Class Subkey

  • All Implemented Interfaces:
    java.lang.Cloneable

    public class Subkey
    extends java.lang.Object
    implements java.lang.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(java.lang.String)).

    • Constructor Summary

      Constructors 
      Constructor Description
      Subkey()
      Constructs a blank subkey.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      java.lang.String getFingerprint()
      Fingerprint of public key, or empty string if no public key.
      java.lang.String getId()
      Full '0xlong' format of public key, or empty string if no public key.
      java.lang.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.
      java.lang.String getShortId()
      Abbreviated 'short' format of public key, or empty string if no public key.
      java.util.List<java.lang.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​(java.lang.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​(java.util.regex.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​(java.lang.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.
      java.lang.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 java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • 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 java.lang.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 Detail

      • Subkey

        public Subkey()
        Constructs a blank subkey.
    • Method Detail

      • toString

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

        public Subkey clone()
        Overrides:
        clone in class java.lang.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 java.lang.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:
        getPassphraseChars()
      • setPassphrase

        public void setPassphrase​(java.lang.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:
        setPassphraseChars(char[])
      • 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 java.lang.String getFingerprint()
        Fingerprint of public key, or empty string if no public key.
      • getId

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

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

        public java.util.List<java.lang.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​(java.lang.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​(java.util.regex.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
      • 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