Subkey (JPGPJ 1.3 API)

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 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:
- isForSigning(): true if should be used for signing messages
- isForVerification(): true if should be used for verifying messages
- isForEncryption(): true if should be used for encrypting messages
- isForDecryption(): 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)).

Constructor Summary

Constructors
Constructor and Description

Subkey()
Constructs a blank subkey.

Constructors
Constructor and Description
`Subkey()` Constructs a blank subkey.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearSecrets()` Zeroes-out the cached passphrase for this subkey, and releases the extracted private key material for garbage collection.
`Subkey`	`clone()`
`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.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>")
`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>")
`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, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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
  - 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(java.lang.String) is used to access the passphrase, the passphrase data cannot be zeroed (so instead use getPassphraseChars() and setPassphraseChars(char[])).

Class Subkey

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Subkey

Method Detail

toString

clone

isForSigning

setForSigning

isForVerification

setForVerification

isForEncryption

setForEncryption

isForDecryption

setForDecryption

isUsableForSigning

isUsableForVerification

isUsableForEncryption

isUsableForDecryption

getPassphraseChars

setPassphraseChars

getPassphrase

setPassphrase

isNoPassphrase

setNoPassphrase

getPublicKey

setPublicKey

getSecretKey

setSecretKey

getPrivateKey

getFingerprint

getId

getShortId

getUids

getUsageFlags

matches

matches

isUnlocked

unlock

clearSecrets