Class Subkey
- java.lang.Object
-
- org.c02e.jpgpj.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 fullKey
. 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, itsforSigning
property will also be set to true. When a subkey with a "encrypt communications" or "encrypt storage" flag is loaded, itsforEncryption
property will be set to true; and if the subkey includes the private part of its public-key pair, itsforDecryption
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 theKey.setPassphraseChars(char[])
on its containingKey
. If the subkey does not have a passphrase, set the passphrase to theKey.NO_PASSPHRASE
constant (or usesetNoPassphrase(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[] viasetPassphraseChars(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 viasetPassphrase(java.lang.String)
).
-
-
Field Summary
Fields Modifier and Type Field Description private static char[]
EMPTY_PASSPHRASE
protected boolean
forDecryption
protected boolean
forEncryption
protected boolean
forSigning
protected boolean
forVerification
private static char[]
NO_PASSPHRASE
protected java.lang.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
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 untilclearSecrets()
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 castlePGPKeyFlags
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 untilclearSecrets()
is called.
-
-
-
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.
-
-
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 classjava.lang.Object
-
clone
public Subkey clone()
- Overrides:
clone
in classjava.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[]. 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
public java.lang.String 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:
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. 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:
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 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
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 castlePGPKeyFlags
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 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.PGPException
Sets forSigning etc flags based on key data.- Throws:
org.bouncycastle.openpgp.PGPException
-
-