OpenPGP Modules

The OpenPGP Transformer provides OpenPGP signing and encryption functionality.

Remarks

The OpenPGP Module is used for sending and receiving OpenPGP signed and encrypted messages. The messages may be signed, encrypted, or both.

By default the OpenPGP Module will use an internal OpenPGP implementation. This implementation of OpenPGP does not require any additional dependencies and is completely managed. Alternatively the module may be configured to use an external implementation such as GnuPG. See PGPProviderType for details.

OpenPGP Encoder Module

The encoder takes raw messages as input, and generates a signed, encrypted, or signed and encrypted OpenPGP message as output. This module adds encryption and signing functionality to your Mule Project.

The SignData and EncryptData properties tell the module which operations should be performed on the message. Set the respective property to true to enable the operation. If signing a message, you will need to specify the private key for signing in the Key property. If encrypting a message, you will need to specify the public key of the recipient in the RecipientKey property. Optionally use the PGPParams property to specify input parameters to the operation.

Encode Example

To get started, simply provide the module a message to encode. Do this by setting the payload of a Mule Message to the Binary input data before it arrives at the Encode operation. For example, add a File Read Connector to your flow and add OpenPGP Encode behind it. There is no need to transform the output of the File Read Connector before passing it to the OpenPGP Encoder.

Configure the module with at a minimum the RecipientKey property and it will begin encrypting messages. To write the resulting message to disk, add a File Write connector behind the OpenPGP Encode operation and specify the Path and Content. The output of the Encoder in the payload can be passed directly to the File Write connector.

OpenPGP Decoder Module

The decoder takes OpenPGP signed, encrypted, or signed and encrypted messages as input, then verifies and/or decrypts the message. The resulting message will be the raw original message.

The incoming message will be decrypted using the private key in the Key property. Verification is performed automatically when the public key of the signer is specified in the SignerKey property. Optionally use the PGPParams property to specify input parameters to the operation.

Decode Example

To get started, simply provide the module a message to decode. Do this by setting the payload of a Mule Message to the Binary input data before it arrives at the Decode operation. For example. add a File Read Connector in front of OpenPGP Decode. There is no need to transform the output of the File Read Connector before passing it to the OpenPGP Decoder.

Configure the module with at a minimum the Key property and it will begin processing messages. To write the resulting message to disk, add a File Write connector behind the OpenPGP Decode operation and specify the Path and Content. The output of the Decoder in the payload can be passed directly to the File Write connector.

Encoder Property List

The following is the full list of the properties of the encoder Module with short descriptions. Click on the links for further details.


ASCIIArmor	Specifies whether to use ASCII armor to encode the output message.
CompressionMethod	The compression algorithm used.
EncryptData	Whether or not to encrypt the data.
EncryptingAlgorithm	The encryption algorithm used when encrypting.
HomeDir	The home directory containing the keyring.
Key	Specifies the OpenPGP private key to use for decryption and signing.
LogFile	The file to write logging information to at runtime.
LogMode	What information gets logged during component execution.
LogType	How information gets logged during component execution.
Other	Defines a set of configuration settings to be used by the transformer.
Passphrase	The passphrase of the private/secret key.
PGPParams	Sets the parameters in the OpenPGP provider.
RecipientKey	Specifies the OpenPGP public key to use for encryption.
RecipientUserId	The user Id of the recipient.
RuntimeLicense	Specifies the component runtime license key.
SignData	Whether or not to sign the data.
SigningAlgorithm	The signature hash algorithm used when signing.
TempPath	The path to which temporary files are written at runtime.
UserId	The user Id of the key.

Decoder Property List

The following is the full list of the properties of the decoder Module with short descriptions. Click on the links for further details.


HomeDir	The home directory containing the keyring.
Key	Specifies the OpenPGP private key to use for decryption and signing.
LogFile	The file to write logging information to at runtime.
LogMode	What information gets logged during component execution.
LogType	How information gets logged during component execution.
Other	Defines a set of configuration settings to be used by the transformer.
Passphrase	The passphrase of the private/secret key.
PGPParams	Sets the parameters in the OpenPGP provider.
RuntimeLicense	Specifies the component runtime license key.
SignerKey	Specifies the OpenPGP public key to use for signature verification.
SignerUserId	The user Id of the signer.
TempPath	The path to which temporary files are written at runtime.
UserId	The user Id of the key.

Config Settings

The following is a list of config settings for the Module with short descriptions. Click on the links for further details.


AllowOldPacketType	Whether to allow the older encrypted packet type.
Filename	The original name of the file to encrypt.
ForceV3Signature	Whether to use v3 signatures.
KeySelectionMethod	The method used to select a key for encryption or signing.
LogDebugData	Whether to include debug information in the log.
PublicKeyringFile	The name of the public keyring file.
RecursiveDecryptMode	Whether the encrypted data should be decrypted recursively.
RequireEncryption	Whether an error should be thrown if the message is not encrypted.
RequireSignature	Whether an error should be thrown if the message is not signed.
SecretKeyringFile	The name of the secret keyring file.
SymmetricPassphrase	The password used for symmetric encryption or decryption.

ASCIIArmor Property (OpenPGP Module)

Specifies whether to use ASCII armor to encode the output message.

Data Type

Boolean

Default Value

true

Remarks

This property controls whether or not ASCII armoring is used on the output message. The default value is True.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Decompressor/Decoder.

CompressionMethod Property (OpenPGP Module)

The compression algorithm used.

Data Type

String

Default Value

"zip"

Remarks

This property specifies which compression method is used when generating output. Possible values are:

zip (default)
zlib
bzip2
none or uncompressed

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Decompressor/Decoder.

EncryptData Property (OpenPGP Module)

Whether or not to encrypt the data.

Data Type

Boolean

Default Value

true

Remarks

If true, then the data will be encrypted by the module.

This property is not available in the Decompressor/Decoder.

EncryptingAlgorithm Property (OpenPGP Module)

The encryption algorithm used when encrypting.

Data Type

String

Default Value

"AES128"

Remarks

This property specifies the encryption algorithm used when encrypting. Possible values are:

CAST5
3DES or TripleDES
AES256
AES192
AES128 (default)
BLOWFISH
TWOFISH
IDEA

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Decompressor/Decoder.

HomeDir Property (OpenPGP Module)

The home directory containing the keyring.

Data Type

String

Default Value

Remarks

This property specifies the directory containing the keyring. A keyring consists of a public (pubring.gpg) and secret keyring (secring.gpg) file. This should be set to the path containing those files.

To use an individual PGP key rather than a keyring file, the Key or RecipientKey properties should be set instead.

Note: Values specified in PGPParams take precedence over values specified in this property.

Key Property (OpenPGP Module)

Specifies the OpenPGP private key to use for decryption and signing.

Data Type

String

Default Value

Remarks

When using an individual PGP private key instead of a keyring, set this property to the private key. If the key is stored in a key file then this property should be set to the path to that file; alternatively, the ASCII-armored key data can be set directly in this property.

See the HomeDir property for information on using a keyring file.

Note: Values specified in PGPParams take precedence over values specified in this property. However, when using PGPParams the ASCII-armored file data can not be set directly; the key must be stored in a file and a path to a key file must be provided.

LogFile Property (OpenPGP Module)

The file to write logging information to at runtime.

Data Type

String

Default Value

Remarks

To write logging information to a file instead of using the connector's logging API, set this property to a valid file on disk and set the LogType property to "File".

LogMode Property (OpenPGP Module)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)

Default Value

Remarks

This property controls what information the connector logs. The possible values have the following affect on the connector's behavior:


Verbose	The connector will report all information regarding the transport.
Info	The connector will report all major operations, as well as all warnings and errors.
Warning	The connector will report any conditions that could result in unpredictable behavior as well as errors.
Error	The connector will report all errors that prevent normal operations from completing.
Fatal	The connector will report only serious errors that cause the connector to completely stop functioning.

LogType Property (OpenPGP Module)

How information gets logged during component execution.

Data Type

Enumeration

Possible Values

None (0)
Console (1)
File (2)

Default Value

Remarks

This property controls where the connector will log the information. The possible values have the following affect on the connector's behavior:


None	The connector will not report any logging information.
Console	The connector will report all logging information to the console.
File	The connector will report all logging information to a file. The desired file must be specified in the LogFile when this type has been selected.

Other Property (OpenPGP Module)

Defines a set of configuration settings to be used by the transformer.

Data Type

String

Default Value

Remarks

The module accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the module, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

Passphrase Property (OpenPGP Module)

The passphrase of the private/secret key.

Data Type

String

Default Value

Remarks

This property specifies the password of the key used for signing and decryption. This property is required when using private/secret keys, whether or not the key has been imported into a keyring.

Note: Values specified in PGPParams take precedence over values specified in this property.

PGPParams Property (OpenPGP Module)

Sets the parameters in the OpenPGP provider.

Data Type

String

Default Value

Remarks

Each parameter should be listed on a separate line by itself. The parameters exist in name/value pairs separated by an '=' sign. This may be used to specify all parameters in one location and may also be used to override some component properties.

The following is an example of several parameters that may exist for this property: homedir=C:\myhomedir passphrase=testpgp signature=nondetached


asciiarmor	Controls whether or not ASCII armoring is used on the output message. This will overwrite the value of the ASCIIArmor property.
compressionmethod	Specifies which compression method is used when generating output. Possible values are: zip (default) zlib bzip2 none or uncompressed This will overwrite the value of the CompressionMethod property.
encryptingalgorithm	Specifies the encryption algorithm used when encrypting. Possible values are: CAST5 3DES or TripleDES AES256 AES192 AES128 (default) BLOWFISH TWOFISH IDEA This will overwrite the value of the EncryptingAlgorithm property.
homedir	The directory containing the public keyring, secret keyring and trust database. This will overwrite the value of the HomeDir property.
key	The file where the private/secret PGP key is held. If the key is not stored in a file, the ASCII-armored data can be set directly via the Key property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This will overwrite the value of the Key property.
passphrase	The passphrase to access the secret keys in the secret-keyring. This will overwrite the value of the Passphrase property.
recipientkey	The file where the public PGP key for encryption is held. Only applicable for the PGP Encoder component. If the key is not stored in a file, the ASCII-armored data can be set directly via the RecipientKey property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This will overwrite the value of the RecipientKey property.
recipient-userid	The identifier used to select a public key within the public keyring when encrypting. This will overwrite the value of the RecipientUserId property.
recipient-userid[i]	An alternative to recipient-userid that allows for multiple recipients to be specified. Each key would be specified with a different index. For example: recipient-userid[0], recipient-userid[1], etc.
signer-userid	The identifier used to select a public key within the public keyring when verifying a signature.
signer-userid[i]	An alternative to signer-userid that allows for multiple recipients to be specified. Each key would be specified with a different index. For example: signer-userid[0], signer-userid[1], etc.
signerkey	The file where the public PGP key for signature verification is held. Only applicable for the PGP Decoder component. If the key is not stored in a file, the ASCII-armored data can be set directly via the RecipientKey property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This will overwrite the value of the SignerKey property.
signingalgorithm	Specifies the signature hash algorithm used when signing. Possible values are: SHA1 MD5 SHA256 (default) SHA348 SHA512 SHA224 RIPEMD160
userid	The identifier used to select a secret key within the secret-keyring; used for both decryption and signing. This will overwrite the value of the UserId property.

RecipientKey Property (OpenPGP Module)

Specifies the OpenPGP public key to use for encryption.

Data Type

String

Default Value

Remarks

When using an individual PGP public key instead of a keyring, set this property to the public key. If the key is stored in a key file then this property should be set to the path to that file; alternatively, the ASCII-armored key data can be set directly in this property.

See the HomeDir property for information on using a keyring file.

This property is not available in the Decompressor/Decoder.

RecipientUserId Property (OpenPGP Module)

The user Id of the recipient.

Data Type

String

Default Value

Remarks

This specifies the user Id of the recipient's key. This is used to identify the key with which the message is encrypted.

The UserId format is:

FirstName LastName (Comment) <Email>

Not all values are required when selecting or generating a key, but at least FirstName or Email are required.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Decompressor/Decoder.

RuntimeLicense Property (OpenPGP Module)

Specifies the component runtime license key.

Data Type

String

Default Value

Remarks

You can use the RuntimeLicense property to set the runtime key for the connector license.

SignData Property (OpenPGP Module)

Whether or not to sign the data.

Data Type

Boolean

Default Value

false

Remarks

If true, then the data will be signed by the module.

This property is not available in the Decompressor/Decoder.

SignerKey Property (OpenPGP Module)

Specifies the OpenPGP public key to use for signature verification.

Data Type

String

Default Value

Remarks

See the HomeDir property for information on using a keyring file.

This property is not available in the Compressor/Encoder.

SignerUserId Property (OpenPGP Module)

The user Id of the signer.

Data Type

String

Default Value

Remarks

This specifies the user Id of the signer's public key. This is used to identify the key with which the signature should be verified when it has been imported to a keyring.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Compressor/Encoder.

SigningAlgorithm Property (OpenPGP Module)

The signature hash algorithm used when signing.

Data Type

String

Default Value

"SHA256"

Remarks

This property specifies the signature hash algorithm used when signing. Possible values are:

SHA1
MD5
SHA256 (default)
SHA384
SHA512
SHA224
RIPEMD160

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Decompressor/Decoder.

TempPath Property (OpenPGP Module)

The path to which temporary files are written at runtime.

Data Type

String

Default Value

Remarks

If you are planning on working with binary files or large files, it is recommended that you set a valid path for this property. When set to a valid path this property tells the connector to use temp files when performing operations. If this is not set, all operations are done in memory and require that all input and output is in ASCII.

UserId Property (OpenPGP Module)

The user Id of the key.

Data Type

String

Default Value

Remarks

This specifies the user Id of the key which is used for signing and decryption. This is used to identify the key when it has been imported to a keyring.

The UserId format is:

FirstName LastName (Comment) <Email>

Not all values are required when selecting or generating a key, but at least FirstName or Email are required.

Note: Values specified in PGPParams take precedence over values specified in this property.

Config Settings (OpenPGP Module)

The connector accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the connector, access to these internal properties is provided through the Other property.

OpenPGP Config Settings

AllowOldPacketType: Whether to allow the older encrypted packet type.

By default the connector will only encrypt data using the newer and more secure integrity protected data packet type. Old implementations such as PGP 6.5.8 may require the older less secure data packet type.

When set to True the connector will read the features from the recipient key to determine if the older packet type is required. If the key does require the old packet type, then the older packet type will be used. If the key does not require the old packet type, then the new integrity protected packet type will still be used.

By default this value is False. This means under no conditions is the older less secure packet type used. The newer integrity protected packet type is always used.

Only enable this setting if you have a requirement to do so.

Filename: The original name of the file to encrypt.

When encrypting, this configuration setting can be used to specify the original filename of the data to encrypt. If specified, this value is included in the encrypted packet.

This setting is only available in the Encoder.

ForceV3Signature: Whether to use v3 signatures.

This setting is used to force v3 signatures for compatibility with older PGP implementations (versions 5 through 7).

The default value is False.

This setting is only available in the Encoder.

KeySelectionMethod: The method used to select a key for encryption or signing.

When more than one key is present this connector can be configured to automatically select a key based on certain criteria (described below) or allow for manual selection.


0	Automatic selection, first suitable subkey. Expired keys accepted.
1	Automatic selection, first suitable subkey. Expired keys not accepted.
2	Automatic selection, newest suitable subkey. Expired keys not accepted (Default).
99	Manual Selection.

A key's suitability is determined by its usage flags.

Manual Selection

To manually select a key for any operation pass the key's Id in the UserId property.

LogDebugData: Whether to include debug information in the log.

This setting may be set to True to include detailed debug information in the log. The log mode should also be set to Verbose when using this setting. This may be helpful for troubleshooting purposes. The default value is False.

PublicKeyringFile: The name of the public keyring file.

This setting may be used to specify an alternative public keyring file. By default the connector will look for the file "pubring.gpg" in the homedir. Specify this setting to provide an alternative filename. This may be set to a filename without path such as "pubring.pkr" in which case the connector will search for this file in the homedir. This may also be set to a full path such as "C:\keyring\pubring.pkr".

RecursiveDecryptMode: Whether the encrypted data should be decrypted recursively.

In some instances data will be encrypted multiple times. This configuration option determines how the connector will handle this situation. Options are:


0	Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default)
1	Always attempt recursive decryption.
2	Never attempt recursive decryption.

RequireEncryption: Whether an error should be thrown if the message is not encrypted.

This setting only affects the decoder. By default, unencrypted messages will not cause an error to be thrown. To change this and only allow encrypted messages, set this option to true.

RequireSignature: Whether an error should be thrown if the message is not signed.

This setting only affects the decoder. By default, unsigned messages will not cause an error to be thrown. To change this and only allow encrypted messages, set this option to true.

SecretKeyringFile: The name of the secret keyring file.

This setting may be used to specify an alternative secret keyring file. By default the connector will look for the file "secring.gpg" in the homedir. Specify this setting to provide an alternative filename. This may be set to a filename without path such as "secring.skr" in which case the connector will search for this file in the homedir. This may also be set to a full path such as "C:\keyring\secring.skr".

SymmetricPassphrase: The password used for symmetric encryption or decryption.

This setting specifies the passphrase when using symmetric encryption. If a value is provided, symmetric encryption/decryption will be attempted. In this case no keys are used for either encryption or decryption. Only Encrypt and Decrypt are valid operations when a value is set. Sign, SignAndEncrypt, VerifySignature, and DecryptAndVerifySignature are not valid operations when using this option.