Introduction

By digitally signing a message you can prevent tampering with a message and guarantee it is authentic. You can apply your unique digital mark to the message. This digital mark includes a certificate and public key. The public key is sent to recipients of your message. The recipient can use the public key to verify that message is from you and that it has not been altered in its transit.

Signing messages in BizTalk Server

In BizTalk Server signing a message can be achieved by using the standard encoding component (S/MIME) in the send pipeline. This component will use a private key to sign outgoing messages. The encoding component then needs to be configured to sign all outgoing messages. The signing key and certificate that are used to sign the outgoing message is retrieved from the personal certificate store for the host service account, where the pipeline is running.

The following table describes the keys and certificates that need to be installed to sign and verify messages.

Certificate Purpose	Certificate Type	Certificate Store
Signing	Own private key with associated certificate	Personal store for each service account of a host instance that has a send pipeline with a MIME/SMIME Encoder pipeline component configured to sign messages (Add Signing Cert To Message property set to True).
Verifying signature	Partner's public key, found in Partner’s certificate	Other People store on each computer that has a host instance that uses a receive pipeline with a MIME/SMIME Decoder pipeline component.

Personal Certificate

BizTalk Server can only supports one personal certificate for each BizTalk group. A BizTalk group represents an entire enterprise, a department, a hub, or another business unit. The personal certificate that is used by the BizTalk group is specified by setting the thumbprint of the personal certificate in the BizTalk group properties. Therefor the BizTalk group is limited by using one certificate to be used for signing a message. So make sure that the signing certificate is available in the certificate store of the service account of the hosts, where the send pipelines are running.

Request a digital signature certificate with a private-public key pair from a Certificate Authority (CA) for BizTalk Server to use. Send the certificate with the public key to the communication partner(s) that need to verify the digital signature on your messages. You can also use makecert.exe command line tool to create the certificate. In this article the makecert.exe will be discussed to create a self-signing certificate.

View Certificates

To see what certificates you currently have on your machine you need to open a Microsoft Management Console through Start, select run and type mmc.exe. Then click File, Add/Remove Snap-in, select Certificates from the left list, click "Add". Select "My user account", which will mean the snap in will show certificates that are stored specifically for your Windows user account. Select Certificates from the list again and "Add" it, then this time select "Computer account". This snap in will show certificates belonging to the machine specifically, and will apply across all accounts. Finally press Finish, then OK. This MMC arrangement you have created is available by default (out-of-the box), so it is advisable to save it in case you want to get back to it in the future.

Makecert command tool

The makecert is a tool available through Windows Software Development Kit (SDK) for Windows8. For testing and development purposes you may want to create your own Certificate Authority (CA) certificate and client certificate. The following command can be used to create your certificate authority, along with an explanation of each of the options you pass to makecert command line tool:

makecert -n "CN=My Local Certificate Authority"
                 -cy authority
                 -a sha1
                 -sv "My Local Certificate Authority Private Key.pvk"
                  -r
                  "My Local Certificate Authority.cer"

-n                     : The certificate name. CN stands for Common Name and is the name that
                           identifies the certificate. For websites, this is their domain name.
-cy authority : Creates a certificate authority certificate
-a sha1            : Use the SHA1 algorithm
-sv                    : The private key to use, or create.
-r                     : Create a self-signed certificate (so that you are the root of the certificate chain)
*.cer                : The filename to export to

Since a private key before has not been created before, the -sv option will create one for you. Therefore, Makecert will ask for a password that will lock the private key.

The new certificate authority certificate can now be installed into the trusted store. You can go to your MMC console you can create or have created (see View Certificates). In the MMC right click on "Trusted Root Certification Authorities" , then go to "All Tasks", and select "Import". Select the new certificate, and when it asks you where to put the certificate, ensure that it goes into "Trusted Root Certification Authorities". Your computer will now implicitly trusts all certificates signed by that new certificate authority.

Note: A security warning will be given through a dialog box: You are about to install a certificate form a certification authority (CA) claiming to represent: My Local Certificate Authority. Windows cannot validate that the certificate is actually form "My Local Certificate Authority".

Next step is to create a client certificate that is signed by the new certificate authority. Next step is to create a client certificate that is signed by the new certificate authority. This can be done by either

creating a certificate and store it and its private key in the Windows Certificate Store or
to create it and its private key as files on the hard drive.

The following command can be used to create a certificate and store it and its private key in the Windows Certificate Store:

makecert -n "CN=mysite.com"
                -ic "My Local Certificate Authority.cer"
                -iv "My Local Certificate Authority Private Key.pvk"
                -a sha1
                -sky signature
                -pe
                -sr currentuser
                -ss my
                 "mysite.cer"

-n                      : The certificate name. CN stands for Common Name and is the name that
                             identifies the certificate. For websites, this is their domain name.
-ic                      : The certificate to use as the root authority
-iv                    : The private key of the root authority certificate
-a sha1             : Use the SHA1 algorithm
-sky signature : Indicates that the key is used for a digital signature, exchange can used to indicate for key encryption and key exchange
-pe                    : Makes the certificate's private key exportable
-sr                     : The certificate store location to hold the certificate (current user or local machine)
-ss                     : The certificate store name. my is the Personal store
*.cer                 : The filename to export to

Note: -sr parameter is current user, however depending which host instance will access the certificate store you will need to specify the appropriate user account.

When executing this command you will be asked for the certificate authority's private key's password, so that it can use the private key to sign the client certificate. It then will store the client certificate (and its private key) in the current user's Personal store. A copy of the client certificate will also be created on the hard drive.

The other way the client certificate can be create is to create it and its private key as files on the hard drive. Both can then be combined into a single PFX (Personal Information Exchange) file, which can be imported into your certificate store if you wish. To do this, the following makecert command can be executed:

makecert -n "CN=mysite.com"
                 -ic "My Local Certificate Authority.cer"
                 -iv "My Local Certificate Authority Private Key.pvk"
                 -a sha1
                 -sky signature
                 -pe
                 -sv "mysite.com Private Key.pvk"
                "mysite.com.cer"

-n                        : The certificate name. CN stands for Common Name and is the name that
                                identifies the certificate. For websites, this is their domain name.
-ic                       : The certificate to use as the root authority
-iv                       : The private key of the root authority certificate
-a sha1              : Use the SHA1 algorithm
-sky signature : Indicates that the key is used for a digital signature, exchange can used to indicate for key encryption and key exchange
-pe                      : Makes the certificate's private key exportable
-sv                       : The private key to use, or create.
*.cer                   : The filename to export to

By executing this makecert command you will be asked for a password with which you lock the new private key you are creating for this certificate. It will also ask for the password of the certificate authority's private key. It subsequently creates the client certificate on the hard drive and also the private key in a PVK file.

To combine the private key and the certificate into a PFX file, the following command with Pvk2Pfx command line tool:

pvk2pfx -pvk "mysite.com Private Key.pvk"
                -spc "mysite.cer"
                -pfx "mysite.pfx"
                -pi YourPassword

-pvk : The PVK file to lock away in the PFX
-spc : The certificate to put in the PFX
-pfx : The PFX file to create
-pi   : The password of the private key

A PFX file will be created, which you can import into the Personal store using MMC in a similar fashion as you did with the certificate authority certificate. Windows uses .pfx for a PKCS #12 file. This file can contain a variety of cryptographic information, including certificates, certificate chains, root authority certificates, and private keys. Its contents can be cryptographically protected (with passwords) to keep private keys private and preserve the integrity of the root certificates. You can import the PFX file when logged in under account that is used by the host instance that access the certificate store.

Signing and verifying a message

BizTalk Server uses a private key to sign outgoing messages. This can be achieved by using the standard encoding component (S/MIME) in the send pipeline. You can configure the encoding component to sign all outgoing messages. The signing key and certificate that are used to sign the outgoing message are retrieved from the personal certificate store for the host service account where the pipeline is running. See also Signing messages in BizTalk Server.

Preparation

Request a digital signature certificate with a private-public key pair from a Certificate Authority (CA) for BizTalk Server to use or use the one generated by yourself using the makcert tool (see Makecert command tool). Send the certificate with the public key to the communication partner(s) that need to verify the digital signature on your messages. You can also use makecert.exe command line tool to create a self-signed certificate.

For signing messages you need to log on the BizTalk machine with the service account for the host instance running the handler that will send messages to partner(s). Install the private key certificate that BizTalk Server will use to sign messages in the personal store for the service account.

For verifying messages you need to install the public key certificate of your communication partner(s) in the Other People store. This certificate is used to verify the digital signature of the messages of your partner(s).

Custom pipeline using MIME/SMIME Encoder Component

The following steps describe how you to create a custom pipeline to enable digital signing of messages in a send port:

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. Specify a name for the pipeline according to your naming convention.
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 Signature Type to ClearSign or BlobSign. This will ensure that the certificate will be appended to the message and/or encoded. The other option is NoSign (default), which is not applicable as message will be not be signed.
d) In case you use your own CA, you set the Check Certificate Revocation property of the S/MIME Encoder to False in your pipeline. If you use the your self-created CA then you can run into an error like "The revocation status of the certificate used to sign the message is unknown."
e) Right click the project and go to Signing. Sign the project with a strong name.
f) Subsequently go to deployment and specify a name for the application according to your naming convention.
g) Build and deploy the BizTalk project.
h) Create a send port to deliver the message to the recipient, using any transport adapter desired. You could choose FILE first for testing purposes.
i) In the Administration Console right click BizTalk Group. Choose certificate and add the certificate to will be used for signing. Click Ok.

Signing messages in BizTalk occurs inside the encode stage of a send pipeline. The MIME/SMIME Encoder pipeline component within the pipeline signs 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 send handler. To enable signing using the MIME/SMIME encoder the Signature type property of the MIME/SMIME encoder component must be set to either Clear- or BlobSign. Both types append the signature to the message, where only BlobSign can be used in combination with encryption.

Custom pipeline using MIME/SMIME Decoder Component

The following steps describe how you to create a custom pipeline to verify a digital signed message in a receive port:

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. Specify a name for the pipeline according to your naming convention.
b) Drag the MIME/SMIME Encoder component from the BizTalk Pipeline Components section of the toolbox to the Decoder stage of the receive pipeline.
c) Leave the properties as they are (default).
d) In case you use your own CA, you set the Check Certificate Revocation property of the S/MIME Decoder to False in your pipeline. If you use the your self-created CA then you can run into an error like "The revocation status of the certificate used to sign the message is unknown."
e) Subsequently go to deployment and specify a name for the application according to your naming convention.
f) Build and deploy the BizTalk project.
g) Create a receive port and a receive location to accept the signed message from the sender, using an appropriate transport adapter. Specify a name for the port and receive location according to your naming convention.
h) Open the BizTalk Administration Console, and navigate to Platform Settings. Select Host Instances. Right click the BizTalk host that will receive the signed message and select Properties.
i) Specify the certificate BizTalk will use to validate incoming messages. Paste the thumbprint of the certificate into the Thumbprint field in the Certificates section of the Host Properties dialog box.

Verifying messages in BizTalk occurs inside the decode stage of a receive pipeline. The MIME/SMIME Decoder pipeline component within the pipeline verifies the signature by using the partner's public key that is stored in the Other Peoplestore on the machine that has a host instance configured for the receive handler.

Sample code for signing and verifying a message can be found on MSDN Code Gallery: BizTalk Server 2013: Sign and verifying a message. This sample is also applicable for previous BizTalk versions i.e. the principles/concepts are the same.