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.

This article covers common use cases. Please refer to the help file for additional details.

Contents

  1. Installation
  2. Creating a Send Pipeline
  3. Creating a Receive Pipeline
  4. Conclusion

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:

PropertyDescription
EncryptDataWhether to encrypt the data.
KeyThe 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.
PassphraseThe passphrase of the private key used to sign the data. Only required if SignData is set to True.
RecipientKeyThe 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.
SignDataWhether to sign the data.

Here is an example configuration for the OpenPGP Encoder when using individual keys:

PGP Encoder Properties For 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.

PropertyDescription
EncryptDataWhether 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.
PassphraseThe passphrase of the private key used to sign the data. This is the passphrase of the key specified by UserId.
RecipientUserIdThe user Id of the recipient. This is used to load the public key used for encryption.
SignDataWhether to sign the data.
UserIdThe 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:

PGP Encoder Properties For Keyrings

Advanced Properties

Advanced properties are not typically required, but offer more granular control over the behavior of the pipeline component.

PropertyDescription
ASCIIArmorWhether to ASCII armor the output. If False the output will be raw bytes.
CompressionMethodThe compression method used. Possible values are:
  • zip (default)
  • zlib
  • bzip2
  • none
EncryptingAlgorithmThe encryption algorithm to use. Possible values are:
  • CAST5
  • 3DES
  • AES256
  • AES192
  • AES128 (default)
  • BLOWFISH
  • TWOFISH
  • IDEA
OtherAllows additional configuration settings to be set. Please refer to the Other Settings section of the help file for details.
PGPParamsProvides an alternative to setting the common properties. All necessary values can be set in one location. Please see the help file for details.
ProtectedPGPParamsAn encrypted version of PGPParams
PGPProviderTypeAllows the use of an external PGP implementation like GnuPG. This is not recommended unless you have a specific reason to use this.
PGPProviderThis is only used when PGPProviderType is set to External and specifies the path to the provider .dll file.
SigningAlgorithmThe signing algorithm to use. Possible vales are:
  • SHA1
  • MD5
  • SHA256 (default)
  • SHA384
  • SHA512
  • SHA224
  • RIPEMD160
TempPathA 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:

PropertyDescription
KeyThe 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.
PassphraseThe passphrase of the private key used to decrypt.
RecipientKeyThe 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:

PGP Decoder Properties For 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.

PropertyDescription
EncryptDataWhether 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.
PassphraseThe passphrase of the private key used to sign the data. This is the passphrase of the key specified by UserId.
RecipientUserIdThe user Id of the recipient. This is used to load the public key used for encryption.
SignDataWhether to sign the data.
UserIdThe 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:

PGP Decoder Properties For Keyrings

Advanced Properties

Advanced properties are not typically required, but offer more granular control over the behavior of the pipeline component.

PropertyDescription
OtherAllows additional configuration settings to be set. Please refer to the Other Settings section of the help file for details.
PGPParamsProvides an alternative to setting the common properties. All necessary values can be set in one location. Please see the help file for details.
ProtectedPGPParamsAn encrypted version of PGPParams
PGPProviderTypeAllows the use of an external PGP implementation like GnuPG. This is not recommended unless you have a specific reason to use this.
PGPProviderThis is only used when PGPProviderType is set to External and specifies the path to the provider .dll file.
TempPathA 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.