Attention: We are retiring the ASP.NET Community Blogs. Learn more >

Biztalk ESB Toolkit - All About Itinerary Designer Security

There is a new feature in the ESB Toolkit 2.0 that let you protect the sensitive information embedded into an Itinerary model such as passwords, connections strings, credentials, etc.Let start with some details about the model properties that may be protected and also the encrypted data embedded into the exported itinerary.First of all, the protection is being done by encrypting the sensitive data with an X.509 Certificate selected in the “Encryption Certificate” property located at the model level settings. Here are the basic operations on setting certificate in this property: (Note: If you already read this from the documentation, you can bypass it and go down to “Certificate Validation Settings” section.)  

 

To select the X.509 certificate for an itinerary:
  1. In the Itinerary Designer Properties window, expand the Encryption Certificate property, and then click the Store Location drop-down list, and select the CurrentUser or LocalMachine. This associates the X.509 certificate store with the current user or the local computer.
  2. In the Properties window, click the Store Name drop-down list and select the value which corresponds to your certificate store.
  3. In the Properties window, click the ellipsis button (...) next to the Encryption Certificate property, and then select the X.509 certificate in the Select Certificate dialog box.
  

 

To remove the X.509 certificate from an itinerary:

 In the Itinerary Designer Properties window, expand the Encryption Certificate property, and then set the Store Location property to a different value. This disassociates the old certificate with the BizTalk ESB Toolkit itinerary model.

 

To disable the X.509 certificate validation: For those scenarios like Development environments where you may not have available Certificates or you don’t want to use security, you can disable this feature by opening the Registry Editor, navigate to the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk ESB Toolkit\2.0\Designer, and then set the RequireX509Certificate property value to false.  

 

Note:
If you installed the BizTalk ESB Toolkit on an operating system that has 64-bit support, the subkey is HKEY_LOCAL_MACHINE\SOFTWARE\SysWOW64\Microsoft\BizTalk ESB Toolkit\2.0\Designer.

 

Notice that you may find other ways to do this like the one described here. However I would strongly suggest using the above steps because that’s the way it was designed the certificate usage ON/OFF switch functionality.   

 

Certificate Validation Settings: The certificate is used for encryption but is also validated before using it. The validation behavior and settings are controlled by the attributes values located in the esb.config file in the following section: 

 

<esb>    <!-- validation settings used to validate the encryption X509 Certificate -->    <x509CertificateAuthentication certificateValidationMode="ChainTrust"                                    revocationMode="Online" />

 

You may have probably noticed that these attributes resemble the WCF Certificate Authentication Properties. The reason for this is simply because the Designer is actually using the same API that WCF uses in order to perform the certificate validation so you can use any of the values allowed in these settings according to WCF documentation. If you want to know more about this API and its usage you can read this post.  

 

Encrypted Model Properties: As I mentioned at the beginning, there are some properties in the model and extenders that may be secured by encrypting them with the X.509 Certificate set in the model property.Regarding the properties that are encrypted when the model file is persisted, we have: -      Model Properties:o    Biztalk Server Connection Stringo    Model Exporter (DB Exporter): Itinerary Database-      Static Resolver Extender:o    Endpoint Configuration Regarding the “Endpoint Configuration” property, there are some details to add. First you need to set the “Transport Name” property. After this when you open the Endpoint Configuration editor (…) will show up a dialog with all the properties included in the manifest file according to the Transport Name set. Let say that you set the “FTP” value, then the editor will show up the properties in the FTPPropertyManifest.xml file located in the Designer installation folder.  

<property name="Password" type="FTP.Password" description="The password for the  conection." encrypted="true" assembly="globalPropertySchemas" />

 

You will find in the following property element the “encrypted” attribute that marks this element for encryption. The same applies to any other element with this attribute set to “true”.

In case that there’s no Certificate set and the certificate registry value is set as “true”, you may not be able to set a sensitive property value because it will show up as disabled like in the following figure:

 

 

    

 

Once you have set the certificate or disabled the certificate usage as described in the above section, you may set these properties as expected.  

 

Exporting the model with encrypted values

When you export the model to an xml itinerary you will get the encrypted data like the properties marked for encryption in “Endpoint Configuration” resolver property or any other extender property (including custom extenders) with the attribute “EncryptPropertyAttribute” on the sensitive property like the sample below: 

 

[EncryptProperty(typeof(ItineraryModel))]

public string EndpointConfig { get; set; }

 

   

After exporting the model, you will get the exported data like in the “endpointConfig” attribute value below, all the XmlEncryption section “<EncriptedData>…” with a reference to the X.509 certificate used for encryption. 

Notice that you should install this same certificate on the server where the core ESB engine will process this itinerary in order to decrypt the sensitive information.

17 Comments

Comments have been disabled for this content.