Package org.c02e.jpgpj

Class Key

  • All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    KeyForDecryption, KeyForEncryption, KeyForSigning, KeyForVerification
    public class Key
extends java.lang.Object
implements java.lang.Cloneable
    The identity of a person (or persona, or non-human actor, etc) as a collection of Subkeys. A key whose subkeys contain only the public part of their public-key pair is considered a "public key"; whereas a key whose subkeys contain both the public part and private part their public-key pair is considered a "secret key".

    A key can be constructed from an armored key text block with the Key(String) constructor; or constructed from a key file with the Key(File) constructor; or constructed from an input stream containing a key file (or armored key text block) with the Key(InputStream) constructor. A key can also be constructed as an empty key (Key()) and the key loaded later — either via load(String), load(File), or load(InputStream)); or by adding individual Subkeys to the list of subkeys that can be accessed via getSubkeys().

    The purposes for which a key can be used are indicated by these four methods:

    The subkey to use for each purpose is made available by these four methods:

    You can list the key's user IDs (the human-readable identification of the key, like "Alice (work) alice@example.com") via the getUids() method. When signing with a key that includes multiple user IDs, you can specify the user ID to embed in the signature via the setSigningUid(java.lang.String) method (otherwise this defaults to the first user ID; also note that when verifying the message, other clients may ignore this setting, and display an arbitrary user ID, or all user IDs, as the message signer).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String NO_PASSPHRASE
      Use this value to set the passphrase of a passphrase-less key.
      protected java.lang.String signingUid  
      protected java.util.List<Subkey> subkeys  

    • Constructor Summary

      Constructors 
      Constructor Description
      Key()
      Constructs a new empty key.
      Key​(java.io.File file)
      Loads first key from the specified file.
      Key​(java.io.File file, char[] passphraseChars)
      Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.io.File file, java.lang.String passphrase)
      Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.io.InputStream stream)
      Loads first key from the specified input stream.
      Key​(java.io.InputStream stream, char[] passphraseChars)
      Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.io.InputStream stream, java.lang.String passphrase)
      Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.lang.String armor)
      Loads first key from the specified armored text.
      Key​(java.lang.String armor, char[] passphraseChars)
      Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.lang.String armor, java.lang.String passphrase)
      Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.
      Key​(java.util.List<Subkey> subkeys)
      Constructs a new key with the specified subkeys.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clearSecrets()
      Zeroes-out the cached passphrase for all subkeys, and releases the extracted private key material for garbage collection.
      Key clone()  
      java.util.List<Subkey> findAll​(java.lang.String id)
      All subkeys for which the specified string is a case-insensitive substring of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      java.util.List<Subkey> findAll​(java.util.regex.Pattern id)
      All subkeys for which the specified pattern matches any part of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      Subkey findById​(java.lang.Long id)
      Subkey with the specified full ID, or null.
      Subkey getDecryption()
      Last subkey that can decrypt, or null.
      Subkey getEncryption()
      Last subkey that can encrypt, or null.
      Subkey getMaster()
      First subkey or null.
      Subkey getSigning()
      Last subkey that can sign, or null.
      java.lang.String getSigningUid()
      User ID to use for signing, or empty string.
      java.util.List<Subkey> getSubkeys()
      All subkeys, or an empty list.
      java.util.List<java.lang.String> getUids()
      User ID strings for master subkey (ex ["My Name (comment) <me@example.com>"]).
      Subkey getVerification()
      Last subkey that can verify, or null.
      boolean isForDecryption()
      True if any subkey can be used for decryption.
      boolean isForEncryption()
      True if any subkey can be used for encryption.
      boolean isForSigning()
      True if any subkey can be used for signing.
      boolean isForVerification()
      True if any subkey can be used for verification.
      void load​(java.io.File file)
      Loads first key from the specified file.
      void load​(java.io.InputStream stream)
      Loads first key from the specified input stream.
      void load​(java.lang.String armor)
      Loads first key from the specified armored text.
      boolean matches​(java.lang.String id)
      True if the string is a case-insensitive substring of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      boolean matches​(java.util.regex.Pattern id)
      True if the specified pattern matches any part of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")
      protected Ring newRing()  
      void setNoPassphrase​(boolean x)
      True to flag all subkeys as needing no passphrase to unlock; false to require a passphrase to be (re-)set on all subkeys.
      void setPassphrase​(java.lang.String x)
      Sets the passphrase of all subkeys.
      void setPassphraseChars​(char[] x)
      Sets the passphrase of all subkeys.
      void setSigningUid​(java.lang.String x)
      User ID to use for signing, or empty string.
      protected void setSubkeys​(java.util.List<Subkey> x)
      All subkeys, or an empty list.
      Key toPublicKey()
      Creates a copy of this with only the public parts of the key.
      java.lang.String toString()
      Display string for the key, including each subkey's usage flags, short ID, and user IDs.

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • NO_PASSPHRASE

        public static java.lang.String NO_PASSPHRASE
        Use this value to set the passphrase of a passphrase-less key.

      • signingUid

        protected java.lang.String signingUid

      • subkeys

        protected java.util.List<Subkey> subkeys

    • Constructor Detail

      • Key

        public Key()
        Constructs a new empty key.

      • Key

        public Key​(java.util.List<Subkey> subkeys)
        Constructs a new key with the specified subkeys.

      • Key

        public Key​(java.lang.String armor)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified armored text.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the text contains no keys.
        java.io.IOException

      • Key

        public Key​(java.lang.String armor,
           char[] passphraseChars)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the text contains no keys.
        java.io.IOException

      • Key

        public Key​(java.lang.String armor,
           java.lang.String passphrase)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase. Prefer Key(String, char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the text contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.File file)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified file.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the file contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.File file,
           char[] passphraseChars)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the file contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.File file,
           java.lang.String passphrase)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase. Prefer Key(File, char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the file contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.InputStream stream)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified input stream.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the input streame contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.InputStream stream,
           char[] passphraseChars)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the input streame contains no keys.
        java.io.IOException

      • Key

        public Key​(java.io.InputStream stream,
           java.lang.String passphrase)
    throws java.io.IOException,
           org.bouncycastle.openpgp.PGPException
        Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase. Prefer Key(InputStream, char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the input streame contains no keys.
        java.io.IOException

    • Method Detail

      • toPublicKey

        public Key toPublicKey()
                throws org.bouncycastle.openpgp.PGPException
        Creates a copy of this with only the public parts of the key.
        Throws:
        org.bouncycastle.openpgp.PGPException

      • toString

        public java.lang.String toString()
        Display string for the key, including each subkey's usage flags, short ID, and user IDs.
        Overrides:
        toString in class java.lang.Object

      • clone

        public Key clone()
        Overrides:
        clone in class java.lang.Object

      • setNoPassphrase

        public void setNoPassphrase​(boolean x)
        True to flag all subkeys as needing no passphrase to unlock; false to require a passphrase to be (re-)set on all subkeys.

      • getUids

        public java.util.List<java.lang.String> getUids()
        User ID strings for master subkey (ex ["My Name (comment) <me@example.com>"]).

      • getSigningUid

        public java.lang.String getSigningUid()
        User ID to use for signing, or empty string. By default, this is first user ID listed by the master subkey.

      • setSigningUid

        public void setSigningUid​(java.lang.String x)
        User ID to use for signing, or empty string.

      • isForSigning

        public boolean isForSigning()
        True if any subkey can be used for signing.

      • isForVerification

        public boolean isForVerification()
        True if any subkey can be used for verification.

      • isForEncryption

        public boolean isForEncryption()
        True if any subkey can be used for encryption.

      • isForDecryption

        public boolean isForDecryption()
        True if any subkey can be used for decryption.

      • getMaster

        public Subkey getMaster()
        First subkey or null.

      • getSigning

        public Subkey getSigning()
        Last subkey that can sign, or null.

      • getVerification

        public Subkey getVerification()
        Last subkey that can verify, or null.

      • getEncryption

        public Subkey getEncryption()
        Last subkey that can encrypt, or null.

      • getDecryption

        public Subkey getDecryption()
        Last subkey that can decrypt, or null.

      • getSubkeys

        public java.util.List<Subkey> getSubkeys()
        All subkeys, or an empty list.

      • setSubkeys

        protected void setSubkeys​(java.util.List<Subkey> x)
        All subkeys, or an empty list.

      • findById

        public Subkey findById​(java.lang.Long id)
        Subkey with the specified full ID, or null.

      • findAll

        public java.util.List<Subkey> findAll​(java.lang.String id)
        All subkeys for which the specified string is a case-insensitive substring of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a string "0x1234" would match the above full ID; a string "90ab" would match the above fingerprint; and a string "alice (work)" would match the above user ID.

      • findAll

        public java.util.List<Subkey> findAll​(java.util.regex.Pattern id)
        All subkeys for which the specified pattern matches any part of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a pattern /0x1234/ would match the above full ID; a pattern /(?i)90ab/ would match the above fingerprint; and a pattern /Alice .work./ would match the above user ID.

      • matches

        public boolean matches​(java.lang.String id)
        True if the string is a case-insensitive substring of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a string "0x1234" would match the above full ID; a string "90ab" would match the above fingerprint; and a string "alice (work)" would match the above user ID.

      • matches

        public boolean matches​(java.util.regex.Pattern id)
        True if the specified pattern matches any part of either:
        • any subkey's full ID (eg "0x1234567890ABCDEF")
        • any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
        • any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")

        So for example, a pattern /0x1234/ would match the above full ID; a pattern /(?i)90ab/ would match the above fingerprint; and a pattern /Alice .work./ would match the above user ID.

      • clearSecrets

        public void clearSecrets()
        Zeroes-out the cached passphrase for all subkeys, and releases the extracted private key material for garbage collection. Note that if setPassphrase(java.lang.String) is used to access the passphrase, the passphrase data cannot be zeroed (so instead use setPassphraseChars(char[])).

      • load

        public void load​(java.lang.String armor)
          throws java.io.IOException,
                 org.bouncycastle.openpgp.PGPException
        Loads first key from the specified armored text.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the text contains no keys.
        java.io.IOException

      • load

        public void load​(java.io.File file)
          throws java.io.IOException,
                 org.bouncycastle.openpgp.PGPException
        Loads first key from the specified file.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the file contains no keys.
        java.io.IOException

      • load

        public void load​(java.io.InputStream stream)
          throws java.io.IOException,
                 org.bouncycastle.openpgp.PGPException
        Loads first key from the specified input stream.
        Throws:
        org.bouncycastle.openpgp.PGPException - if the input streame contains no keys.
        java.io.IOException

      • newRing

        protected Ring newRing()