Class Subkey
- All Implemented Interfaces:
Cloneable
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:
isForSigning()
: true if should be used for signing messagesisForVerification()
: true if should be used for verifying messagesisForEncryption()
: true if should be used for encrypting messagesisForDecryption()
: true if should be used for decrypting messages
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)
).
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final char[]
protected boolean
protected boolean
protected boolean
protected boolean
private static final char[]
protected String
Deprecated.Null unless explicitly set by user.protected char[]
protected org.bouncycastle.openpgp.PGPPrivateKey
Decrypted private key material.protected org.bouncycastle.openpgp.PGPPublicKey
protected org.bouncycastle.openpgp.PGPSecretKey
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor
buildDecryptor
(char[] passphraseChars) Builds a secret key decryptor for the specified passphrase.protected void
Sets forSigning etc flags based on key data.void
Zeroes-out the cached passphrase for this subkey, and releases the extracted private key material for garbage collection.clone()
protected org.bouncycastle.openpgp.PGPPrivateKey
extractPrivateKey
(char[] passphraseChars) Extracts the private key from this subkey's secret key using the specified passphrase.Fingerprint of public key, or empty string if no public key.getId()
Full '0xlong' format of public key, or empty string if no public key.Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string.char[]
Passphrase needed to unlock the private part of the subkey's public key-pair; or empty char[].org.bouncycastle.openpgp.PGPPrivateKey
Extracts the Bouncy castle private-key material from this subkey's secret key, using the subkey's passphrase, and caches it in memory untilclearSecrets()
is called.org.bouncycastle.openpgp.PGPPublicKey
Bouncy castle public-key pair, containing only the public part of the pair; or null.org.bouncycastle.openpgp.PGPSecretKey
Bouncy castle public-key pair, containing both the public and private parts of the pair; or null.Abbreviated 'short' format of public key, or empty string if no public key.getUids()
User ID strings of public key (ex ["My Name (comment) <me@example.com>"]), or empty list.int
Usage flags as Bouncy castlePGPKeyFlags
bits.boolean
True if the subkey should be used for decrypting messages.boolean
True if the subkey should be used for encrypting messages.boolean
True if the subkey should be used for signing messages.boolean
True if the subkey should be used for verifying messages.boolean
True if no passphrase is needed to unlock the private part of the subkey's public key-pair.boolean
True if the private key material has been extracted from this subkey's secret key and is currently cached in memory.boolean
True if technically usable for decryption.boolean
True if technically usable for encryption.boolean
True if technically usable for signing.boolean
True if technically usable for verification.boolean
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
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
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.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 untilclearSecrets()
is called.
-
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.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 privateKeyDecrypted private key material. Null unless decrypted.
-
-
Constructor Details
-
Subkey
public Subkey()Constructs a blank subkey.
-
-
Method Details
-
toString
Display string for the subkey, including its usage flags, short ID, and user IDs. -
clone
-
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[]. UseKey.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 untilclearSecrets()
is called (orsetPassphraseChars(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[]. UseKey.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 untilclearSecrets()
is called (orsetPassphraseChars(char[])
is called again with a different passphrase), and then the char[] will be zeroed. -
getPassphrase
Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string. PrefergetPassphraseChars()
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up. UseKey.NO_PASSPHRASE
to signal the private part of the subkey is not protected by a passphrase.- See Also:
-
setPassphrase
Passphrase needed to unlock the private part of the subkey's public key-pair; or empty string. PrefersetPassphraseChars(char[])
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up. UseKey.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.PGPExceptionExtracts the Bouncy castle private-key material from this subkey's secret key, using the subkey's passphrase, and caches it in memory untilclearSecrets()
is called.- Returns:
- null if this subkey does not have a secret key.
- Throws:
PassphraseException
- if passphrase is incorrect.org.bouncycastle.openpgp.PGPException
-
getFingerprint
Fingerprint of public key, or empty string if no public key. -
getId
Full '0xlong' format of public key, or empty string if no public key. -
getShortId
Abbreviated 'short' format of public key, or empty string if no public key. -
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.PGPExceptionUsage flags as Bouncy castlePGPKeyFlags
bits.- Throws:
org.bouncycastle.openpgp.PGPException
-
matches
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
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 untilclearSecrets()
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 ifgetPassphrase()
orsetPassphrase(java.lang.String)
is used to access the passphrase, the passphrase data cannot be zeroed (so instead usegetPassphraseChars()
andsetPassphraseChars(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.PGPExceptionSets forSigning etc flags based on key data.- Throws:
org.bouncycastle.openpgp.PGPException
-