OpenPGP Pipeline Component for Microsoft BizTalk
Requirements:
/n software Adapters for Microsoft BizTalk
Introduction
The OpenPGP pipeline component provides functionality to Sign, Encrypt, Decrypt, and Verify Signatures using OpenPGP standards. The component is fully interoperable with other OpenPGP software and uses standard keyring formats for key management.
The component performs OpenPGP operations using a full-featured internal implementation of OpenPGP.
There are no external dependencies.
Contents
Installation
After running the setup the pipeline components will be registered for use as a BizTalk Pipeline Component but will not be available from within Visual Studio at design time.
Note: As an alternative to building your own pipeline project you may use the Prebuilt Pipelines included with the toolkit. See the BizTalk Prebuilt Pipelines article for details.
To use the components inside Visual Studio first right click on the BizTalk Pipeline Components tab in the toolbox and select Choose Items.
Next select the BizTalk Pipeline Components tab in the dialog and select the desired pipeline components.
After adding the pipeline components they should now be visible in the toolbox when in design view of the BizTalk Pipeline.
This should not be used if the key has been imported to a keyring.
Creating a Send Pipeline
When creating a send pipeline, the OpenPGP Encoder can be used in the Encode stage of the pipeline. After dropping the pipeline component from the toolbox onto the pipeline the properties of the component can be set.
The OpenPGP Encoder supports individual OpenPGP keys as well as OpenPGP keyring files. The required properties are different depending on whether keyrings or individual keys are used.
Properties Required to Use Individual Keys
If individual keys are used, the following properties must be set:
| Property | Description |
|---|---|
| EncryptData | Whether to encrypt the data. |
| Key | The private key used to sign. This can be the path to a key file on disk, or the ASCII-armored key data itself. Only required if SignData is set to True. |
| Passphrase | The passphrase of the private key used to sign the data. Only required if SignData is set to True. |
| RecipientKey | The public key used to encrypt. This can be the path to a key file on disk, or the ASCII-armored key data itself. Only required if EncryptData is set to True. |
| SignData | Whether to sign the data. |
Here is an example configuration for the OpenPGP Encoder when using individual keys:
Properties Required to Use Keyring Files
If the OpenPGP keys have already been imported to a keyring, a different set of properties is required.
| Property | Description |
|---|---|
| EncryptData | Whether to encrypt the data. |
| HomeDir | The path to the keyring(s) on disk. This should be the absolute path to the directory containing secring.gpg and pubring.gpg. |
| Passphrase | The passphrase of the private key used to sign the data. This is the passphrase of the key specified by UserId. |
| RecipientUserId | The user Id of the recipient. This is used to load the public key used for encryption. |
| SignData | Whether to sign the data. |
| UserId | The user Id of the sender. This is used to load the private key for signing. Passphrase must also be set. |
Here is an example configuration for the OpenPGP Encoder when using keyrings:
Advanced Properties
Advanced properties are not typically required, but offer more granular control over the behavior of the pipeline component.
| Property | Description |
|---|---|
| ASCIIArmor | Whether to ASCII armor the output. If False the output will be raw bytes. |
| CompressionMethod | The compression method used. Possible values are:
|
| EncryptingAlgorithm | The encryption algorithm to use. Possible values are:
|
| Other | Allows additional configuration settings to be set. Please refer to the Other Settings section of the help file for details. |
| PGPParams | Provides an alternative to setting the common properties. All necessary values can be set in one location. Please see the help file for details. |
| ProtectedPGPParams | An encrypted version of PGPParams |
| PGPProviderType | Allows the use of an external PGP implementation like GnuPG. This is not recommended unless you have a specific reason to use this. |
| PGPProvider | This is only used when PGPProviderType is set to External and specifies the path to the provider .dll file. |
| SigningAlgorithm | The signing algorithm to use. Possible vales are:
|
| TempPath | A directory on disk where data is held before processing. This can be used to reduce memory usage when processing large files. |
Creating a Receive Pipeline
When creating a receive pipeline, the OpenPGP Decoder can be used in the Decode stage of the pipeline. After dropping the pipeline component from the toolbox onto the pipeline the properties of the component can be set.
The OpenPGP Decoder supports individual OpenPGP keys as well as OpenPGP keyring files. The required properties are different depending on whether keyrings or individual keys are used.
Properties Required to Use Individual Keys
If individual keys are used, the following properties must be set:
| Property | Description |
|---|---|
| Key | The private key used to decrypt. This can be the path to a key file on disk, or the ASCII-armored key data itself. Only required if the received OpenPGP message was encrypted. |
| Passphrase | The passphrase of the private key used to decrypt. |
| RecipientKey | The public key used to verify the signature. This can be the path to a key file on disk, or the ASCII-armored key data itself. Only required if the received OpenPGP message was signed. |
Here is an example configuration for the OpenPGP Decoder when using individual keys:
Properties Required to Use Keyring Files
If the OpenPGP keys have already been imported to a keyring, a different set of properties is required.
| Property | Description |
|---|---|
| EncryptData | Whether to encrypt the data. |
| HomeDir | The path to the keyring(s) on disk. This should be the absolute path to the directory containing secring.gpg and pubring.gpg. |
| Passphrase | The passphrase of the private key used to sign the data. This is the passphrase of the key specified by UserId. |
| RecipientUserId | The user Id of the recipient. This is used to load the public key used for encryption. |
| SignData | Whether to sign the data. |
| UserId | The user Id of the sender. This is used to load the private key for signing. Passphrase must also be set. |
Here is an example configuration for the OpenPGP Decoder when using keyrings:
Advanced Properties
Advanced properties are not typically required, but offer more granular control over the behavior of the pipeline component.
| Property | Description |
|---|---|
| Other | Allows additional configuration settings to be set. Please refer to the Other Settings section of the help file for details. |
| PGPParams | Provides an alternative to setting the common properties. All necessary values can be set in one location. Please see the help file for details. |
| ProtectedPGPParams | An encrypted version of PGPParams |
| PGPProviderType | Allows the use of an external PGP implementation like GnuPG. This is not recommended unless you have a specific reason to use this. |
| PGPProvider | This is only used when PGPProviderType is set to External and specifies the path to the provider .dll file. |
| TempPath | A directory on disk where data is held before processing. This can be used to reduce memory usage when processing large files. |
Conclusion
After the pipeline components are configured the pipelines would be deployed as normal. At runtime the pipeline will perform the requested operation based on the specified properties. Messages produced by the OpenPGP Encoder will look like any other OpenPGP message, for instance:
-----BEGIN PGP MESSAGE-----
Version: IPWorks! OpenPGP 2016
wYwDh1whig3wymABBACXFQeZGggajxPzZ70X9HFT2wPjzRmOAVpVNxGFaqfDYtgh
TNNI25gtaogSN+xxmZcLJJFuFnpThzA1Q9flAEGElunF5d0oiTCW5+PKSsBPJUhr
7FOkUzewsQS9uTCg9ElPcSu0cy2pE9oxX3SqIsheoo3GAbVfxRT/FqdyY/jSJtLA
VQHfos2znvgztRt8veqtzSobDn/+v0eXW+fMgYwbVvVla2oIr+kotg1PsiJQC7fb
2yi3lnXSZI5poMLyHStWqSOzFIvr7uP7C476GEdgVjYEtOIuHq2CLyCdQ2cOZC27
9K/AAAVkawymUYhwyoVhXLtXO+SSCQx+4am/JB9dhpB+CjHDze9FrXm8Xb282a0x
cIBSLVUX/f1oTqZDjYRaZr6R2KPOnU9xrODXcChUiN0q0o5qbSoI7RWxBUDkHA3s
gBiGoYKPfvIncZMphf0fJC8wZ+EjzUOFn/zvsCoq42XfV+5jSXONb7X5J7QpN95x
myJznggltFLVG846uHnGz/rgHtN5+gZ7uJF5MT3O3A21/vufWGE=
=qg4N
-----END PGP MESSAGE-----
If errors are encountered they will be visible in the Application Event Log. Please contact support@nsoftware.com with any questions, issues, or comments.
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.