Discuss this help topic in SecureBlackbox Forum

DC add-on: Embed ActiveX control to web page

ActiveX controls are supported in the Internet Explorer browser only. With the ActiveX control, the user is able to use Windows system certificate storage, cryptographic tokens, and smart cards (if they provide PKCS#11 drivers), and X.509 certificates stored in CER, PEM and PFX (P12) files to sign data, located on the server, and return the signature back to the server.

Embedding the control

The control can be embedded into a HTML page using the following HTML 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="AllowFileStorage" value="yes" />
    <param name="AllowWindowsStorage" value="no" />
    <param name="AllowTokenStorage" value="yes" />
    <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" />
</object>

Mandatory parameters

Data- this parameter contains a signature request. This request is produced by TElDCAsyncState or TElDCAsyncStateCollection classes (as an XML document) and must be Base64-encoded before embedding into the web page. There are two parameters available to return signed data back to the server:

  • The DataURL parameter specifies the URL where the signed data to be posted to.
  • The GoURL parameter specifies the URL where the browser has to be navigated to after the data is posted.
If no DataURL parameter is provided, the signed data is returned using the query part of the URL from the GoURL parameter (see below).

Additionally one of the below parameters must be included:

  • DataURL - this parameter provides an absolute or a relative URL to be used to post the signed data back to the server. The signed data is posted back to the server using TElHTTPSClient component, so no cookies or other things from the browser will be available in that HTTP request. The only way to identify the original session or document on the server is to use the SessionID parameter. The value of this parameter (if it is provided in the web page source) is included without any change to the query part of the URL. If there are other parameters available in the DataURL value, they are not affected in any way and the SessionID parameter will be added to the end of the existing query part. The Content-Type field of the POST request is set to application/xml.
    POST /<path from DataURL>?sessionid=unique-text HTTP/1.1
    Host: <host name from DataURL>
    Content-Type: application/xml
    ...
    
    The ActiveX control expects status code 200 to be returned from the server. All other status codes are reported to the user as an error.
  • GoURL - this parameter provides an absolute or a relative URL to be used to navigate the browser to after the data is signed. If no DataURL parameter is included in the web page, the signed data is returned as a query parameter named data. In this case, the signed data is Base64-encoded.
    The value of the SessionID parameter is used in the same way, as described for the DataURL parameter. If there are other parameters available in the DataURL value, they are not affected in any way and the sessionid parameter will be added to the end of the existing query part.

Optional parameters

  • SessionID - this parameter should contain a text string which helps to determine the signing session or the pre-signed document on the server where the control returns the signed data back to the server. The value of this parameter is not changed and just added to the query part of the URL(s) provided by the DataURL and GoURL parameters.
  • AllowFileStorage - the parameter specifies if the user is allowed to use certificates loaded from files. Possible values are true or yes to allow the user to load certificates from files, and false or no to disable this. If the parameter is not specified, the user is allowed to use certificates from files.
  • AllowWindowsStorage - the parameter specifies if the user is allowed to use certificates from the Windows system certificate storage. Possible values are true or yes to allow the user to use certificates from the Windows certificate storage, and false or no to disable this. If the parameter is not specified, the user is allowed to use certificate from the Windows certificate storage.
  • AllowTokenStorage - the parameter specifies if the user is allowed to use keys from security tokens and smart cards. Possible values are true or yes to allow the user to use keys from security tokens and smart card, and false or no to disable this. If the parameter is not specified, the user is allowed to use security tokens and smart cards.
    If usage of security tokens and smart cards is allowed, either PKCS11Registry parameter or PKCS11Libraries parameter must be included in the web page (see this how-to topic for details).
  • Color - the parameter specifies the background color of the control in HTML style: #RRGGBB. If the parameter is not specified the control will be of WHITE color.
  • How To articles about Distributed Cryptography add-on.

    Discuss this help topic in SecureBlackbox Forum