ActiveX Control for Distributed Cryptography

Distributed Cryptography ActiveX control

The Distributed Cryptography (DC) ActiveX control can be used to sign data remotely. The user can use Windows system certificate storage, cryptographic tokens and smart cards which provide PKCS#11 drivers, and X.509 certificates stored in .CER, .PEM and .PFX (.P12) files.

The control can be embedded into a HTML page using the following code:


<object classid="clsid:208CE54E-F15E-4DCB-823A-9DA0DFD1B2E1"
        codebase="SBDCSigner.ocx#version=1,1,0,0" width=500 height=240>
<param name="Data" value="base64-encoded xml request" />
<param name="SessionID" value="unique text" />
<param name="Color" value="#FFFFFF" />
<param name="DataURL" value="absolute or relative url" />
<param name="GoURL" value="absolute or relative url" />
<param name="PKCS11Registry" value="absolute path in windows registry w/o HKLM or HKCU marks" />
<param name="Token" value="token name" />
<param name="PKCS11Libraries" value="list of DLLs" />

The control supports the following parameters.

SessionID - A string that will be added when posting the signed data back to the server and navigating the browser after the data is signed. If DataURL parameter is specified the signed data is transferred to the server from within the control, the browser is not used for this purpose. And this value is the only way to determine the corresponding signing session on the server.
Data - Base64-encoded XML document produced by ElDCAsyncState class.
DataURL (optional) - a URL that will be used to POST the resulting signature to; the resulting data is in the form of XML and is posted with application/xml Content-Type field set. Query part of the URL is allowed, SessionID parameter will be added automatically. If DataURL parameter is not specified the resulting signature is sent using the query part of the GET request to the URL specified in the GoURL parameter. Both absolute and relative URLs are supported.
GoURL (optional) - a URL that will be used to navigate the browser and (if DataURL is not specified) return the resulting data. Query part of the URL is allowed, SessionID parameter will be added automatically. If DataURL parameter is not specified, the resulting signature will be added to the query as Data parameter using base64 encoding. If GoURL parameter is not specified, the browser will remain on the page which contains the control. Both absolute and relative URLs are supported.
AllowFileStorage (optional) - specifies if the user is allowed to use keys loaded from files. Possible values are: "true" or "yes" to allow the user to load keys from files, and "false" or "no" to disable this. If the parameter is not specified, the default value is "yes".
AllowWindowsStorage (optional) - specifies if the user is allowed to use keys from the Windows system certificate storage. Possible values are: "true" or "yes" to allow the user to use keys from Windows certificate storage, and "false" or "no" to disable this. If the parameter is not specified, the default value is "yes".
AllowTokenStorage (optional) - specifies if the user is allowed to use keys from security tokens and/or smart cards. Possible values are: "true" or "yes" to allow the user to use keys from security tokens and/or smart card, and "false" or "no" to disable this. If the parameter is not specified, the default value is "yes".

PKCS11Registry (optional) - sbsolute registry key name on client computers where PKCS#11 libraries are referenced. For each library which the user is allowed to use with this ActiveX control, a reference of the following structure should be created:


<key name specified in PKCS11Registry parameter>
     |
     +- [key] <any name>
     |       |
     |       +- [string value] Name = <unique readable text>
     |       |
     |       +- [string value] Library = <dll path name of pkcs#11 driver>
     |       |
     |       +- [string value] SlotID = <text>
     |       |
     |       +- [dword value] SlotIndex = <index>
     |
     +- [key] <any other name>

The ActiveX control first checks registry in HKLM key and loads the referenced PKCS#11 providers from there. Than the ActiveX control checks registry in HKCU key and loads providers from there. If HKCU part contains a provider with the same name (readable text specified in the Name string value) as already loaded from HKLM key, such reference will be overwritten with info loaded from HKCU key.
Example of .reg file which creates such a 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"="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"
-----------------------------------------------------------------------------------

Token (optional) - name reference in the pkcs#11 registry (see PKCS#11Registry) that must be used to sign the data. If this parameter is not specified, the user will be prompted to select a token from the list of registered tokens. If the parameter is specified but there is no token registered with this name, the user will not be able to use crypto tokens and smart cards at all.
PKCS11Libraries (optional) - lists names of all known PKCS#11 drivers to search for on the client computer. The list must be in the following form: [name1=]dllname1[;[name2=dllname2]...].
For example:
```
eToken=etpkcs11.dll;eutron.dll
```
The ActiveX control does a search for each of the specified libraries in all folders on the client computer which are specified in its %PATH% environment variable. All found libraries are listed in a combo box and the user on the client computer can select one of them to be used to sign the data. If an optional nameX is specified, the user will see this name for corresponding dll instead of dll name.
Color (optional) - background color of the applet in HTML style: #RRGGBB. If the parameter is not specified the control will be of WHITE color.

Important!

At least DataURL or GoURL MUST be specified.
At least PKCS11Registry or PKCS11Libraries MUST be specified.

Discuss this help topic in SecureBlackbox Forum