org.bouncycastle.openpgp

Class PGPPublicKeyRing

java.lang.Object

org.bouncycastle.openpgp.PGPKeyRing

org.bouncycastle.openpgp.PGPPublicKeyRing

All Implemented Interfaces:

java.lang.Iterable<PGPPublicKey>

Direct Known Subclasses:

BcPGPPublicKeyRing, JcaPGPPublicKeyRing

public class PGPPublicKeyRing
extends PGPKeyRing
implements org.bouncycastle.util.Iterable<PGPPublicKey>

Class to hold a single master public key and its subkeys.

Often PGP keyring files consist of multiple master keys, if you are trying to process or construct one of these you should use the PGPPublicKeyRingCollection class.

Constructor Summary

Constructors

Constructor and Description
PGPPublicKeyRing(byte[] encoding, KeyFingerPrintCalculator fingerPrintCalculator)
PGPPublicKeyRing(java.io.InputStream in, KeyFingerPrintCalculator fingerPrintCalculator)
PGPPublicKeyRing(java.util.List<PGPPublicKey> pubKeys) Base constructor from a list of keys representing a public key ring (a master key and its associated sub-keys).

Method Summary

Modifier and Type	Method and Description
void	encode(java.io.OutputStream outStream)
void	encode(java.io.OutputStream outStream, boolean forTransfer) Encode the key ring to outStream, with trust packets stripped out if forTransfer is true.
byte[]	getEncoded()
byte[]	getEncoded(boolean forTransfer) Return an encoding of the key ring, with trust packets stripped out if forTransfer is true.
byte[]	getEncoded(PacketFormat format)
java.util.Iterator<PGPPublicKey>	getKeysWithSignaturesBy(KeyIdentifier identifier)
java.util.Iterator<PGPPublicKey>	getKeysWithSignaturesBy(long keyID) Return any keys carrying a signature issued by the key represented by keyID.
PGPPublicKey	getPublicKey() Return the first public key in the ring.
PGPPublicKey	getPublicKey(byte[] fingerprint) Return the public key with the passed in fingerprint if it is present.
PGPPublicKey	getPublicKey(KeyIdentifier identifier)
PGPPublicKey	getPublicKey(long keyID) Return the public key referred to by the passed in keyID if it is present.
java.util.Iterator<PGPPublicKey>	getPublicKeys() Return an iterator containing all the public keys.
java.util.Iterator<PGPPublicKey>	getPublicKeys(KeyIdentifier identifier)
static PGPPublicKeyRing	insertPublicKey(PGPPublicKeyRing pubRing, PGPPublicKey pubKey) Returns a new key ring with the public key passed in either added or replacing an existing one.
java.util.Iterator<PGPPublicKey>	iterator() Support method for Iterable where available.
static PGPPublicKeyRing	join(PGPPublicKeyRing first, PGPPublicKeyRing second) Join two copies of the same certificate.
static PGPPublicKeyRing	join(PGPPublicKeyRing first, PGPPublicKeyRing second, boolean joinTrustPackets, boolean allowSubkeySigsOnNonSubkey) Join two copies of the same certificate.
static PGPPublicKeyRing	removePublicKey(PGPPublicKeyRing pubRing, PGPPublicKey pubKey) Returns a new key ring with the public key passed in removed from the key ring.
int	size() Return the number of keys in the key ring.

Methods inherited from class org.bouncycastle.openpgp.PGPKeyRing

getKeyIdentifier

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

PGPPublicKeyRing

public PGPPublicKeyRing(byte[] encoding,
                        KeyFingerPrintCalculator fingerPrintCalculator)
                 throws java.io.IOException

Throws:

java.io.IOException

PGPPublicKeyRing

public PGPPublicKeyRing(java.util.List<PGPPublicKey> pubKeys)

Base constructor from a list of keys representing a public key ring (a master key and its associated sub-keys).

Parameters:

pubKeys - the list of keys making up the ring.

PGPPublicKeyRing

public PGPPublicKeyRing(java.io.InputStream in,
                        KeyFingerPrintCalculator fingerPrintCalculator)
                 throws java.io.IOException

Throws:

java.io.IOException

Method Detail

getPublicKey

public PGPPublicKey getPublicKey()

Return the first public key in the ring.

Specified by:

getPublicKey in class PGPKeyRing

Returns:

PGPPublicKey

getPublicKey

public PGPPublicKey getPublicKey(long keyID)

Return the public key referred to by the passed in keyID if it is present.

Specified by:

getPublicKey in class PGPKeyRing

Parameters:

keyID - the full keyID of the key of interest.

Returns:

PGPPublicKey with matching keyID, null if it is not present.

getPublicKey

public PGPPublicKey getPublicKey(byte[] fingerprint)

Return the public key with the passed in fingerprint if it is present.

Specified by:

getPublicKey in class PGPKeyRing

Parameters:

fingerprint - the full fingerprint of the key of interest.

Returns:

PGPPublicKey with the matching fingerprint, null if it is not present.

getPublicKey

public PGPPublicKey getPublicKey(KeyIdentifier identifier)

Specified by:

getPublicKey in class PGPKeyRing

getPublicKeys

public java.util.Iterator<PGPPublicKey> getPublicKeys(KeyIdentifier identifier)

Specified by:

getPublicKeys in class PGPKeyRing

getKeysWithSignaturesBy

public java.util.Iterator<PGPPublicKey> getKeysWithSignaturesBy(long keyID)

Return any keys carrying a signature issued by the key represented by keyID.

Specified by:

getKeysWithSignaturesBy in class PGPKeyRing

Parameters:

keyID - the key id to be matched against.

Returns:

an iterator (possibly empty) of PGPPublicKey objects carrying signatures from keyID.

getKeysWithSignaturesBy

public java.util.Iterator<PGPPublicKey> getKeysWithSignaturesBy(KeyIdentifier identifier)

Specified by:

getKeysWithSignaturesBy in class PGPKeyRing

getPublicKeys

public java.util.Iterator<PGPPublicKey> getPublicKeys()

Return an iterator containing all the public keys.

Specified by:

getPublicKeys in class PGPKeyRing

Returns:

Iterator

iterator

public java.util.Iterator<PGPPublicKey> iterator()

Support method for Iterable where available.

Specified by:

iterator in interface java.lang.Iterable<PGPPublicKey>

getEncoded

public byte[] getEncoded()
                  throws java.io.IOException

Specified by:

getEncoded in class PGPKeyRing

Throws:

java.io.IOException

getEncoded

public byte[] getEncoded(PacketFormat format)
                  throws java.io.IOException

Specified by:

getEncoded in class PGPKeyRing

Throws:

java.io.IOException

getEncoded

public byte[] getEncoded(boolean forTransfer)
                  throws java.io.IOException

Return an encoding of the key ring, with trust packets stripped out if forTransfer is true.

Parameters:

forTransfer - if the purpose of encoding is to send key to other users.

Returns:

a encoded byte array representing the key.

Throws:

java.io.IOException - in case of encoding error.

size

public int size()

Return the number of keys in the key ring.

Specified by:

size in class PGPKeyRing

Returns:

number of keys (master key + subkey).

encode

public void encode(java.io.OutputStream outStream)
            throws java.io.IOException

Specified by:

encode in class PGPKeyRing

Throws:

java.io.IOException

encode

public void encode(java.io.OutputStream outStream,
                   boolean forTransfer)
            throws java.io.IOException

Encode the key ring to outStream, with trust packets stripped out if forTransfer is true.

Parameters:

outStream - stream to write the key encoding to.

forTransfer - if the purpose of encoding is to send key to other users.

Throws:

java.io.IOException - in case of encoding error.

insertPublicKey

public static PGPPublicKeyRing insertPublicKey(PGPPublicKeyRing pubRing,
                                               PGPPublicKey pubKey)

Returns a new key ring with the public key passed in either added or replacing an existing one.

Parameters:

pubRing - the public key ring to be modified

pubKey - the public key to be inserted.

Returns:

a new keyRing

removePublicKey

public static PGPPublicKeyRing removePublicKey(PGPPublicKeyRing pubRing,
                                               PGPPublicKey pubKey)

Returns a new key ring with the public key passed in removed from the key ring.

Parameters:

pubRing - the public key ring to be modified

pubKey - the public key to be removed.

Returns:

a new keyRing, null if pubKey is not found.

join

public static PGPPublicKeyRing join(PGPPublicKeyRing first,
                                    PGPPublicKeyRing second)
                             throws PGPException

Join two copies of the same certificate. The certificates must have the same primary key, but may carry different subkeys, user-ids and signatures. The resulting certificate will carry the sum of both certificates subkeys, user-ids and signatures.

This method will ignore trust packets on the second copy of the certificate and instead copy the local certificate's trust packets to the joined certificate.

Parameters:

first - local copy of the certificate

second - remote copy of the certificate (e.g. from a key server)

Returns:

joined key ring

Throws:

PGPException

join

public static PGPPublicKeyRing join(PGPPublicKeyRing first,
                                    PGPPublicKeyRing second,
                                    boolean joinTrustPackets,
                                    boolean allowSubkeySigsOnNonSubkey)
                             throws PGPException

Join two copies of the same certificate. The certificates must have the same primary key, but may carry different subkeys, user-ids and signatures. The resulting certificate will carry the sum of both certificates subkeys, user-ids and signatures.

For each subkey holds: If joinTrustPackets is set to true and the second key is carrying a trust packet, the trust packet will be copied to the joined key. Otherwise, the joined key will carry the trust packet of the local copy.

Parameters:

first - local copy of the certificate

second - remote copy of the certificate (e.g. from a key server)

joinTrustPackets - if true, trust packets from the second certificate copy will be carried over into the joined certificate

allowSubkeySigsOnNonSubkey - if true, the resulting joined certificate may carry subkey signatures on its primary key

Returns:

joined certificate

Throws:

PGPException