OpenPGP Task
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.
| 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. |
| InputFile | The name of the input file for the component. |
| Key | Specifies the OpenPGP private key to use for decryption and signing. |
| Other | Defines a set of configuration settings to be used by the task. |
| OutputFile | The name of the output file for the component. |
| Passphrase | The passphrase of the private/secret key. |
| PGPParams | Sets the parameters in the OpenPGP provider. |
| PGPProvider | The OpenPGP provider provides an interface to the OpenPGP cryptography software. |
| PGPProviderType | The PGP provider to use. |
| ProtectedPGPParams | Sets the protected 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 task with short descriptions. Click on the links for further details.
| HomeDir | The home directory containing the keyring. |
| InputFile | The name of the input file for the component. |
| Key | Specifies the OpenPGP private key to use for decryption and signing. |
| Other | Defines a set of configuration settings to be used by the task. |
| OutputFile | The name of the output file for the component. |
| Passphrase | The passphrase of the private/secret key. |
| PGPParams | Sets the parameters in the OpenPGP provider. |
| PGPProvider | The OpenPGP provider provides an interface to the OpenPGP cryptography software. |
| PGPProviderType | The PGP provider to use. |
| ProtectedPGPParams | Sets the protected 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 task 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 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
| 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:
This will overwrite the value of the CompressionMethod property. |
| encryptingalgorithm | Specifies the encryption algorithm used when encrypting. Possible values are:
This will overwrite the value of the EncryptingAlgorithm property. |
| gpg-path | The path to the OpenPGP executable for the desired implementation. This parameter is not applicable when PGPProviderType is set to ptInternal. |
| homedir | The 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. |
| 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 parameter is only applicable when PGPProviderType is set to ptInternal.
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 parameter is only applicable when PGPProviderType is set to ptInternal.
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 parameter is only applicable when PGPProviderType is set to ptInternal.
This will overwrite the value of the SignerKey property. |
| signingalgorithm | Specifies the signature hash algorithm used when signing. Possible values are:
|
| 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. |
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: 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: 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
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.
This setting is only available in the Encoder.
The default value is False.
This setting is only available in the Encoder.
| 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. |
Manual Selection
To manually select a key for any operation pass the key's Id in the UserId property.
| 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. |