BizTalk Server 2013: Encrypting and Decrypting a Message
Introduction
There can be scenario's applicable within your enterprise when encryption mechanism for outgoing messages, as well as a decryption mechanism for the inbound messages may be required. In case data in messages is of a sensitive nature, for instance, credit card data or privacy laws are applicable. When BizTalk Server is your messaging broker, you will want to ensure data is secure.
BizTalk Server offers encryption capabilities using certificates, which contain cryptographic key pairs consisting of a public and private key. BizTalk can own the private key for decrypting messages while its public key can be shared with communication partner(s) that can use to encrypt messages. As the message can only be decrypted with the corresponding private key the partner(s) are certain the message can only be decrypted by the owner of the certificate. This means that the private key has to be securely kept and protected by the owner. On the other end BizTalk can send encrypted messages securely to partners by using the public key certificate of each of them. A host can have many public keys for sending encrypted messages, but it can only use one certificate for decrypting messages.
The following table describes the keys and certificates that need to be installed for encrypting and decrypting messages.
| Certificate Purpose | Type of Certificate | Certificate Store |
| Encryption | Partner's public key | Other People store on each computer that has a host instance that has a send pipeline with a MIME/SMIME Encoder pipeline component configured to encrypt messages (Enable encryption property set to True). |
| Decryption | Own private key | Personal store for each service account of a host instance that has a receive pipeline with a MIME/SMIME Decoder pipeline component. |
Every certificate contains a unique identifier called a thumbprint, which BizTalk uses to identify the correct certificate. The thumbprint is calculated by applying a hashing algorithm to the certificate. Thumbprints are used when configuring a host or a send port.
Preparation for encryption or decryption of a message with BizTalk
For sending encrypted messages from BizTalk you will need the public key certificate from the party where you will send the encrypted message to. Create your own self-signed certificate or get one from a Certificate Authority (CA) to send public keys to your communication partner(s) so they can encrypt their messages and BizTalk can decrypt them.
Sending encrypted messages with BizTalk Server
To be able to send encrypted messages with BizTalk Server you will need to install the certificate from communication partner(s) in the Local Computer\Other People store (see MSDN How to Install the Certificates for Encrypted Messages). The next steps will involve creating a custom pipeline using the out-of-the box MIME/SMIME Encoder component:
a) Create a new BizTalk project and add a new send pipeline by right-clicking the project, select Add --> New Item, and select Send Pipeline from the Add New Item dialog. Give the pipeline a name according to your coding standards.
b) Drag the MIME/SMIME Encoder component from the BizTalk Pipeline Components section of the toolbox to the Encode stage of the send pipeline.
c) Select and right-click the component, and select Properties. Change the value of the Enable encryption property from False to True. Choose the encryption algorithm you desire (options are, from strong to weak, DES3, DES or RC2).
d) Right click the project and go to Signing. Sign the project with a strong name.
e) Subsequently go to deployment and give the application a name according to your coding standards.
f) Build and deploy the BizTalk project.
g) Create a send port to deliver the message to the recipient, using any transport adapter desired.
h) Create a send port and give it a name according to your coding standards. Select an appropriate Adapter and choose the send pipeline you deployed.
i) In port choose certificate and select the public-key certificate of the message receiver for the Certificate Name property.
What will happen when messages flow your send port is that encryption will occur inside the encode stage of the send pipeline. The MIME/SMIME Encoder pipeline component within encode stage will encrypt the message by using the public key of the communication Partner(s). This key is stored in the Other People store on the machine of the host instance configured for the send handler. To enable encryption using the MIME/SMIME encoder the Enable encryption property must be set to True!
Receiving encrypted messages with BizTalk Server
To be able to receive encrypted messages with BizTalk you will need to obtain a certificate from a certification authority (CA) containing a private key, or create one using the MakeCert.exe command line tool (see TechNet Wiki article BizTalk Server 2013: Sign and verifying a message). The next steps will involve creating a custom pipeline using the out-of-the box MIME/SMIME Decoder component:
a) Create a new BizTalk project and add a new receive pipeline by right-clicking the project, select Add --> New Item, and select Receive Pipeline from the Add New Item dialog. Give the pipeline a name according to your naming convention.
b) Drag the MIME/SMIME Decoder component from the BizTalk Pipeline Components section of the toolbox to the Decode stage of the receive pipeline.
c) Select and right-click the component, and select Properties.
d) Right click the project and go to Signing. Sign the project with a strong name.
e) Subsequently go to deployment and give the application a name according to your naming convention.
f) Build and deploy the BizTalk project.
g) Create a receive port and a receive location to accept the encrypted message from the sender, using an appropriate transport adapter. Give the port and the receive location a name according to your naming convention.
h) Open the BizTalk Administration Console, and navigate to Platform Settings. Select Hosts. Right click the BizTalk host that will receive the encrypted message and select Properties.
i) Specify the certificate BizTalk will use to decrypt the messages. Paste the thumbprint of this certificate into the Thumbprint field in the Certificates section of the Host Properties dialog box.
When encrypted messages are received the decryption in BizTalk will occur inside the decode stage of a receive pipeline. The MIME/SMIME Decoder pipeline component decrypts the message by using the BizTalk Server private key that is stored in the personal store of the service account of a host instance configured for the receive handler.
See Also
Based on the security policies in your company, you may want to consider the questions provided through MSDN:
BizTalk Server supports encryption of outbound messages and decryption of inbound messages based on Secure Multipurpose Internet Mail Extensions (S/MIME). BizTalk Server uses S/MIME version 3 for encryption of outbound messages, and S/MIME versions 2 and 3 for decryption of inbound messages:
Beside MSDN there is an interesting article on the Code project web site that contains a BizTalk project with guidance on securing messages with encryption:
Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.