EldoS | Feel safer!

Software components for data protection, secure storage and transfer

Making BizCrypto use system certificates

BizCrypto 7 introduces support for certificates stored in Windows system stores and on miscellaneous cryptographic devices. The article explains the details of component configuration in this respect, and, we hope, will help you set up your component (adapter, pipeline, task or activity) for using such certificates with ease.

The article describes use of certificates stored in Windows system stores; however, certificates stored on PKCS #11-compliant cryptographic devices are accessed in a very similar way. That's why we recommend reading this article in the latter case too.

There are several advantages in storing certificates in system certificate stores:

  1. Safety. The corresponding private key is stored in secure storage, protected by the operating system. There's even an option of making private key non-exportable at all, which means that the value of the key will never be seen by anyone except the cryptographic kernel of the system.

  2. Ease of use and administration. All the certificates are stored in a number of either system-wide or user-specific certificate stores, each one having a specific purpose (personal certificates, trusted root certificates, certificates of other people). The contents of the stores can be viewed and edited with user-friendly interface of Microsoft Management Console.

  3. Flexibility. The cryptographic kernel of Windows is extensible. A lot of vendors of cryptographic devices offer custom extensions to the default cryptographic functionality that allow using certificates stored on the devices as if they were stored in the native system stores (as computer gurus say, the certificates are transparently mapped to the system stores).

So, let's start. Imagine that we have to download files from our business partner's server, one file per day. The server of our partner is an FTP-over-SSL (FTPS) server that is set up to require a secure connection with client authentication, as our partner, obviously, does not want the file to be downloaded by a competitor. The partner has provided us the following information that should be used to access the server:

  1. Credentials (username, password, server address),

  2. Server certificate (without the private key), usually as a single .cer or .crt file. Let's refer to it as "server.cer".

  3. Client certificate with the corresponding private key, usually as a single password-encrypted .pfx file. Let's refer to it as "client.pfx".

First, let's put the certificates to the system certificate stores. Run Microsoft Management Console (Start button -> Run... -> type "mmc" and click "OK"). In MMC window, go to File->Add/Remove snap-in menu, click the "Add..." button on the dialog that appeared. Choose the "Certificates" item in the "Add Standalone Snap-in" list and click "Add".

Choose the "Computer account" and click "Next", then choose "Local computer" and click the "Finish" button. Close the "Add Standalone Snap-in" dialog and click "OK" on the "Add/Remove snap-in" one. Now the "Certificates (Local computer)" snap-in has been added to the Console Root.

Picture 1. Adding the "Certificates" snap-in.

Expand the "Certificates" node. You will see a number of system store items. The following stores are usually present in all versions of Windows: Personal, Trusted Root Certification Authorities and Intermediate Certification Authorities. Personal store is intended for storing certificates of computer users, i.e. your certificates or certificates of your applications. Trusted Root Certification Authorities store contains the certificates of trusted CA's, such as Thawte or Verisign. There are several dozens of trusted certificates in this store already, which have been put there by Microsoft.

As you probably already understood, we should put the certificate contained in the client.pfx file to the Personal store, and the certificate contained in the "server.cer" to the Trusted Root Certification Authorities store. There can be certain exceptions (for instance, if the server maintains not a single certificate but a dynamic certificate chain), but in most cases this would be enough.

To add certificate to a store, expand its node and right-click on the inner "Certificates" node. Choose "All tasks" -> "Import" in the pop-up menu and follow the instructions of the Wizard.

Picture 2. Importing certificate to a Trusted Root Certification Authorities store.

Once the certificates are imported, let's set up SecureBlackbox to use them. All the further information concerns SecureBlackbox FTPS adapter for BizTalk, however, setting up FTPS connection in SQL Server Integration Services or FTPS Activity in Sharepoint Server is performed in exactly same way.

Run BizTalk Administration Console and expand the node of the needed receive location (I suppose, you've already created one? ;) ). Select BizCrypto FTPS adapter from the list and open adapter configuration dialog.

Remark. In BizCrypto adapters for BizTalk, there are three properties reserved for each certificate or key. For instance, there are Certificate path, Certificate and Certificate source properties that allow specifying a client certificate for SSL connection. How to use them?

Certificate path property accepts a path to certificate. If you need to use certificate stored in a file on disk, just use this property and leave the other two empty.

Certificate and Certificate Source allow specifying certificates stored in a different location. Certificate source specifies the type of information that is assigned to the Certificate property. The following types are supported: File, Value, System and PKCS11.

Certificates stored in system certificate stores correspond to the System certificate source. Certificates contained on cryptographic tokens correspond to the PKCS11 source type. However, token-based certificates mapped to a system store by a custom vendor's extension (also known as cryptographic services provider, or CSP) should be referred to as System source.

P.S. Yes, the certificate contained in a file can be specified in two different ways, through Certificate pathproperty or via Certificate and Certificate source pair with Certificate sourceset to Fileand Certificateset to the actual file path.

First, let's set up the certificate of the server. As it is contained in a system certificate store, setting Trusted Certificates Source property to System. Now we have to specify the exact location of the certificate in the system via the Trusted Certificates property (as there is a number of different system stores, we have to specify the exact one that should be used for validation). So, assigning the following value to the Trusted Certificates: store="ROOT". This line tells the adapter that it should use the Trusted Root Certification Authorities store to search for the certificate provided by the server for validation.

Remark. "ROOT" is a real name that corresponds to a user-friendly name "Trusted Root Certification Authorities" (which is artificial and differs for different localizations of the operating system). The same can be said for Personal (whose real name is "MY") and Intermediate Certification Authorities ("CA") stores.

Second, let's set up a certificate for client authentication. Similarly, setting Certificate Source to System. However, if it was enough for us to specify the entire store in the above case, now we have to specify the exact certificate contained in the Personal store. Why? Because the store might contain other certificates (of other adapters or applications), and our adapter has to find the right certificate to satisfy the FTPS server. That's why the value of Certificate property would be slightly more complex: store="MY", subject="/O=Big Company, Inc/CN=FTPS Adapter". Besides specifying the store, we narrowed down the criteria by specifying some fields of certificate subject value. Certificate details can be obtained using Windows certificate viewer.

Picture 3. Viewing certificate properties.

That's all. Now you can start your BizTalk application and check if the download works correctly.

Specifying certificates using BizCrypto Certificate Template Language

BizCrypto provides a powerful mechanism for specifying certificates contained in alternative storages, such as system certificate stores or cryptographic devices. This chapter gives some guidelines on using SecureBlackbox Certificate Template Language, an easy-to-use way for identifying a particular certificate among others contained in the same storage.

SCTL is similar to file masks, though slightly more complex (but not as complex as regular expressions ;) ). SCTL expression consists of a set of criteria, each one specifying a particular set of certificates. Obviously, the more details are specified in a criterion, the less certificates satisfy it.

A typical SCTL expression has the following look:

issuer="/CN=Administrator", subject="/CN=Myself", serial="00FFA0" single-criterion expression, satisfied by all certificates whose issuer's common name is "Administrator", subject's common name is "Myself" and serial number is 0x00FFA0.

(issuer="/CN=Administrator 1")(issuer="/CN=Administrator 2") double-criterion expression, satisfied by all certificates whose issuer's common name is "Administrator 1" or "Administrator 2".

Sure, you got the idea. Each criterion is enveloped with parentheses. For a single-criterion expressions the parentheses can be omitted.

The following table contains properties that can be specified within a single criterion for any certificate storage type:

issuer

Specifies a subset of fields of certificate issuer in widely used DN (distinguished name) format. DN expression consists of Name=Value pairs, separated by the '/' character.

Example:

issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"

subject

The same, but for the certificate subject.

Example:

subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"

serial

Certificate serial number in base16 format.

Example:

serial="00FFA0"

fingerprint

SHA1 fingerprint of the certificate in base16 format.

Example:

fingerprint="00112233445566778899AABBCCDDEEFF00112233"

keyid

The value of the subject key identifier extension of the certificate in base16 format.

Example:

keyid="112233445566"

Depending on a type of the storage, additional properties can be published. The following table shows the properties, specific to Windows system certificate stores.

store

The real (not user-friendly!) name of the system store. Default value: "MY".

Example:

store="ROOT"

accesstype

System store location. Windows maintains several instances of the stores with the same names for different purposes. For instance, there are several "Personal" stores, a system-wide one, and an individual one for each user account.

Possible values: "CurrentService", "CurrentUser", "CurrentUserGroupPolicy", "LocalMachine", "LocalMachineEnterprise", "LocalMachineGroupPolicy", "Services", "Users". Default value: "LocalMachine".

Example:

AccessType="CurrentUser"

provider

The name of cryptographic provider to use. In most cases you do not need to set this property. Possible values: "Default", "BaseDSSDH", "BaseDSS", "Base", "RSASchannel", "RSASignature", "EnhancedDSSDH", "EnhancedRSAAES", "Enhanced", "BaseSmartCard", "Strong". Default value: "Default".

Example:

Provider="Enhanced"

And, finally, the properties specific for PKCS11-compliant cryptographic devices.

dllpath

Path to PKCS11 driver DLL. An obligatory property.

Example:

DllPath="C:\Program Files\Token\cp11.dll"

slot

Slot number. If not specified, the first slot with the inserted token is considered.

Example:

Slot="5"

pin

Token PIN.

Example:

Pin="12345"

Example 1.

(store="MY", subject="/CN=Administrator/C=US", serial="012345")(store="MY" serial="22")

Specifies all the certificates from the Personal store, whose subject includes "Administrator" as a common name and "US" as a country and whose serial number is "012345", plus all the certificates from the Personal store whose serial number is "22". As AccessType property is omitted, all the certificates are taken from the local machine instance of the Personal store.

Example 2.

(store="MY")

Specifies all the certificates from the local machine instance of the Personal store.

Example 3.

(store="MY")(store="ROOT")

Specifies all the certificates from the local machine instances of the Personal and Trusted Root Certification Authorities stores.

Example 4.

dllpath="C:\Windows\System32\cp11_1.dll", pin="test", subject="/CN=John Johnson"

Specifies all the certificates with the "John Johnson" subject common name stored on the cryptographic token whose driver is located under the above path. The "test" word is used as a PIN to log in to the token.

Return to the list

|

Back to top

As of July 15, 2016 EldoS Corporation will operate as a division of /n software inc. For more information, please read the announcement.

Got it!