Class Key

java.lang.Object
org.c02e.jpgpj.Key
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
KeyForDecryption, KeyForEncryption, KeyForSigning, KeyForVerification
public class Key extends Object implements 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(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 String
    NO_PASSPHRASE
    Use this value to set the passphrase of a passphrase-less key.
    protected String
    signingUid
     
    protected List<Subkey>
    subkeys
     

  • Constructor Summary

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

  • Method Summary

    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()
     
    List<Subkey>
    findAll(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>")
    List<Subkey>
    findAll(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(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.
    String
    getSigningUid()
    User ID to use for signing, or empty string.
    List<Subkey>
    getSubkeys()
    All subkeys, or an empty list.
    List<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(File file)
    Loads first key from the specified file.
    void
    load(InputStream stream)
    Loads first key from the specified input stream.
    void
    load(String armor)
    Loads first key from the specified armored text.
    boolean
    matches(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(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(String x)
    Sets the passphrase of all subkeys.
    void
    setPassphraseChars(char[] x)
    Sets the passphrase of all subkeys.
    void
    setSigningUid(String x)
    User ID to use for signing, or empty string.
    protected void
    setSubkeys(List<Subkey> x)
    All subkeys, or an empty list.
    Key
    toPublicKey()
    Creates a copy of this with only the public parts of the key.
    String
    toString()
    Display string for the key, including each subkey's usage flags, short ID, and user IDs.

    Methods inherited from class Object

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

  • Field Details

    • NO_PASSPHRASE

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

    • signingUid

      protected String signingUid

    • subkeys

      protected List<Subkey> subkeys

  • Constructor Details

    • Key

      public Key()
      Constructs a new empty key.

    • Key

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

    • Key

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

    • Key

      public Key(String armor, char[] passphraseChars) throws 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.
      IOException

    • Key

      public Key(String armor, String passphrase) throws 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.
      IOException

    • Key

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

    • Key

      public Key(File file, char[] passphraseChars) throws 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.
      IOException

    • Key

      public Key(File file, String passphrase) throws 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.
      IOException

    • Key

      public Key(InputStream stream) throws 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.
      IOException

    • Key

      public Key(InputStream stream, char[] passphraseChars) throws 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.
      IOException

    • Key

      public Key(InputStream stream, String passphrase) throws 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.
      IOException

  • Method Details

    • 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 String toString()
      Display string for the key, including each subkey's usage flags, short ID, and user IDs.
      Overrides:
      toString in class Object

    • clone

      public Key clone()
      Overrides:
      clone in class Object

    • setPassphraseChars

      public void setPassphraseChars(char[] x)
      Sets the passphrase of all subkeys.
      See Also:

    • setPassphrase

      public void setPassphrase(String x)
      Sets the passphrase of all subkeys. Prefer setPassphraseChars(char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.
      See Also:

    • 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 List<String> getUids()
      User ID strings for master subkey (ex ["My Name (comment) <me@example.com>"]).

    • getSigningUid

      public 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(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 List<Subkey> getSubkeys()
      All subkeys, or an empty list.

    • setSubkeys

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

    • findById

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

    • findAll

      public List<Subkey> findAll(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 List<Subkey> findAll(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(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(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(String) is used to access the passphrase, the passphrase data cannot be zeroed (so instead use setPassphraseChars(char[])).

    • load

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

    • load

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

    • load

      public void load(InputStream stream) throws 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.
      IOException

    • newRing

      protected Ring newRing()