OpenPGP Task

Properties   Config Settings  

The OpenPGP Task provides OpenPGP signing and encryption functionality.

Remarks

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

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

OpenPGP Encoder Task

The encoder takes raw messages as input, and generates a signed, encrypted, or signed and encrypted OpenPGP message as output. This task can be used when creating pipelines to create such messages.

The SignData and EncryptData properties tell the task 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.

OpenPGP Decoder Task

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.

Encoder Property List


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

ASCIIArmorSpecifies whether to use ASCII armor to encode the output message.
CompressionMethodThe compression algorithm used.
EncryptDataWhether or not to encrypt the data.
EncryptingAlgorithmThe encryption algorithm used when encrypting.
HomeDirThe home directory containing the keyring.
InputFileThe name of the input file for the component.
KeySpecifies the OpenPGP private key to use for decryption and signing.
OtherDefines a set of configuration settings to be used by the task.
OutputFileThe name of the output file for the component.
PassphraseThe passphrase of the private/secret key.
PGPParamsSets the parameters in the OpenPGP provider.
PGPProviderThe OpenPGP provider provides an interface to the OpenPGP cryptography software.
PGPProviderTypeThe PGP provider to use.
ProtectedPGPParamsSets the protected parameters in the OpenPGP provider.
RecipientKeySpecifies the OpenPGP public key to use for encryption.
RecipientUserIdThe user Id of the recipient.
RuntimeLicenseSpecifies the component runtime license key.
SignDataWhether or not to sign the data.
SigningAlgorithmThe signature hash algorithm used when signing.
TempPathThe path to which temporary files are written at runtime.
UserIdThe user Id of the key.

Decoder Property List


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

HomeDirThe home directory containing the keyring.
InputFileThe name of the input file for the component.
KeySpecifies the OpenPGP private key to use for decryption and signing.
OtherDefines a set of configuration settings to be used by the task.
OutputFileThe name of the output file for the component.
PassphraseThe passphrase of the private/secret key.
PGPParamsSets the parameters in the OpenPGP provider.
PGPProviderThe OpenPGP provider provides an interface to the OpenPGP cryptography software.
PGPProviderTypeThe PGP provider to use.
ProtectedPGPParamsSets the protected parameters in the OpenPGP provider.
RuntimeLicenseSpecifies the component runtime license key.
SignerKeySpecifies the OpenPGP public key to use for signature verification.
SignerUserIdThe user Id of the signer.
TempPathThe path to which temporary files are written at runtime.
UserIdThe user Id of the key.

Config Settings


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

AllowOldPacketTypeWhether to allow the older encrypted packet type.
FileNameThe original name of the file to encrypt.
ForceV3SignatureWhether to use v3 signatures.
KeySelectionMethodThe method used to select a key for encryption or signing.
LogDebugDataWhether to include debug information in the log.
PublicKeyringFileThe name of the public keyring file.
RecursiveDecryptModeWhether the encrypted data should be decrypted recursively.
RequireEncryptionWhether an error should be thrown if the message is not encrypted.
RequireSignatureWhether an error should be thrown if the message is not signed.
SecretKeyringFileThe name of the secret keyring file.
SymmetricPassphraseThe password used for symmetric encryption or decryption.

ASCIIArmor Property (OpenPGP Task)

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 Disassembler/Decoder.

CompressionMethod Property (OpenPGP Task)

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 Disassembler/Decoder.

EncryptData Property (OpenPGP Task)

Whether or not to encrypt the data.

Data Type

Boolean

Default Value

true


Remarks

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

This property is not available in the Disassembler/Decoder.

EncryptingAlgorithm Property (OpenPGP Task)

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 Disassembler/Decoder.

HomeDir Property (OpenPGP Task)

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.

InputFile Property (OpenPGP Task)

The name of the input file for the component.

Data Type

String

Default Value

""


Remarks

This property specifies the name of the file to be read.

The output for the task will be written to the OutputFile.

If the file cannot be read, or written, as appropriate, a trappable error will be generated.

Key Property (OpenPGP Task)

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.

Other Property (OpenPGP Task)

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

Data Type

String

Default Value

""


Remarks

The task 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 task, 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

OutputFile Property (OpenPGP Task)

The name of the output file for the component.

Data Type

String

Default Value

""


Remarks

This property specifies the name of the file to be written.

The input for the task will be read from the InputFile.

If the file cannot be read, or written, as appropriate, a trappable error will be generated.

Passphrase Property (OpenPGP Task)

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 Task)

Sets the parameters in the OpenPGP provider.

Data Type

String

Default Value

""


Remarks

The PGPParams property is used to specify the parameters required by the OpenPGP provider to perform the OpenPGP operation. Although the parameters needed may vary in different providers, we expect many of the parameters in the following set to be necessary.

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

asciiarmorControls whether or not ASCII armoring is used on the output message.

This will overwrite the value of the ASCIIArmor property.

compressionmethodSpecifies which compression method is used when generating output. Possible values are:
  • zip (default)
  • zlib
  • bzip2
  • none or uncompressed
This parameter is only applicable when PGPProviderType is set to ptInternal.

This will overwrite the value of the CompressionMethod property.

encryptingalgorithmSpecifies the encryption algorithm used when encrypting. Possible values are:
  • CAST5
  • 3DES or TripleDES
  • AES256
  • AES192
  • AES128 (default)
  • BLOWFISH
  • TWOFISH
  • IDEA
This parameter is only applicable when PGPProviderType is set to ptInternal.

This will overwrite the value of the EncryptingAlgorithm property.

gpg-pathThe path to the OpenPGP executable for the desired implementation. This parameter is not applicable when PGPProviderType is set to ptInternal.
homedirThe directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified.

This will overwrite the value of the HomeDir property.

keyThe 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 parameter is only applicable when PGPProviderType is set to ptInternal.

This will overwrite the value of the Key property.

passphraseThe passphrase to access the secret keys in the secret-keyring.

This will overwrite the value of the Passphrase property.

recipientkeyThe 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 parameter is only applicable when PGPProviderType is set to ptInternal.

This will overwrite the value of the RecipientKey property.

recipient-useridThe 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-useridThe 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.
signerkeyThe 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 parameter is only applicable when PGPProviderType is set to ptInternal.

This will overwrite the value of the SignerKey property.

signingalgorithmSpecifies the signature hash algorithm used when signing. Possible values are:
  • SHA1
  • MD5
  • SHA256 (default)
  • SHA348
  • SHA512
  • SHA224
  • RIPEMD160
This parameter is only applicable when PGPProviderType is set to ptInternal.
useridThe 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.

The task expects the encryption and signing to return an ASCII armored output. Note: GnuPG is the Free Software Foundation's implementation of OpenPGP.

GnuPG is not included with this package, so you should download the latest version from http://www.gnupg.org. You might use GnuPG (or other software) to import your trading partners' public keys, and to import or generate a private key for yourself. These operations are outside the scope of this software, so please see the GnuPG documentation for details.

PGPProvider Property (OpenPGP Task)

The OpenPGP provider provides an interface to the OpenPGP cryptography software.

Data Type

String

Default Value

""


Remarks

The library that interfaces to the OpenPGP cryptography software.

When PGPProviderType is set to Internal this property is not used.

When PGPProviderType is set to External this property must be set to a DLL holding the interface to the external application.

External Provider Implementation Notes

When PGPProviderType is set to External the task uses the provider pattern to interface with external cryptography libraries. An OpenPGP provider is a simple module that allows the task to offload OpenPGP operations to the OpenPGP software of your choice. The interface is designed to be generic in its ability to include various OpenPGP software. We include an OpenPGP provider implementation for GnuPG which may be used as a reference to implement other providers.

An OpenPGP provider is simply a class called "nsoftwarePGPProvider" that should have the following methods. The task uses reflection to access the methods of the provider. public void SetParam(string name,string value); public byte[] Encrypt(byte[] data); public byte[] Decrypt(byte[] data); public byte[] Sign(byte[] data); public byte[] EncryptAndSign(byte[] data);

PGPProviderType Property (OpenPGP Task)

The PGP provider to use.

Data Type

Enumeration

Possible Values

External (0)
Internal (1)


Default Value

1


Remarks

This property specifies which PGP provider is used. By default property is set to ptInternal and all cryptographic operations will be performed by the task directly using an internal implementation. In this case PGPProvider is not used.

If set to ptExternal the task will rely on the an external provider such as GnuPG which is accessed through the interface DLL specified by PGPProvider.

External Provider Implementation Notes

When PGPProviderType is set to External the task uses the provider pattern to interface with external cryptography libraries. An OpenPGP provider is a simple module that allows the task to offload OpenPGP operations to the OpenPGP software of your choice. The interface is designed to be generic in its ability to include various OpenPGP software. We include an OpenPGP provider implementation for GnuPG which may be used as a reference to implement other providers.

An OpenPGP provider is simply a class called "nsoftwarePGPProvider" that should have the following methods. The task uses reflection to access the methods of the provider. public void SetParam(string name,string value); public byte[] Encrypt(byte[] data); public byte[] Decrypt(byte[] data); public byte[] Sign(byte[] data); public byte[] EncryptAndSign(byte[] data);

ProtectedPGPParams Property (OpenPGP Task)

Sets the protected parameters in the OpenPGP provider.

Data Type

String

Default Value

""


Remarks

This should be set to any PGPParams which contain important values that will be hidden from the user configuration.

RecipientKey Property (OpenPGP Task)

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.

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.

This property is not available in the Disassembler/Decoder.

RecipientUserId Property (OpenPGP Task)

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 that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

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

This property is not available in the Disassembler/Decoder.

RuntimeLicense Property (OpenPGP Task)

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 task license.

SignData Property (OpenPGP Task)

Whether or not to sign the data.

Data Type

Boolean

Default Value

false


Remarks

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

This property is not available in the Disassembler/Decoder.

SignerKey Property (OpenPGP Task)

Specifies the OpenPGP public key to use for signature verification.

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.

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.

This property is not available in the Assembler/Encoder.

SignerUserId Property (OpenPGP Task)

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 Assembler/Encoder.

SigningAlgorithm Property (OpenPGP Task)

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 Disassembler/Decoder.

TempPath Property (OpenPGP Task)

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 task 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.

This property accepts the "%TEMP%" macro, which will be replaced with the default system temporary directory at runtime.

UserId Property (OpenPGP Task)

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 that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

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

Config Settings (OpenPGP Task)

The task 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 task, 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 task 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 task 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 task 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 task 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 task 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 task will handle this situation. Options are:

0Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default)
1Always attempt recursive decryption.
2Never 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 task 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 task 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.