Discuss this help topic in SecureBlackbox Forum

DC add-on: Use security tokens and smart cards in ActiveX control

The ActiveX control is able to load certificates from security tokens and smart cards using PKCS#11 libraries. It's needed to let the control know, which libraries it has to load. There are two ways to do this: using PKCS11Libraries parameter and using PKCS11Registry parameter. At least one of them must be specified, if AllowTokenStorage parameter allows the user to use security tokens and smart cards.

Using a list of known PKCS#11 libraries

This way is used if the client computer cannot be configured by adding some values to its Windows Registry. The PKCS11Libraries parameter allows to let the ActiveX control which PKCS#11 libraries have to be used.

The list is provided in the following format:

[alias1=]dllname1[;[alias2=]dllname2...]
The ActiveX control does a search for each of the specified libraries in all the folders specified in the %PATH% environment variable on the client computer. All found libraries are listed in the combo box and the user on the client computer can select one of them to be used to sign the data. If an optional alias is specified, the user will see this the alias instead of the DLL name.
	<object ...>
	    ...
	    <param name="AllowTokenStorage" value="yes" />
	    <param name="PKCS11Libraries" value="Aladdin eToken=etpkcs11.dll;Eutron.dll" />
	    ...
	</object>

The example above shows two items in the combo box (of course, if both DLLs are found on the client computer) to the user: the first one is “Aladdin eToken” and the second one is “Eutron.dll”.

When the user selects a token in the combo box and clicks the “Next” button, the control attempts to load the library. If it succeeded, it checks how many slots does the library support. If there are several slots available, the control uses the first non-empty slot.

Using a list of known PKCS#11 libraries

This way is used if it's possible to add new values to the Windows Registry on the client computer. In this case, the PKCS11Registry parameter is used to refer to the registry key with referenced libraries.

For each library, which the user is allowed to use with the ActiveX control, a reference of the following structure has to be created:

{key name specified in PKCS11Registry parameter}
    [key] {any name}
        [string value] Name = {unique readable text}
        [string value] Library = {path name of a PKCS#11 library}
        [string value] SlotID = {text}
        [dword value] SlotIndex = {index}
    [key] {other name}
    etc.

The ActiveX control first checks HKLM key of the Registry and loads the referenced PKCS#11 libraries from there. Then, the ActiveX control checks HKCU key and loads libraries from there. If HKCU part contains a library with the same name (readable text specified in the Name string value) as already loaded from the HKLM key, such reference will be overwritten with the info loaded from HKCU key.

An example of a REG file which creates such PKCS#11 registry is shown below.

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\My Company]
[HKEY_CURRENT_USER\Software\My Company\My Product]
[HKEY_CURRENT_USER\Software\My Company\My Product\DC PKCS11]
[HKEY_CURRENT_USER\Software\My Company\My Product\DC PKCS11\1]
"Name"="Aladdin eToken"
"Library"="C:\\Windows\\System32\\eTPKCS11.dll"
[HKEY_CURRENT_USER\Software\My Company\My Product\DC PKCS11\2]
"Name"="Eutron"
"Library"="C:\\Program Files\\Eutron\\eutron.dll"

Then, this registry can be referenced from web pages as follows:

<object ...>
    ...
    <param name="AllowTokenStorage" value="yes" />
    <param name="PKCS11Registry"
           value="\Software\My Company\My Product\DC PKCS11" />
    ...
</object>

How To articles about Distributed Cryptography add-on.

Discuss this help topic in SecureBlackbox Forum