How to encrypt sections within BtsNtsvc.exe.config file?

|  Posted: August 13, 2008  |  Categories: General Technical

It’s one of the common requirements in some of the projects I’ve worked on to put some kind of configuration information in the BizTalk config file, things like appSettings, connectionString etc. Majority of the time it will be ok to leave the value in plain text inside the xml based config file (for example by using integrated authentication connection string instead of providing username/password), and designing in the way so that you don’t put sensitive information inside the config file.

But, there will be times you need to put some sensitive data inside and you can’t get past the security team review. In this article I’ll explain how you can easily encrypt the sections of the config file using the utilities provided in .NET 2.0. There is absolutely no extra coding required inside your application to decrypt the data.

We are going to utilize the aspnet_regiis utility for this purpose, don’t get scared with the keyword “ASP” here, even though its designed for asp .net 2.0 web.config files, its perfectly valid to use it for our BtsNtSvc.exe.config file (since all the configuration files in .NET are derived from same schema). Other important thing to note here is, aspnet_regiis utility is installed as part of .NET Framework 2.0 installation and it should be available in all our your production BizTalk 2006 (and above) servers.

.NET 2.0 comes by default with two providers; you can also implement your own custom providers.
RSAProtectedConfigurationProvider: This is the default provider and uses the RSA public key encryption to encrypt and decrypt data.
DPAPIProtectedConfigurationProvider: This provider uses the Windows Data Protection API (DPAPI) to encrypt and decrypt data.

Note: aspnet_regiis tool is installed under C:WINDOWSMicrosoft.NETFrameworkv2.0.50727

Here are the steps you need to perform

1. Rename BtsNtSvc.exe.config to web.config

aspnet_regiis tool is capable of working with only web.config files. So, take a copy of your BtsNtSvc.exe.config file and rename it to web.config file.

2. Identify the section to be encrypted

Encrypting and decrypting data incurs performance overhead. To keep this overhead to a minimum, encrypt only the sections of your configuration file that store sensitive data. Normally on a BizTalk solution encrypting appSettings and ConnectionString sections will be sufficient for majority of the solutions.

3. Create a custom RSA Key Container

The RSAProtectedConfigurationProvider supports machine-level and user-level key containers for key storage. Machine-level key containers are available to all users, but a user-level key container is available to that user only.

But to use it on a BizTalk configuration file on a multi-server environment, we must create a custom RSA encryption key container (can’t use the default machine or user level key containers) and deploy the same key container on all the BizTalk servers.

You can create a custom RSA key container by giving the following command

aspnet_regiis -pc "CustomKeys" -exp

NOTE: “CustomKeys” is the name of custom key container; -exp options allow the private key to be exportable.

The command should give the following output

Creating RSA Key container...Succeeded!

4. Add and configure the configProtectedData in the BtsNtSvc.exe.conf file

To do this, add the following <configProtectedData> section to the web.config file (renamed BtsNtSvc.exe.config file from step 1). Note that the key container name is set to CustomKeys, which is the name of the key container created previously in step #3.

        <add keyContainerName="CustomKeys"
             description="Uses RsaCryptoServiceProvider to encrypt and decrypt"
             type="System.Configuration.RsaProtectedConfigurationProvider,System.Configuration, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />

You can paste this section on the very first line after <configuration>

5. Encrypt the section in the configuration file

The following example shows encrypting the appSettings section.

aspnet_regiis.exe -pef “appSettings” C:@BlogEncryptingConfigSections -prov “CustomProvider”

-pef: To tell we are working on file system, normally the tool will look for virtual directory
-prov “CustomProvider”: configProtectedData section name we configured inside the configuration file in step #4.

Before encryption:

before encryption

After encryption:

after encryption

6. Copy the configuration file to BizTalk installation location

Rename the web.config file back to BtsNtSvc.exe.config and copy it to the BizTalk installation folder (Normally C:Program FilesMicrosoft BizTalk Server 2006).

NOTE: Restart the host instances.

7. Accessing the value inside code

Now you can make use of the values inside your code (Orchestration, Pipeline Component etc) in a way, how you will do it normally.

Add Reference to System.Configuration

System.Configuration.ConfigurationManager class automatically decrypts configuration sections when processing them; therefore, you do not need to write any additional decryption code. Example: to access the above appSettings inside your orchestration or custom .net component you’ll use the following code

endPoint = System.Configuration.ConfigurationManager.AppSettings["ABC_CORP_ENDPOINT"];

The above steps will be sufficient to work on a single BizTalk server. But its very likely your production setup will have more than one BizTalk Servers. In order to make this work in a multi server environment, follow the steps below.

Assuming the application is already deployed in the server and the same encrypted config file is copied to the BizTalk installation folder.

1. Export the custom RSA key

We need the custom RSA key (Created in Step #3 earlier) to be deployed into other BizTalk servers before they can utilize the config file. Execute the following command to export the key (in the source system).

aspnet_regiis -px "CustomKeys" "C:@BlogEncryptingConfigSectionsCustomKeys.xml" –pri

NOTE: -pri switch cause both the private and public key to be exported.

The command should give the following output:

Exporting RSA Keys to file...Succeeded!

2. Deploy the key in the destination server

Copy the CustomKeys.xml created in the previous step to the destination server and run the following command.

aspnet_regiis -pi "CustomKeys" "C:CustomKeys.xml"

NOTE: Its very import to take care of the exported key file (CustomKeys.xml). Make sure you don’t leave unnecessary copies lying around.

The command should give the following output

Importing RSA Keys from file..Succeeded!

NOTE: Restart the host instances.

Once the above steps are completed then your application should be able to access the appSettings without any issue. If the above steps are not performed in a multi-server deployment, you’ll receive the following error while trying to access the appSettings value.

Exception thrown from: segment 1, progress 7Inner exception: Failed to decrypt using provider 'CustomProvider'. Error message from the provider: The RSA key container could not be opened. (C:Program FilesMicrosoft BizTalk Server 2006BTSNTSvc.exe.Config line 39)

Finally, Grant access to BizTalk Service Account
Normally you would have performed all the above command executions using the logged in user account. But the BizTalk services will be running under a service account. It’s necessary to give sufficient rights to service account to read the RSA key container. In order to do that issue the following command

aspnet_regiis –pa “CustomKeys” “domainSvcAccountName”

The command should give the following output

Adding ACL for access to the RSA Key container...Succeeded!


Author: Saravana Kumar

Saravana Kumar is the Founder and CTO of BizTalk360, an enterprise software that acts as an all-in-one solution for better administration, operation, support and monitoring of Microsoft BizTalk Server environments.

  • Nice article, might be worth noting that the DPAPI provider is probably one to be careful with because your hosts may run as different user accounts but would all share the same biztalk config file and therefore would not be able to use the approach if you used DPAPI rather than the RSA provider.

  • I don’t think I have tested it with DPAPI. but it’s good to know mate.

One Platform Operations, Monitoring and Analytics Software

microsoft biztalk

Learn more

Over 500 customers across 30+ countries depend on BizTalk360


Azure service bus

Learn more

Start managing your Azure Service Bus namespaces in minutes

One Platform - Operations, Monitoring and Analytics Software

microsoft biztalk

Learn more

Over 500 customers across 30+ countries depend on BizTalk360

One Platform - Operations, Monitoring and Analytics Software

Azure service bus

Learn more

Start managing your Azure Service Bus namespaces in minutes

Back to Top