Introduction
We are sending end receiving sensitive information over the internet. We want to secure all the messages we are exchanging with our partners.
Background
Microsoft® BizTalk® Server relies heavily on the security provided by certificates. By using certificates for encryption and digital signatures, BizTalk Server can send and receive data that can be trusted. By using certificates for encryption and digital signatures, BizTalk Server can:
- Send and receive data that can be trusted.
- Make sure that the data it processes is secure.
- Make sure that authorized parties receive its messages.
- Make sure that it receives messages from authorized parties.
Creating the Certificates
We will need to create a certificate to use for encrypting and decrypting our secure messaging example.
MakeCert Test Certificate
A MakeCert test certificate is an Authenticode digital certificate that is created by the MakeCert tool. A MakeCert test certificate is a self-signed, root certificate. To create a MakeCert test certificate, use the MakeCert tool as follows:
MakeCert -r -pe -ss TestCertStoreName -n "CN=CertName" CertFileName.cer
Where:
- The
-r option specifies that the certificate is self-signed, that is, the certificate is a root certificate. - The
-pe option specifies that the private key that is associated with the certificate can be exported. - The
-ss TestCertStoreName option specifies the name of the certificate store that contains the test certificate. - The
-n "CN=CertName" option specifies a name for the certificate that can be used with the SignTool command-line tool to identify the certificate. It is recommended that you use a certificate name that clearly identifies the certificate as a test certificate, for example, "WDK Driver Testing Cert - for in-house use only." If the certificate name is not supplied, the default name of the certificate is "Joe's Software Emporium. - "CertFilename.cer" is the file name that contains a copy of the test certificate. The certificate file is used to add the certificate to the Trusted Root Certification Authorities certificate store and the Trusted Publishers certificate stores.
Storing the Certificates - Depending on the purpose of a certificate (signing messages, verifying signatures, decrypting messages, encrypting messages, or party resolution), it must be installed in a specific certificate store. BizTalk Server uses two Windows® certificate stores - the Other People certificate store (in the Local Computer folder) for public keys, and the Personal certificate store (in the Current User folder) for the service account of each host instance for private keys.
Other People certificate store. Public key certificates, as their name implies, are public and accessible by anyone with access to the computer on which they are stored. BizTalk Server retrieves from this store the public key certificates to encrypt messages and to verify the digital signatures for incoming messages. All users can read and use the certificates in this store. The following figure shows the Other People certificate store that BizTalk Server uses for public key certificates.
Figure 1: Other People certificate store
Personal certificate store: BizTalk Server uses private key certificates to decrypt incoming messages and sign outbound messages. Every Windows account enabled to log on interactively on a computer has a personal certificate store that only that account can access. BizTalk Server uses the personal certificate store for the service account of each host instance to access the private key certificates to which each service account has access. The private key certificates must be stored in the Personal certificate store for the service account for each host instance on each computer that has a running host instance that requires the certificate for decryption or for signing outbound messages.
Note: The personal certificate store is also named the MY certificate store when it is used for programmatic operations, such as scripting the importing and exporting of certificates. The following figure shows the Personal certificate store that BizTalk Server uses for private key certificates.
Figure 2: Personal certificate Store
For more information about the certificate stores and the Certificate snap-in for the Microsoft Management Console (MMC), search for "Certificate console" in Windows XP, Windows Server™ 2003, or Windows 2000 Server Help.
Certificates That You Need in Each Store
The following table describes the certificates that you must install in each Windows certificate store.
Table 1 Certificates For Each Windows Certificate Store
| Certificate purpose | Certificate type | Certificate store |
Signing
| Own private key
| 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
| Other People store on each computer that has a host instance that has a receive pipeline with a MIME/SMIME Decoder pipeline component.
|
Decrypting
| 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.
|
Encrypting
| 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).
|
Party resolution
| Partner's public key
| Other People store on the administration computer from which you are configuring party resolution.
|
Solution
Figure 3: Solution Concept
The solution consists of creating two pipelines. A receive pipeline that decrypts the incoming messages and a send pipeline that encrypts the outgoing messages. The example in this solution uses four ports, two for the encryption scenario and two for decryption scenario.
- Plain Receive port that consumes files in a directory to be encrypted. This receive port uses one receive location that uses the standard “
Microsoft.BizTalk.DefaultPipelines.XMLReceive” pipeline. - Enc Send Port that subscribes to the receive plane text port. This send port uses the “
PracticalBTS.EncryptPipeLine.EncSendPipeline” pipeline. The figure below shows the configuration. Notice that in the “Outbound Encryption”, certificate name is set to the certificate in “other people certificates store” for the receiver.
Figure 4: Send Encrypted port settings.
- Enc Receive Port that consumes files in a directory that are encrypted and we want to decrypt them. This receive port uses one receive location that uses the “
PracticalBTS.EncryptPipeLine.DecReceivePipeline” pipeline. The figure below shows the configuration.
Figure 5: End Receive Location port configuration
Notice that we do not specify the certificate to use to decrypt the message. As BTS uses the certificate defined for the BTS group as shown in the figure below:
Figure 6: BizTalk Group properties certificate settings
- Plain Send Port - This port subscribes to the Enc Receive Port and just saves the output in a file so we can check it
Pipelines Implementation
Receive Decryption Pipeline
Figure 7: Receive Decryption Pipeline
The figure above shows the receive pipeline. As you can see, we insert into the decode phase the MIME/SMIME pipeline component. And into the Disassemble pipeline, the XML disassembler pipeline component. There are no special settings for any component in this receive pipeline we just accept the default settings.
Send Encryption Pipeline
Figure 8: Encryption Send Pipeline
The figure above shows the Encryption send Pipeline. In this pipeline, we have the standard XML Assembler pipeline component in the assemble phase and the MIME/SMIME encoder component in the encode phase.
Figure 9: Encoder Pipeline Component Settings
The figure above shows the settings for the MIME/SMIME encoder pipeline component where we enable the encryption and we choose the “DES3” encryption algorithm. In this example, we are not going to sign the messages so we select “NoSign” for the signature sign.
Deploying the solution
- Installing the certificate
- Compiling and deploying the solution
Use the secure message deployment script to deploy the solution.
Using the Code
To test the configuration, copy a sample XML file from the “Data Folders\Sample XML Files” or any other valid XML file and drop it in the folder “Data Folders\SecureMessaging\Encryption\In” after BTS process the message you will find the encrypted file at “SecureMessaging\Encryption\Out”, the encrypted file should look like:
Figure 10: Sample encrypted message
Copy the encrypted message to “Data\SecureMessaging\Decryption\In” and after BTS process the message you will find the plain message at “Data\SecureMessaging\Decryption\out”.
Points of Interest
Certificate Authorization
A message received by adapter "FILE" on receive location
"EncReceive Location" with URI "…\*.txt" is suspended.
Error details: There was a failure executing the receive pipeline:
"PracticalBTS.EncryptPipeLine.DecReceivePipeline,
PracticalBTS.EncryptPipeLine, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=e56921b90feec973" Source: "MIME/SMIME decoder"
Receive Port: "EncReceivePort" URI: "\SecureMessaging\Decryption\In\*.txt"
Reason: Could not validate the Trust Chain of the encryption certificate.
The certificate issuing authority may not be a trusted Certificate Authority.
MessageId: {9C0C7B4B-D2B7-489F-A343-6355F5BFA9AC}
InstanceID: {67753340-9C17-4C7B-8364-501BFD5F2FD3}
Solution
Make sure you have installed the certificate in the trusted Authority folder.
History
Visit www.MoustafaRefaat.com\Bits to find more information.
