org.bouncycastle.openpgp.api

Class OpenPGPMessageGenerator

java.lang.Object

org.bouncycastle.openpgp.api.AbstractOpenPGPDocumentSignatureGenerator<OpenPGPMessageGenerator>

org.bouncycastle.openpgp.api.OpenPGPMessageGenerator

public class OpenPGPMessageGenerator
extends AbstractOpenPGPDocumentSignatureGenerator<OpenPGPMessageGenerator>

Generator for OpenPGP messages. This class can generate armored/unarmored, encrypted and/or signed OpenPGP message artifacts. By default, the generator will merely pack plaintext into an armored LiteralDataPacket. If however, the user provides one or more recipient certificates/keys (addEncryptionCertificate(OpenPGPCertificate) / addEncryptionCertificate(OpenPGPCertificate.OpenPGPComponentKey)) or message passphrases addEncryptionPassphrase(char[]), the message will be encrypted. The encryption mechanism is automatically decided, based on the provided recipient certificates, aiming to maximize interoperability. If the user provides one or more signing keys by calling AbstractOpenPGPDocumentSignatureGenerator.addSigningKey(OpenPGPKey) or AbstractOpenPGPDocumentSignatureGenerator.addSigningKey(OpenPGPKey.OpenPGPSecretKey, KeyPassphraseProvider, SignatureParameters.Callback), the message will be signed.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OpenPGPMessageGenerator.ArmoredOutputStreamFactory
static interface	OpenPGPMessageGenerator.CompressionNegotiator

Field Summary

Fields

Modifier and Type	Field and Description
static int	BUFFER_SIZE
boolean	isAllowPadding

Fields inherited from class org.bouncycastle.openpgp.api.AbstractOpenPGPDocumentSignatureGenerator

defaultKeyPassphraseProvider, implementation, policy, signatureCallbacks, signatureGenerators, signingKeyPassphraseProviders, signingKeys, signingKeySelector

Constructor Summary

Constructors

Constructor and Description
OpenPGPMessageGenerator()
OpenPGPMessageGenerator(OpenPGPImplementation implementation)
OpenPGPMessageGenerator(OpenPGPImplementation implementation, OpenPGPPolicy policy)

Method Summary

Modifier and Type	Method and Description
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate.OpenPGPComponentKey encryptionKey) Add a (sub-)key to the set of recipient encryption keys.
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate.OpenPGPComponentKey encryptionKey, boolean anonymousRecipient) Add a (sub-)key to the set of recipient encryption keys.
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate recipientCertificate) Add a recipients certificate to the set of encryption keys.
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate recipientCertificate, boolean anonymousRecipient) Add a recipients certificate to the set of encryption keys.
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate recipientCertificate, SubkeySelector subkeySelector) Add a recipients certificate to the set of encryption keys.
OpenPGPMessageGenerator	addEncryptionCertificate(OpenPGPCertificate recipientCertificate, SubkeySelector subkeySelector, boolean anonymousRecipient) Add a recipients certificate to the set of encryption keys.
OpenPGPMessageGenerator	addEncryptionPassphrase(char[] passphrase) Add a message passphrase.
OpenPGPMessageOutputStream	open(java.io.OutputStream out) Open an OpenPGPMessageOutputStream over the given output stream.
OpenPGPMessageGenerator	setAllowPadding(boolean allowPadding)
OpenPGPMessageGenerator	setArmored(boolean armored) Specify, whether the output OpenPGP message will be ASCII armored or not.
OpenPGPMessageGenerator	setArmorStreamFactory(OpenPGPMessageGenerator.ArmoredOutputStreamFactory factory) Replace the OpenPGPMessageGenerator.ArmoredOutputStreamFactory with a custom implementation.
OpenPGPMessageGenerator	setCompressionNegotiator(OpenPGPMessageGenerator.CompressionNegotiator compressionNegotiator) Replace the default OpenPGPMessageGenerator.CompressionNegotiator with a custom implementation.
OpenPGPMessageGenerator	setEncryptionKeySelector(SubkeySelector encryptionKeySelector) Replace the default encryption key selector with a custom implementation.
OpenPGPMessageGenerator	setFileMetadata(java.io.File file) Set metadata (filename, modification date, binary format) from a file.
OpenPGPMessageGenerator	setPasswordBasedEncryptionNegotiator(OpenPGPEncryptionNegotiator pbeNegotiator) Replace the default OpenPGPEncryptionNegotiator that gets to decide, which MessageEncryptionMechanism mode to use if only password-based encryption is used.
OpenPGPMessageGenerator	setPublicKeyBasedEncryptionNegotiator(OpenPGPEncryptionNegotiator pkbeNegotiator) Replace the default OpenPGPEncryptionNegotiator that decides, which MessageEncryptionMechanism mode to use if public-key encryption is used.
OpenPGPMessageGenerator	setSessionKeyExtractionCallback(PGPEncryptedDataGenerator.SessionKeyExtractionCallback callback) Set a callback which fires once the session key for message encryption is known.

Methods inherited from class org.bouncycastle.openpgp.api.AbstractOpenPGPDocumentSignatureGenerator

addKeyPassphrase, addSigningKey, addSigningKey, addSigningKey, addSigningKey, addSigningKey, addSigningKey, addSignToGenerator, initSignatureGenerator, setMissingKeyPassphraseCallback, setSigningKeySelector

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE

See Also:

Constant Field Values

isAllowPadding

public boolean isAllowPadding

Constructor Detail

OpenPGPMessageGenerator

public OpenPGPMessageGenerator()

OpenPGPMessageGenerator

public OpenPGPMessageGenerator(OpenPGPImplementation implementation)

OpenPGPMessageGenerator

public OpenPGPMessageGenerator(OpenPGPImplementation implementation,
                               OpenPGPPolicy policy)

Method Detail

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate recipientCertificate)
                                                 throws InvalidEncryptionKeyException

Add a recipients certificate to the set of encryption keys. Subkeys will be selected using the default SubkeySelector, which can be replaced by calling setEncryptionKeySelector(SubkeySelector). The recipient will be able to decrypt the message using their corresponding secret key.

Parameters:

recipientCertificate - recipient certificate (public key)

Returns:

this

Throws:

InvalidEncryptionKeyException

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate recipientCertificate,
                                                        boolean anonymousRecipient)
                                                 throws InvalidEncryptionKeyException

Add a recipients certificate to the set of encryption keys. Subkeys will be selected using the default SubkeySelector, which can be replaced by calling setEncryptionKeySelector(SubkeySelector). The recipient will be able to decrypt the message using their corresponding secret key. If anonymousRecipient is true, the recipients key-identifier will be obfuscated via a wildcard key-identifier.

Parameters:

recipientCertificate - recipient certificate (public key)

anonymousRecipient - whether to obfuscate the recipients identity within the message

Returns:

this

Throws:

InvalidEncryptionKeyException

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate recipientCertificate,
                                                        SubkeySelector subkeySelector)
                                                 throws InvalidEncryptionKeyException

Add a recipients certificate to the set of encryption keys. Subkeys will be selected using the provided SubkeySelector. The recipient will be able to decrypt the message using their corresponding secret key.

Parameters:

recipientCertificate - recipient certificate (public key)

subkeySelector - selector for encryption subkeys

Returns:

this

Throws:

InvalidEncryptionKeyException - if the certificate is not capable of encryption

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate recipientCertificate,
                                                        SubkeySelector subkeySelector,
                                                        boolean anonymousRecipient)
                                                 throws InvalidEncryptionKeyException

Add a recipients certificate to the set of encryption keys. Subkeys will be selected using the provided SubkeySelector. The recipient will be able to decrypt the message using their corresponding secret key. If anonymous recipient is true, the identity of the recipient will be obfuscated via a wildcard key-identifier.

Parameters:

recipientCertificate - recipient certificate (public key)

subkeySelector - selector for encryption subkeys

anonymousRecipient - whether to obfuscate the recipients identity within the message

Returns:

this

Throws:

InvalidEncryptionKeyException - if the certificate is not capable of encryption

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate.OpenPGPComponentKey encryptionKey)
                                                 throws InvalidEncryptionKeyException

Add a (sub-)key to the set of recipient encryption keys. The recipient will be able to decrypt the message using their corresponding secret key.

Parameters:

encryptionKey - encryption capable subkey

Returns:

this

Throws:

InvalidEncryptionKeyException - if the key is not capable of encryption

addEncryptionCertificate

public OpenPGPMessageGenerator addEncryptionCertificate(OpenPGPCertificate.OpenPGPComponentKey encryptionKey,
                                                        boolean anonymousRecipient)
                                                 throws InvalidEncryptionKeyException

Add a (sub-)key to the set of recipient encryption keys. The recipient will be able to decrypt the message using their corresponding secret key. If anonymous recipient is true, the identity of the recipient will be obfuscated via a wildcard key-identifier.

Parameters:

encryptionKey - encryption capable subkey

anonymousRecipient - whether to obfuscate the recipients identity within the message

Returns:

this

Throws:

InvalidEncryptionKeyException - if the key is not capable of encryption

addEncryptionPassphrase

public OpenPGPMessageGenerator addEncryptionPassphrase(char[] passphrase)

Add a message passphrase. In addition to optional public key encryption, the message will be decryptable using the given passphrase.

Parameters:

passphrase - passphrase

Returns:

this

setArmored

public OpenPGPMessageGenerator setArmored(boolean armored)

Specify, whether the output OpenPGP message will be ASCII armored or not.

Parameters:

armored - boolean

Returns:

this

setAllowPadding

public OpenPGPMessageGenerator setAllowPadding(boolean allowPadding)

setFileMetadata

public OpenPGPMessageGenerator setFileMetadata(java.io.File file)

Set metadata (filename, modification date, binary format) from a file.

Parameters:

file - file

Returns:

this

setSessionKeyExtractionCallback

public OpenPGPMessageGenerator setSessionKeyExtractionCallback(PGPEncryptedDataGenerator.SessionKeyExtractionCallback callback)

Set a callback which fires once the session key for message encryption is known. This callback can be used to extract the session key, e.g. to emit it to the user (in case of SOP).

Parameters:

callback - callback

Returns:

this

open

public OpenPGPMessageOutputStream open(java.io.OutputStream out)
                                throws PGPException,
                                       java.io.IOException

Open an OpenPGPMessageOutputStream over the given output stream.

Parameters:

out - output stream

Returns:

OpenPGP message output stream

Throws:

PGPException - if the output stream cannot be created

java.io.IOException

setPasswordBasedEncryptionNegotiator

public OpenPGPMessageGenerator setPasswordBasedEncryptionNegotiator(OpenPGPEncryptionNegotiator pbeNegotiator)

Replace the default OpenPGPEncryptionNegotiator that gets to decide, which MessageEncryptionMechanism mode to use if only password-based encryption is used.

Parameters:

pbeNegotiator - custom PBE negotiator.

Returns:

this

setPublicKeyBasedEncryptionNegotiator

public OpenPGPMessageGenerator setPublicKeyBasedEncryptionNegotiator(OpenPGPEncryptionNegotiator pkbeNegotiator)

Replace the default OpenPGPEncryptionNegotiator that decides, which MessageEncryptionMechanism mode to use if public-key encryption is used.

Parameters:

pkbeNegotiator - custom encryption negotiator that gets to decide if PK-based encryption is used

Returns:

this

setEncryptionKeySelector

public OpenPGPMessageGenerator setEncryptionKeySelector(SubkeySelector encryptionKeySelector)

Replace the default encryption key selector with a custom implementation. The encryption key selector is responsible for selecting one or more encryption subkeys from a recipient certificate.

Parameters:

encryptionKeySelector - selector for encryption (sub-)keys

Returns:

this

setCompressionNegotiator

public OpenPGPMessageGenerator setCompressionNegotiator(OpenPGPMessageGenerator.CompressionNegotiator compressionNegotiator)

Replace the default OpenPGPMessageGenerator.CompressionNegotiator with a custom implementation. The OpenPGPMessageGenerator.CompressionNegotiator is used to negotiate, whether and how to compress the literal data packet.

Parameters:

compressionNegotiator - negotiator

Returns:

this

setArmorStreamFactory

public OpenPGPMessageGenerator setArmorStreamFactory(OpenPGPMessageGenerator.ArmoredOutputStreamFactory factory)

Replace the OpenPGPMessageGenerator.ArmoredOutputStreamFactory with a custom implementation.

Parameters:

factory - factory for ArmoredOutputStream instances

Returns:

this