Building a Complete Certificate Scenario With BizTalk Server 2006

I’m working on a BizTalk project where we’re testing the use of security certificates, and I’ve just had a bear of a time finding thorough walkthroughs of setting this up. It’s barely mentioned in the available BizTalk books, and while the BizTalk 2004 whitepaper (which has now been added to the BizTalk 2006 documentation) has some very nice coverage, it wasn’t exactly what I wanted. So, after much toil (and threats of lighting myself on fire), I present a step-by-step for building a certificate scenario using test certificates.

I’ve used the .NET Framework tool makecert to build local test certificates. The hardest part for me was getting the correct series of command line parameters to build the cert I wanted. I finally put together one that worked:

makecert -r -pe -n “” -b 02/01/2007 -e 01/01/2036 -eku -ss my -sr currentuser -sky exchange -sp “Microsoft RSA SChannel Cryptographic Provider” -sy 12

For a description of the available parameters, check out the MSDN page for makecert.

What this did, was create a (self-signed) certificate, and placed it in my “current user” personal store.

You can see from the shot here that the certificate’s private key is included.

So first, I exported the private key certificate out. To do this, I selected the certificate, right-clicked, and chose export. As you can see below, I chose to Yes, export the private key and created the .pfx file.

Next I exported the public key. This is the one that I would give partners. I selected the certificate again, right-clicked and exported. This time, I chose not to export the public key, and created a .cer file.

Now I jumped into the Other People certificate store to import the public certificate (.cer file). Why? Well the Current User/Personal/Certificates store is where certificates go for decrypting inbound messages. This store is account specific, so I’m using the account that the receiving host is running under. The store under the Local Computer/Other People/Certificates is for public certificates used to sign outbound messages. The “other people” then have a corresponding private key to decrypt the inbound messages.

As you can see here, the public certificate doesn’t have a private key attached.

Within BizTalk, I created both send and receive pipelines. The send pipeline has the MIME/SMIME Encoder component included with the Enable Encryption set to true.

The receive pipeline has the MIME/SMIME Decoder component.

Within my send port (which uses my new send pipeline), I set up the Certificates tab to point to the public certificate. The Browse button pulls up any certs in the Other People store.

Finally, the BizTalk Host that contains the receive pipeline (and port) must be configured. The host has a Certificates tab where once again I can browse. This time, it looks for the Personal store of the BizTalk Host account.

After creating a local folder structure for dropping off and picking messages up (e.g. pick up clear text, drop off encrypted, pick up encrypted, drop off clear text), and setting up the ports, the “encryption” send port outputs the following message …

After picking the encrypted message up, BizTalk decrypts it and sends me this …

There you go. Let me tell you, there was a LOT of silent fist-pumping in my office this afternoon after I got this working. Hopefully someone else finds this useful as well!

Technorati Tags:

Author: Richard Seroter

Richard Seroter is Director of Developer Relations and Outbound Product Management at Google Cloud. He’s also an instructor at Pluralsight, a frequent public speaker, the author of multiple books on software design and development, and a former editor plus former 12-time Microsoft MVP for cloud. As Director of Developer Relations and Outbound Product Management, Richard leads an organization of Google Cloud developer advocates, engineers, platform builders, and outbound product managers that help customers find success in their cloud journey. Richard maintains a regularly updated blog on topics of architecture and solution design and can be found on Twitter as @rseroter.

35 thoughts

  1. Hi,

    Thanks alot for such a wonderful article!! It really worked . Even microsoft documentation does not have such a clear explanation!


  2. Thank you. That was a really cool article. I am very new to the security business and your article has really helped me understand the scenario, with great simplicity.

  3. Hi Richard,
    I tried implementing the same thing in my sample application. But i encountered the following error –
    There was an authentication failure. “Decoder could not find the decryption certificate in the “Current User\Personal” certificate store. Unable to decrypt the message. “.

    I have my certificate installed in perosnal store..
    Any idea as why I am getting this error ?

  4. Richard,
    I used your step by step process to create the Certificate and the receive and send ports. I am able to generate an Encoded file but when by Receive Location picks up the file to decode is gets suspended with the message
    “The published message could not be routed because no subscribers were found. This error occurs if the subscribing orchestration or send port has not been enlisted, or if some of the message properties necessary for subscription evaluation have not been promoted. Please use the Biztalk Administration console to troubleshoot this failure. “.

    I am logged in with the BizTalk Service a/c on the server. And when I try to resume it gives the following error –

    “There was a failure executing the receive pipeline: “Microsoft.BizTalk.DefaultPipelines.XMLReceive, Microsoft.BizTalk.DefaultPipelines, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35” Source: “XML disassembler” Receive Port: “TestCert_PickEncodedFilePort” URI: “C:\BaanEDI\Test\ThomsonTestFiles\RL_PickupEncodedText\*” Reason: No Disassemble stage components can recognize the data. ”

    I am assuming this is caused by the XML Dissembler because it the ReceivePipe failed to Decode the Data in the Encoded file.
    Could it be failing because there was an error in Encodeing ?


  5. Hi Indira,

    Your receive pipeline is set to decode, and you have all the certs in the riht spots? Your assumption appears right, that you have no subscribers since you still have an encoded and untyped message.

  6. hey, Richard,

    nice post!! thanks!! I followed your post and it worked very well. Just have one issue here:

    the ‘Encrypted’ file is a base64 encoded. I am no expert in cryption, but according to a colleague that base64 is not really encrypted.

    and I tried to set the encoding to 8bit for the mime pipeline components. if i did not use encryption, the received file will still be 8bit encoded. but if i use a certificate to encrypt it, the encoding became base64. I want the encrypted file to be 8bit/16bit encoded, can you please help me out?

    a lot of thanks!!

    merry x-mas!

  7. Hi Richard,

    Your post helped me out enormously. However, i had to do an additional step to make the encryption/decryption work: i had to import the newly generated (and exported) certificate into the “Trusted Root Certification Authorities” folder whilst logged on under the BizTalk host account. This to avoid the following (edited) error message published to the event log:

    Event Type: Error
    Event Source: BizTalk Server 2006
    Event Category: BizTalk Server 2006
    Event ID: 5754
    Date: 3/1/2009
    Time: 10:12:29 AM
    User: N/A
    Computer: …
    A message sent to adapter “FILE” on send port “…” with URI “…” is suspended.

    Error details: There was a failure executing the send pipeline:

    Reason: Could not validate the Trust Chain of the encryption certificate. The certificate issuing authority may not be a trusted Certificate Authority.

    Did I miss something?

    1. Hey there,
      I don’t think you missed something. I’m no certificate expert, but working with self-signed certs can be tricky and trust relationships aren’t always explicit. Setting up the trust as you did may be necessary.

  8. Hi!

    I can´t use your makecert example. It gives me an error “too many parameters”.

    Is that correct?


  9. Hi Richard,

    Is there a particular setting in SEND port when outputting a decrypted message. Here is what I did.

    My Receive Location is using the EncryptReceive Pipeline (with an MIME decoder and XML assembler)

    My send port is using a filter for BTS.receiveportname = EncryptedRcvPort.

    But BizTalk says there is no subscriber? Am I missing something?

  10. Shariq, interesting that you get a subscriber error. Are you sure, absent the encryption/decryption part, that the connection between your receive port and send port is working? Or are there errors preventing data from hitting the MessageBox? If a message suspends, then you can see if its context properties match your subscription, but it seems you aren’t even getting that far ..

  11. This article is very useful. I’m trying to do it by myself and want to know what is the tool listed in the article to display the certificate (CompleteConsole)? Is it comes with BizTalk, Windows or a seperate tool needs its own install?

  12. Hi,

    Thanks for all of your help.
    we need similar process for encryption and decption of files. but there is small differnce.
    we need to encrypt the file using biztalk and need to decrypt using tool. i am able to encrypt the file successfully using Biztalk. Now using code i am able to decrypt the encrypted file.

    But in decrypted file i am seeing each character appended with ”, like below. not sure how to fix this issue. any help is greatly appreaciated.

    <?xml version=\"1.0\" encoding=\"utf-

  13. strange.. these characters are converted to normal text even in this comments. looks there is snall trick here.

    < ? x m l v e r s i o n = \ "\ 01.0\"

  14. FYI… the makecert example has fancy double quotes (“”) instead of simple double quotes (“”). Replace the fancy with the simple or you will get a “Too many paramters” error.

  15. Can I use any other tool instead of Makecert? Business partner needs a key with either DSA/RSA algorithm with 1024/2048 length.
    And also, I assume this can be used along with any SFTP adapter?


    1. You SHOULD be using a legit cert from a real authority and not makecert anyway! And this works fine real certs. I haven’t done an end to end case with the 3rd party (or now native) SFTP adapters, but I don’t see why there’d be any issues.

  16. Hello Richard, I have followed the steps specified on the article, however after loading the certificates on the specified stores I am getting following error..

    The Messaging engine failed to process a message submitted by adapter:FILE Source URL:D:\Test\*.xml. Details:No subscriber owned the required decryption certificate to receive this message.
    Please verify the host that the intended subscriber is associated with owns the appropriate decryption certificate.

    I can see the private key certificate loaded on the Personal store for the account the Host Instance is configured to run under.

    Thanks in advance.

  17. I’m also getting the

    Details:No subscriber owned the required decryption certificate to receive this message.
    Please verify the host that the intended subscriber is associated with owns the appropriate decryption certificate.

    I’ve checked that the host is using the correct certification.

    1. OK I have experienced the same error as these posts and found the resolution. My setup involved receiving an encrypted file, then processing in an orchestration then passing onto a send port. I assumed the host that needed the cert adding to it was the one the receive location used, but no!! It all worked perfectly when I removed the cert from this receiving host and added it to the host the orchestration used!.

      Hope this solves this issue for someone else.

  18. Hi, we have a problem receiving a message with the receive pipeline: “There was a failure executing the receive pipeline: “ReceiveSMIMEPipeline.ReceiveSMIME_Pipeline, ReceiveSMIMEPipeline, Version=, Culture=neutral, PublicKeyToken=6fd9020324a3f9b2” Source: “MIME/SMIME decoder” Receive Port: “PUERTO” URI: “/TEST_PRE/BTSHTTPReceive.dll” Reason: There was an authentication failure. “The hash for the message is not valid. The message may have been tampered with.”.

    We don’t understand the problema because it looks correctly configured and it appears to be an error inside the pipeline component MIME/SMIME decoder which I cannot debug. Any idea?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.