Class Key
- java.lang.Object
-
- org.c02e.jpgpj.Key
-
- All Implemented Interfaces:
java.lang.Cloneable
- Direct Known Subclasses:
KeyForDecryption
,KeyForEncryption
,KeyForSigning
,KeyForVerification
public class Key extends java.lang.Object implements java.lang.Cloneable
The identity of a person (or persona, or non-human actor, etc) as a collection ofSubkey
s. A key whose subkeys contain only the public part of their public-key pair is considered a "public key"; whereas a key whose subkeys contain both the public part and private part their public-key pair is considered a "secret key".A key can be constructed from an armored key text block with the
Key(String)
constructor; or constructed from a key file with theKey(File)
constructor; or constructed from an input stream containing a key file (or armored key text block) with theKey(InputStream)
constructor. A key can also be constructed as an empty key (Key()
) and the key loaded later — either viaload(String)
,load(File)
, orload(InputStream)
); or by adding individualSubkey
s to the list of subkeys that can be accessed viagetSubkeys()
.The purposes for which a key can be used are indicated by these four methods:
isForSigning()
: true if can be used for signing messagesisForVerification()
: true if can be used for verifying messagesisForEncryption()
: true if can be used for encrypting messagesisForDecryption()
: true if can be used for decrypting messages
The subkey to use for each purpose is made available by these four methods:
getSigning()
: subkey to use for signing messages, or nullgetVerification()
: subkey to use for verifying messages, or nullgetEncryption()
: subkey to use for encrypting messages, or nullgetDecryption()
: subkey to use for decrypting messages, or null
You can list the key's user IDs (the human-readable identification of the key, like "Alice (work) alice@example.com") via the
getUids()
method. When signing with a key that includes multiple user IDs, you can specify the user ID to embed in the signature via thesetSigningUid(java.lang.String)
method (otherwise this defaults to the first user ID; also note that when verifying the message, other clients may ignore this setting, and display an arbitrary user ID, or all user IDs, as the message signer).
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
NO_PASSPHRASE
Use this value to set the passphrase of a passphrase-less key.protected java.lang.String
signingUid
protected java.util.List<Subkey>
subkeys
-
Constructor Summary
Constructors Constructor Description Key()
Constructs a new empty key.Key(java.io.File file)
Loads first key from the specified file.Key(java.io.File file, char[] passphraseChars)
Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.Key(java.io.File file, java.lang.String passphrase)
Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.Key(java.io.InputStream stream)
Loads first key from the specified input stream.Key(java.io.InputStream stream, char[] passphraseChars)
Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.Key(java.io.InputStream stream, java.lang.String passphrase)
Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.Key(java.lang.String armor)
Loads first key from the specified armored text.Key(java.lang.String armor, char[] passphraseChars)
Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.Key(java.lang.String armor, java.lang.String passphrase)
Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.Key(java.util.List<Subkey> subkeys)
Constructs a new key with the specified subkeys.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clearSecrets()
Zeroes-out the cached passphrase for all subkeys, and releases the extracted private key material for garbage collection.Key
clone()
java.util.List<Subkey>
findAll(java.lang.String id)
All subkeys for which the specified string is a case-insensitive substring of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")java.util.List<Subkey>
findAll(java.util.regex.Pattern id)
All subkeys for which the specified pattern matches any part of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")Subkey
findById(java.lang.Long id)
Subkey with the specified full ID, or null.Subkey
getDecryption()
Last subkey that can decrypt, or null.Subkey
getEncryption()
Last subkey that can encrypt, or null.Subkey
getMaster()
First subkey or null.Subkey
getSigning()
Last subkey that can sign, or null.java.lang.String
getSigningUid()
User ID to use for signing, or empty string.java.util.List<Subkey>
getSubkeys()
All subkeys, or an empty list.java.util.List<java.lang.String>
getUids()
User ID strings for master subkey (ex ["My Name (comment) <me@example.com>"]).Subkey
getVerification()
Last subkey that can verify, or null.boolean
isForDecryption()
True if any subkey can be used for decryption.boolean
isForEncryption()
True if any subkey can be used for encryption.boolean
isForSigning()
True if any subkey can be used for signing.boolean
isForVerification()
True if any subkey can be used for verification.void
load(java.io.File file)
Loads first key from the specified file.void
load(java.io.InputStream stream)
Loads first key from the specified input stream.void
load(java.lang.String armor)
Loads first key from the specified armored text.boolean
matches(java.lang.String id)
True if the string is a case-insensitive substring of either: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of 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: any subkey's full ID (eg "0x1234567890ABCDEF") any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678") any one of any subkey's user IDs (eg "Alice (work) <alice@example.com>")protected Ring
newRing()
void
setNoPassphrase(boolean x)
True to flag all subkeys as needing no passphrase to unlock; false to require a passphrase to be (re-)set on all subkeys.void
setPassphrase(java.lang.String x)
Sets the passphrase of all subkeys.void
setPassphraseChars(char[] x)
Sets the passphrase of all subkeys.void
setSigningUid(java.lang.String x)
User ID to use for signing, or empty string.protected void
setSubkeys(java.util.List<Subkey> x)
All subkeys, or an empty list.Key
toPublicKey()
Creates a copy of this with only the public parts of the key.java.lang.String
toString()
Display string for the key, including each subkey's usage flags, short ID, and user IDs.
-
-
-
Field Detail
-
NO_PASSPHRASE
public static java.lang.String NO_PASSPHRASE
Use this value to set the passphrase of a passphrase-less key.
-
signingUid
protected java.lang.String signingUid
-
subkeys
protected java.util.List<Subkey> subkeys
-
-
Constructor Detail
-
Key
public Key()
Constructs a new empty key.
-
Key
public Key(java.util.List<Subkey> subkeys)
Constructs a new key with the specified subkeys.
-
Key
public Key(java.lang.String armor) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified armored text.- Throws:
org.bouncycastle.openpgp.PGPException
- if the text contains no keys.java.io.IOException
-
Key
public Key(java.lang.String armor, char[] passphraseChars) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase.- Throws:
org.bouncycastle.openpgp.PGPException
- if the text contains no keys.java.io.IOException
-
Key
public Key(java.lang.String armor, java.lang.String passphrase) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified armored text, and sets the passphrase of all subkeys to the specified passphrase. PreferKey(String, char[])
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.- Throws:
org.bouncycastle.openpgp.PGPException
- if the text contains no keys.java.io.IOException
-
Key
public Key(java.io.File file) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified file.- Throws:
org.bouncycastle.openpgp.PGPException
- if the file contains no keys.java.io.IOException
-
Key
public Key(java.io.File file, char[] passphraseChars) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase.- Throws:
org.bouncycastle.openpgp.PGPException
- if the file contains no keys.java.io.IOException
-
Key
public Key(java.io.File file, java.lang.String passphrase) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified file, and sets the passphrase of all subkeys to the specified passphrase. PreferKey(File, char[])
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.- Throws:
org.bouncycastle.openpgp.PGPException
- if the file contains no keys.java.io.IOException
-
Key
public Key(java.io.InputStream stream) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified input stream.- Throws:
org.bouncycastle.openpgp.PGPException
- if the input streame contains no keys.java.io.IOException
-
Key
public Key(java.io.InputStream stream, char[] passphraseChars) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase.- Throws:
org.bouncycastle.openpgp.PGPException
- if the input streame contains no keys.java.io.IOException
-
Key
public Key(java.io.InputStream stream, java.lang.String passphrase) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified input stream, and sets the passphrase of all subkeys to the specified passphrase. PreferKey(InputStream, char[])
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.- Throws:
org.bouncycastle.openpgp.PGPException
- if the input streame contains no keys.java.io.IOException
-
-
Method Detail
-
toPublicKey
public Key toPublicKey() throws org.bouncycastle.openpgp.PGPException
Creates a copy of this with only the public parts of the key.- Throws:
org.bouncycastle.openpgp.PGPException
-
toString
public java.lang.String toString()
Display string for the key, including each subkey's usage flags, short ID, and user IDs.- Overrides:
toString
in classjava.lang.Object
-
clone
public Key clone()
- Overrides:
clone
in classjava.lang.Object
-
setPassphraseChars
public void setPassphraseChars(char[] x)
Sets the passphrase of all subkeys.- See Also:
Subkey.setPassphraseChars(char[])
-
setPassphrase
public void setPassphrase(java.lang.String x)
Sets the passphrase of all subkeys. PrefersetPassphraseChars(char[])
to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.- See Also:
Subkey.setPassphraseChars(char[])
-
setNoPassphrase
public void setNoPassphrase(boolean x)
True to flag all subkeys as needing no passphrase to unlock; false to require a passphrase to be (re-)set on all subkeys.
-
getUids
public java.util.List<java.lang.String> getUids()
User ID strings for master subkey (ex ["My Name (comment) <me@example.com>"]).
-
getSigningUid
public java.lang.String getSigningUid()
User ID to use for signing, or empty string. By default, this is first user ID listed by the master subkey.
-
setSigningUid
public void setSigningUid(java.lang.String x)
User ID to use for signing, or empty string.
-
isForSigning
public boolean isForSigning()
True if any subkey can be used for signing.
-
isForVerification
public boolean isForVerification()
True if any subkey can be used for verification.
-
isForEncryption
public boolean isForEncryption()
True if any subkey can be used for encryption.
-
isForDecryption
public boolean isForDecryption()
True if any subkey can be used for decryption.
-
getMaster
public Subkey getMaster()
First subkey or null.
-
getSigning
public Subkey getSigning()
Last subkey that can sign, or null.
-
getVerification
public Subkey getVerification()
Last subkey that can verify, or null.
-
getEncryption
public Subkey getEncryption()
Last subkey that can encrypt, or null.
-
getDecryption
public Subkey getDecryption()
Last subkey that can decrypt, or null.
-
getSubkeys
public java.util.List<Subkey> getSubkeys()
All subkeys, or an empty list.
-
setSubkeys
protected void setSubkeys(java.util.List<Subkey> x)
All subkeys, or an empty list.
-
findById
public Subkey findById(java.lang.Long id)
Subkey with the specified full ID, or null.
-
findAll
public java.util.List<Subkey> findAll(java.lang.String id)
All subkeys for which the specified string is a case-insensitive substring of either:- any subkey's full ID (eg "0x1234567890ABCDEF")
- any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
- any one of 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.
-
findAll
public java.util.List<Subkey> findAll(java.util.regex.Pattern id)
All subkeys for which the specified pattern matches any part of either:- any subkey's full ID (eg "0x1234567890ABCDEF")
- any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
- any one of 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.
-
matches
public boolean matches(java.lang.String id)
True if the string is a case-insensitive substring of either:- any subkey's full ID (eg "0x1234567890ABCDEF")
- any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
- any one of 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:- any subkey's full ID (eg "0x1234567890ABCDEF")
- any subkey's fingerprint (eg "1234567890ABCDEF1234567890ABCDEF12345678")
- any one of 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.
-
clearSecrets
public void clearSecrets()
Zeroes-out the cached passphrase for all subkeys, and releases the extracted private key material for garbage collection. Note that ifsetPassphrase(java.lang.String)
is used to access the passphrase, the passphrase data cannot be zeroed (so instead usesetPassphraseChars(char[])
).
-
load
public void load(java.lang.String armor) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified armored text.- Throws:
org.bouncycastle.openpgp.PGPException
- if the text contains no keys.java.io.IOException
-
load
public void load(java.io.File file) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified file.- Throws:
org.bouncycastle.openpgp.PGPException
- if the file contains no keys.java.io.IOException
-
load
public void load(java.io.InputStream stream) throws java.io.IOException, org.bouncycastle.openpgp.PGPException
Loads first key from the specified input stream.- Throws:
org.bouncycastle.openpgp.PGPException
- if the input streame contains no keys.java.io.IOException
-
newRing
protected Ring newRing()
-
-