Requirements:
/n software Adapters for Microsoft BizTalk
GnuPG for Windows
Introduction
The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk
Messaging Pipeline as well as a variety of pipeline components including Zip, Gzip, ACH, and PGP. The /n software Adapters extend the features of BizTalk with advanced Internet communications and secure messaging
capabilities.
There are many different BizTalk adapters currently supported: AS2 Adapters for EDI communications, FTPS, FTP,
SFTP, SSH, Email adapters, etc. These adapters have completed the official adapter certification program (administered by Unisys)
established by Microsoft for BizTalk server, which tests for scalability
and interoperability with Microsoft BizTalk Server.
This guide will focus specifically on the PGP Pipeline component, which is used to perform a combination of signing and encrypting messages as well as decrypting and verifying.
If you're interested in using OpenPGP encryption in your BizTalk solution, you're in the right place. Before you continue reading, I recommend that you go ahead and download the product and follow along with me through the tutorial.
Contents
- Compiling The OpenPGP Provider Class
- Creating A Send Pipeline
- Creating A Receive Pipeline
- Putting It All Together
- BizTalk Server Project used in this tutorial.
- Port bindings used in this tutorial.
After you run the setup application, all of the necessary files will be installed on your system.
This includes an OpenPGP Provider class that will serve as the bridge between the OpenPGP Pipeline components
and the actual OpenPGP Provider. It is not required that you use GnuPG as your OpenPGP Provider, but the
OpenPGP Provider class that ships with our product is written for this provider.
The first step will be to compile the OpenPGP Provider Class. In this example, we'll be using GnuPG as our OpenPGP provider, so all we'll need to do is open the project file in Visual Studio and build the project.
This project is installed into the demos directory. The default location of this will be:
C:\Program Files\nsoftware\BizTalk Adapters v3\demos\gnupg_provider
After compiling, you should see that a dll was built (GnuPG_Provider.dll) in the bin/Debug directory.
You may also notice that there are some other files in this demo directory. We'll use those later when configuring the PGPParams.
Now that we've compiled the OpenPGP Provider class, we're ready to create a new BizTalk project and setup the OpenPGP Pipeline Components.
The send pipeline will make use of the OpenPGP Encoder. Let's first review the properties that we'll use.
- EncryptData
A Boolean to tell the component whether or not to encrypt the data.
- PGPProvider
The full path to the dll we compiled in Part 1.
- PGPParams
This is where we'll specify all of the parameters that will be used by GnuPG. These are:
| Parameter | Description |
| gpg-path | The path to the OpenPGP executable for the desired implementation. |
| homedir | The directory containing the public keyring, secret keyring and trust database. |
| passphrase | The passphrase to access the secret keys in the secret-keyring. |
| userid | The identifier used to identify a secret key within the secret-keyring. |
| recipient-userid | The identifier used to identify a public key within the public keyring. |
- ProtectedPGPParams
This is used to hold any of the above PGPParams that you want to be protected (encrypted). You can set this to none, all, or any of the PGPParams that you like. At runtime the component will decrypt the value specified here and combine that with the values specified in PGPParams to get a complete list of all the parameters set.
- SignData
A Boolean to tell the component whether or not to sign the data.
- TempPath
This can be set to a valid path or the %TEMP% macro so at runtime temporary files will be used instead of processing all data in memory. If you are using large files or some of your input or output is in binary (not ASCII), this should be set.
Now that we know what the properties are, first we'll create a new BizTalk Server Project named "PGP Pipeline Demo".
To this we will add a new receive pipeline called "PGPDecoder.btp" and a new send pipeline called "PGPEncoder.btp".
When viewing the PGPEncoder.btp, if you look at the icons in the toolbox you'll see that the OpenPGP Encoder is not yet present.
To add the pipeline components to the toolbox, right click on the toolbox in the BizTalk Pipeline Components section and select "Choose Items".
In the Choose Toolbox Items dialog, select the BizTalk Pipeline Components tab and scroll down to the OpenPGP Encoder and OpenPGP Decoder components. Select both at this time and hit the OK button to finish adding the components to the toolbox.
Now that the icons are present on the toolbox, we'll drag and drop the OpenPGP Encoder onto the Encode stage of the pipeline.
Select the OpenPGP Encoder and you will see the properties mentioned above are available. First, set SignData to True so our
data will be signed and encrypted (EncryptData is true by default). Then, we'll go ahead and set the TempPath property to %TEMP%. Next, we'll specify the path to the OpenPGP Provider dll. So, I'll set PGPProvider to:
C:\Program Files\nsoftware\BizTalk Adapters v3\demos\gnupg_provider\bin\Debug\GnuPG_Provider.dll
Next, we need to set the PGPParams property. In this demo, we'll be using the files that are installed alongside the
PGP Provider demo to perform the encryption, decryption, singing, and signature verification, so we'll set the homedir parameter to this location.
The userid and recipient-userid will both be "PGPTest" and the passphrase will be "testpgp". And lastly, the gpg-path parameter will point to the location of GnuPG.
In this case, I am choosing not to specify any parameters in the ProtectedPGPParams property. Click the ellipses of the PGParams property to open a multi-line editor.
Below is a screenshot of what your PGPParams should look like.
Creating the receive pipeline will be almost the same as the send pipeline. We'll select PGPDecoder and drag and drop the OpenPGP Decoder onto the Decode stage of the pipeline.
You'll notice that the properties are almost the same as with the Encoder, the only difference is that EncryptData and SignData are not present.
This is because the Decoder will handle the incoming data regardless of the combination of signing and encrypting that was used.
Set the PGPProvider to the path of the OpenPGP Provider DLL as above, and also set the TempPath to %TEMP% as before.
Then, in the PGParams property we only need to specify the gpg-path, homedir, and passphrase parameters to the same values used above.
Now your receive pipeline configuration should look like:
In this section, we'll set up some ports to test out our new pipelines. Before we do, that we'll need to deploy our pipelines as normal. So in Visual Studio, we'll go to the Build menu and select "Deploy OpenPGP Pipeline Demo".
Once the pipeline is deployed we'll create the following directories on disk to hold the files before and after encryption.
C:\_incoming\PGPEncrypted
C:\_incoming\PGPDecrypted
C:\_outgoing\PGPEncrypted
C:\_outgoing\PGPDecrypted
Now, we'll create two receive locations and two send ports, all of type file.
We'll use the PGPEncoder pipeline to encrypt files that were placed in the C:\_outgoing\PGPDecrypted folder into the C:\_incoming\PGPEncrypted folder.
We'll use the PGPDecoder pipeline to decrypt files that were placed in the C:\_outgoing\PGPEncrypted folder into the C:\_incoming\PGPDecrypted folder.
First, lets create our receive location and send port to encrypt a file.
I'll name my first receive location "PGPReceiveDecrypted" and point it to C:\_outgoing\PGPDecrypted. Leave the Receive pipeline as the default PassThruReceive.
I'll name my send port "PGPSendEncrypted" and point it to C:\_incoming\PGPEncrypted. Set the Send pipeline to PGPAssemble, which should be present in the available pipeline options.
Lastly, we'll set the Filter for the send adapter. Set BTS.InboundTransportLocation to the URI of our PGPReceiveDecrypted receive location.
Next, we'll create our second receive location and send port to decrypt a file.
I'll name my receive location "PGPReceiveEncrypted" and point it to C:\_outgoing\PGPEncrypted. Set the Receive pipeline to PGPDisassemble.
I'll name my send port "PGPSendDecrypted" and point it to C:\_incoming\PGPDecrypted. Leave the Send pipeline as the default PassThruTransmit.
And lastly, we'll set the Filter for the send adapter. Set the BTS.InboundTransportLocation to the URI of our PGPReceiveEncrypted receive location.
Now we have everything setup and ready to test. Enable the receive locations and start the send ports, then drop a file into the C:\_outgoing\PGPDecrypted location.
You should see BizTalk pick this up and if you open the resulting file in C:\_incoming\PGPEncrypted you should see something like:
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.9 (MingW32)
hQIOAz0vgcjEBCzREAgAwRMIp2aXaJYmsc/MLX3Dy3qUHjuGEznRyrI0L7iKIHVX
z1ksQHJt6quFoMxd/y9lrthE3iMHuEx342+qggVfLvArHnUd1MK+/PJCAkZCEfWu
XH8cSmyHq9jeib3xFQbKjnj+bUJaIvieOkZUJOaj0MMs+zoKGATUqZEbgG54STkB
/AeA1a2FEkCIez7joCRBSbDVnp1Vhwmsalw5CrqmbCaKUJbku6gKjbotF4ZUrEEA
zJr3oLRq5oBiFsuWeq9kIioHCf9B2ToNLyooPLRhpUMp4ptBvHjCw89/eqlVGH8s
T5LuMvt64LzfHQ9W95QQZ5tJAE9AmL8SlmsoZr53rQf/aOORNTD5hxMURCc3LvLO
J00RG3+yV3I3gRztGnPlE1nl6Maba/sv8YSUOKe7m8j583hxtOzo586eG2ZLTiDq
UbmZGqZwkE+nienBkrDXPWwNhpOz6QVwJNSco3qhqn23k9wDmrGPWsy3h4rqWgzU
fLqGDeHvfesi1YyVfvFFnFW/ejzTHbKXQhFiey+8QXmU5aMpyblnN3ImQIUdUH5m
0uOgNchgc4cW2hjPZJmAC8v4/9lfL3zMU34j0453dPfoOdob47YWTrMFDTMeISO8
JRe0HjIytsHYTn/kIakv+XlLDN8NN3cfSuCtqEfZ2LbCv7idsFJ+8jZAl1pTaMKM
eNKSAd7p6UguDaSTQEMBoPVw1yEq2fW4JkgWKUX0NTa0ghBYaSz5851CfBrPe732
TooDAJ6zR5OIgVOx81fkVjijWIwhmqwlryYAohVXg6yGb06RFnGxwEw4Qv0k6EEJ
vMqk0ZYKHGOoRKTLSPwm4DYYSVUGWb3WujEzFVAU6v3FHIZWPztwD3ac3kwaUk+b
Ln0MT/Y=
=stz4
-----END PGP MESSAGE-----
To test the reverse, we'll take the encrypted file we got above, and place that in C:\_outgoing\PGPEncrypted.
The resulting file in C:\_incoming\PGPDecrypted should contain the original file contents.
This concludes the tutorial. You may also use the resources listed at the top as an example of the pipeline project and configurations used above.
This article demonstrates the ease of use of the OpenPGP Pipeline Components in particular, but
/n software provides a
full set of adapters for connecting to various types of internet
servers.
The adapter properties are kept to a minimum for simplicity, but we make an effort
to provide those properties that are necessary for effective control over configurations.
We appreciate your feedback. If you have any questions, comments, or
suggestions about this article please contact our support team at
kb@nsoftware.com.
