Class Subkey

java.lang.Object
org.c02e.jpgpj.Subkey
All Implemented Interfaces:
Cloneable
public class Subkey extends Object implements Cloneable
A single public-key pair from a full Key. It may consist of only the public part of the pair, or it may include both the public and private parts. Each subkey is designated for a specific cryptographic purpose (or purposes), typically either certification (ie signing other keys), encryption, or signing (ie signing messages). The passphrase for a subkey must be provided in order to use its private part (the private part is needed for signing and decryption).

The purpose of a subkey is indicated by these four methods:

By default, when a subkey with a "sign data" flag is loaded, its forVerification property will be set to true; and if the subkey includes the private part of its public-key pair, its forSigning property will also be set to true. When a subkey with a "encrypt communications" or "encrypt storage" flag is loaded, its forEncryption property will be set to true; and if the subkey includes the private part of its public-key pair, its forDecryption property will also be set to true.

However, before actually using a subkey for signing or decryption, you must also set the subkey's passphrase, either via the setPassphraseChars(char[]) method on the subkey, or the Key.setPassphraseChars(char[]) on its containing Key. If the subkey does not have a passphrase, set the passphrase to the Key.NO_PASSPHRASE constant (or use setNoPassphrase(boolean)).

When a subkey is used for signing or decryption, its private key material is extracted and cached in memory. To release this memory, call the subkey's clearSecrets() method. This method will zero-out the subkey's passphrase (if the passphrase had been set as a char[] via setPassphraseChars(char[])) and release the cached private key material (however, the private key material will not be zeroed-out; also, the passphrase will not be zeroed-out if it was set via setPassphrase(String)).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final char[]
    EMPTY_PASSPHRASE
     
    protected boolean
    forDecryption
     
    protected boolean
    forEncryption
     
    protected boolean
    forSigning
     
    protected boolean
    forVerification
     
    private static final char[]
    NO_PASSPHRASE
     
    protected String
    passphrase
    Deprecated.
    Null unless explicitly set by user.
    protected char[]
    passphraseChars
     
    protected org.bouncycastle.openpgp.PGPPrivateKey
    privateKey
    Decrypted private key material.
    protected org.bouncycastle.openpgp.PGPPublicKey
    publicKey
     
    protected org.bouncycastle.openpgp.PGPSecretKey
    secretKey
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Subkey()
    Constructs a blank subkey.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor
    buildDecryptor(char[] passphraseChars)
    Builds a secret key decryptor for the specified passphrase.
    protected void
    calculateUsage()
    Sets forSigning etc flags based on key data.
    void
    clearSecrets()
    Zeroes-out the cached passphrase for this subkey, and releases the extracted private key material for garbage collection.
    Subkey
    clone()
     
    protected org.bouncycastle.openpgp.PGPPrivateKey
    extractPrivateKey(char[] passphraseChars)
    Extracts the private key from this subkey's secret key using the specified passphrase.
    String
    getFingerprint()
    Fingerprint of public key, or empty string if no public key.
    String
    getId()
    Full '0xlong' format of public key, or empty string if no public key.
    String
    getPassphrase()
    Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string.
    char[]
    getPassphraseChars()
    Passphrase needed to unlock the private part of the subkey's public key-pair; or empty char[].
    org.bouncycastle.openpgp.PGPPrivateKey
    getPrivateKey()
    Extracts the Bouncy castle private-key material from this subkey's secret key, using the subkey's passphrase, and caches it in memory until clearSecrets() is called.
    org.bouncycastle.openpgp.PGPPublicKey
    getPublicKey()
    Bouncy castle public-key pair, containing only the public part of the pair; or null.
    org.bouncycastle.openpgp.PGPSecretKey
    getSecretKey()
    Bouncy castle public-key pair, containing both the public and private parts of the pair; or null.
    String
    getShortId()
    Abbreviated 'short' format of public key, or empty string if no public key.
    List<String>
    getUids()
    User ID strings of public key (ex ["My Name (comment) <me@example.com>"]), or empty list.
    int
    getUsageFlags()
    Usage flags as Bouncy castle PGPKeyFlags bits.
    boolean
    isForDecryption()
    True if the subkey should be used for decrypting messages.
    boolean
    isForEncryption()
    True if the subkey should be used for encrypting messages.
    boolean
    isForSigning()
    True if the subkey should be used for signing messages.
    boolean
    isForVerification()
    True if the subkey should be used for verifying messages.
    boolean
    isNoPassphrase()
    True if no passphrase is needed to unlock the private part of the subkey's public key-pair.
    boolean
    isUnlocked()
    True if the private key material has been extracted from this subkey's secret key and is currently cached in memory.
    boolean
    isUsableForDecryption()
    True if technically usable for decryption.
    boolean
    isUsableForEncryption()
    True if technically usable for encryption.
    boolean
    isUsableForSigning()
    True if technically usable for signing.
    boolean
    isUsableForVerification()
    True if technically usable for verification.
    boolean
    matches(String id)
    True if the string is a case-insensitive substring of either: the subkey's full ID (eg "0x1234567890ABCDEF"); the subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678"); 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: the subkey's full ID (eg "0x1234567890ABCDEF"); the subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678"); any subkey's user IDs (eg "Alice (work) <alice@example.com>")
    void
    setForDecryption(boolean x)
    True if the subkey should be used for decrypting messages.
    void
    setForEncryption(boolean x)
    True if the subkey should be used for encrypting messages.
    void
    setForSigning(boolean x)
    True if the subkey should be used for signing messages.
    void
    setForVerification(boolean x)
    True if the subkey should be used for verifying messages.
    void
    setNoPassphrase(boolean x)
    True if no passphrase is needed to unlock the private part of the subkey's public key-pair.
    void
    setPassphrase(String x)
    Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string.
    void
    setPassphraseChars(char[] x)
    Passphrase needed to unlock the private part of the subkey's public key-pair; or empty char[].
    void
    setPublicKey(org.bouncycastle.openpgp.PGPPublicKey x)
    Bouncy castle public-key pair, containing only the public part of the pair; or null.
    void
    setSecretKey(org.bouncycastle.openpgp.PGPSecretKey x)
    Bouncy castle public-key pair, containing both the public and private parts of the pair; or null.
    String
    toString()
    Display string for the subkey, including its usage flags, short ID, and user IDs.
    void
    unlock(char[] passphraseChars)
    Extracts the private key material from this subkey's secret key using the specified passphrase, and caches it in memory until clearSecrets() is called.

    Methods inherited from class Object

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

  • Field Details

    • NO_PASSPHRASE

      private static final char[] NO_PASSPHRASE

    • EMPTY_PASSPHRASE

      private static final char[] EMPTY_PASSPHRASE

    • forSigning

      protected boolean forSigning

    • forVerification

      protected boolean forVerification

    • forEncryption

      protected boolean forEncryption

    • forDecryption

      protected boolean forDecryption

    • passphraseChars

      protected char[] passphraseChars

    • passphrase

      @Deprecated protected String passphrase
      Deprecated.
      Null unless explicitly set by user.

    • publicKey

      protected org.bouncycastle.openpgp.PGPPublicKey publicKey

    • secretKey

      protected org.bouncycastle.openpgp.PGPSecretKey secretKey

    • privateKey

      protected org.bouncycastle.openpgp.PGPPrivateKey privateKey
      Decrypted private key material. Null unless decrypted.

  • Constructor Details

    • Subkey

      public Subkey()
      Constructs a blank subkey.

  • Method Details

    • toString

      public String toString()
      Display string for the subkey, including its usage flags, short ID, and user IDs.
      Overrides:
      toString in class Object

    • clone

      public Subkey clone()
      Overrides:
      clone in class Object

    • isForSigning

      public boolean isForSigning()
      True if the subkey should be used for signing messages.

    • setForSigning

      public void setForSigning(boolean x)
      True if the subkey should be used for signing messages.

    • isForVerification

      public boolean isForVerification()
      True if the subkey should be used for verifying messages.

    • setForVerification

      public void setForVerification(boolean x)
      True if the subkey should be used for verifying messages.

    • isForEncryption

      public boolean isForEncryption()
      True if the subkey should be used for encrypting messages.

    • setForEncryption

      public void setForEncryption(boolean x)
      True if the subkey should be used for encrypting messages.

    • isForDecryption

      public boolean isForDecryption()
      True if the subkey should be used for decrypting messages.

    • setForDecryption

      public void setForDecryption(boolean x)
      True if the subkey should be used for decrypting messages.

    • isUsableForSigning

      public boolean isUsableForSigning()
      True if technically usable for signing.

    • isUsableForVerification

      public boolean isUsableForVerification()
      True if technically usable for verification.

    • isUsableForEncryption

      public boolean isUsableForEncryption()
      True if technically usable for encryption.

    • isUsableForDecryption

      public boolean isUsableForDecryption()
      True if technically usable for decryption.

    • getPassphraseChars

      public char[] getPassphraseChars()
      Passphrase needed to unlock the private part of the subkey's public key-pair; or empty char[]. Use Key.NO_PASSPHRASE to signal the private part of the subkey is not protected by a passphrase. Note that this char[] itself (and not a copy) will be cached and used by the subkey until clearSecrets() is called (or setPassphraseChars(char[]) is called again with a different passphrase), and then the char[] will be zeroed.

    • setPassphraseChars

      public void setPassphraseChars(char[] x)
      Passphrase needed to unlock the private part of the subkey's public key-pair; or empty char[]. Use Key.NO_PASSPHRASE to signal the private part of the subkey is not protected by a passphrase. Note that this char[] itself (and not a copy) will be cached and used by the subkey until clearSecrets() is called (or setPassphraseChars(char[]) is called again with a different passphrase), and then the char[] will be zeroed.

    • getPassphrase

      public String getPassphrase()
      Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string. Prefer getPassphraseChars() to avoid creating extra copies of the passphrase in memory that cannot be cleaned up. Use Key.NO_PASSPHRASE to signal the private part of the subkey is not protected by a passphrase.
      See Also:

    • setPassphrase

      public void setPassphrase(String x)
      Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string. Prefer setPassphraseChars(char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up. Use Key.NO_PASSPHRASE to signal the private part of the subkey is not protected by a passphrase.
      See Also:

    • isNoPassphrase

      public boolean isNoPassphrase()
      True if no passphrase is needed to unlock the private part of the subkey's public key-pair.

    • setNoPassphrase

      public void setNoPassphrase(boolean x)
      True if no passphrase is needed to unlock the private part of the subkey's public key-pair.

    • getPublicKey

      public org.bouncycastle.openpgp.PGPPublicKey getPublicKey()
      Bouncy castle public-key pair, containing only the public part of the pair; or null.

    • setPublicKey

      public void setPublicKey(org.bouncycastle.openpgp.PGPPublicKey x) throws org.bouncycastle.openpgp.PGPException
      Bouncy castle public-key pair, containing only the public part of the pair; or null.
      Throws:
      org.bouncycastle.openpgp.PGPException

    • getSecretKey

      public org.bouncycastle.openpgp.PGPSecretKey getSecretKey()
      Bouncy castle public-key pair, containing both the public and private parts of the pair; or null.

    • setSecretKey

      public void setSecretKey(org.bouncycastle.openpgp.PGPSecretKey x) throws org.bouncycastle.openpgp.PGPException
      Bouncy castle public-key pair, containing both the public and private parts of the pair; or null.
      Throws:
      org.bouncycastle.openpgp.PGPException

    • getPrivateKey

      public org.bouncycastle.openpgp.PGPPrivateKey getPrivateKey() throws org.bouncycastle.openpgp.PGPException
      Extracts the Bouncy castle private-key material from this subkey's secret key, using the subkey's passphrase, and caches it in memory until clearSecrets() is called.
      Returns:
      null if this subkey does not have a secret key.
      Throws:
      PassphraseException - if passphrase is incorrect.
      org.bouncycastle.openpgp.PGPException

    • getFingerprint

      public String getFingerprint()
      Fingerprint of public key, or empty string if no public key.

    • getId

      public String getId()
      Full '0xlong' format of public key, or empty string if no public key.

    • getShortId

      public String getShortId()
      Abbreviated 'short' format of public key, or empty string if no public key.

    • getUids

      public List<String> getUids()
      User ID strings of public key (ex ["My Name (comment) <me@example.com>"]), or empty list.

    • getUsageFlags

      public int getUsageFlags() throws org.bouncycastle.openpgp.PGPException
      Usage flags as Bouncy castle PGPKeyFlags bits.
      Throws:
      org.bouncycastle.openpgp.PGPException

    • matches

      public boolean matches(String id)
      True if the string is a case-insensitive substring of either:
      • the subkey's full ID (eg "0x1234567890ABCDEF");
      • the subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678");
      • 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:
      • the subkey's full ID (eg "0x1234567890ABCDEF");
      • the subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678");
      • 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.

    • isUnlocked

      public boolean isUnlocked()
      True if the private key material has been extracted from this subkey's secret key and is currently cached in memory.

    • unlock

      public void unlock(char[] passphraseChars) throws org.bouncycastle.openpgp.PGPException
      Extracts the private key material from this subkey's secret key using the specified passphrase, and caches it in memory until clearSecrets() is called. Does not cache the passphrase. Does nothing if this subkey does not have a secret key.
      Throws:
      PassphraseException - if passphrase is incorrect.
      org.bouncycastle.openpgp.PGPException

    • clearSecrets

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

    • extractPrivateKey

      protected org.bouncycastle.openpgp.PGPPrivateKey extractPrivateKey(char[] passphraseChars) throws org.bouncycastle.openpgp.PGPException
      Extracts the private key from this subkey's secret key using the specified passphrase.
      Throws:
      org.bouncycastle.openpgp.PGPException

    • buildDecryptor

      protected org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor buildDecryptor(char[] passphraseChars) throws org.bouncycastle.openpgp.PGPException
      Builds a secret key decryptor for the specified passphrase.
      Throws:
      org.bouncycastle.openpgp.PGPException

    • calculateUsage

      protected void calculateUsage() throws org.bouncycastle.openpgp.PGPException
      Sets forSigning etc flags based on key data.
      Throws:
      org.bouncycastle.openpgp.PGPException