Persits Software, Inc. Web Site
Main Menu:  Home |  News |  Manual |  Tasks |  Object Reference |  Crypto 101 |  FAQ |  Download & Buy |  Clients |  Live Demo |  Contact
 Navigator:  Home |  Tasks |  Use AspEncrypt as a Client-side ActiveX Control
Generate PKCS#7 Signatures and Envelopes Issue Certificates
  Use AspEncrypt as a Client-side ActiveX Control
Starting with Version 2.0, the AspEncrypt.dll file contains an ActiveX control component called XEncrypt which can be used on the client side inside Internet Explorer 4.0+. All the cryptographic operations offered by AspEncrypt can now take place on the user's machine and not just the web server. XEncrypt exposes the same properties and methods as CryptoManager with the exception of a few methods not applicable to client-side operations.

Most importantly, XEncrypt allows your Web-based application to perform operations involving the user's private key such as digital signing or data decryption without jeopardizing the security of the private key.

XEncrypt does not require a registration key, so you do not need to purchase a license for every client machine XEncrypt will be downloaded to. However, XEncrypt will only work under IE and not any other environment such as VB, etc. For containers other than IE, you must continue using the CryptoManager object which requires a registration key.

  Using XEncrypt under IE
The XEncrypt ActiveX control resides in the same DLL as the rest of the AspEncrypt objects, aspencrypt.dll. To use XEncrypt on the client side, your web page must reference it using the <OBJECT> tag, as follows:


The CLASSID attribute is the globally unique identifier (GUID) of the XEncrypt control.

The CODEBASE attribute points to a relative path of the file aspencrypt.dll on your server. For this code to work, you must place the file aspencrypt.dll in a virtual directory on your web server where the browser can find and download it from. Note that you do not need to register aspencrypt.dll in that location. Your web server may have the file aspencrypt.dll registered in, say, the system folder c:\winnt\system32, and another copy of that file placed in the same virtual directory as the HTML or ASP files that reference it.

The ID attribute is to be used by client-side VBScript to reference the XEncrypt control (see code samples below).

AspEncrypt is a digitally signed DLL, so when your users run this page for the first time, they will see a dialog box similar to this:

If the user says "Yes", the browser will download and register the file aspencrypt.dll on the user's machine. The AspEncrypt library is signed with Persits Software, Inc.'s digital ID. If you want your company's name to appear on this security dialog and not Persits Software, Inc., contact us and we will send you an unsigned copy of the DLL. You can then sign it using your own digital ID.

XEncrypt is an invisible control with no user interface. It can only be invoked by client-side script. The code sample http://localhost/aspencrypt/client_side/simple_client.asp demonstrates simple text encryption and decryption performed on the client side:



Sub Encrypt
  Set Context = XEncrypt.OpenContext("mycontainer", False)
  Set Key = Context.GenerateKeyFromPassword("my password")
  Set Blob = Key.EncryptText( document.myForm.txtEncr.Value )
  document.myForm.txtDecr.Value = Blob.Base64
End Sub

Sub Decrypt
  Set Context = XEncrypt.OpenContext("mycontainer", False)
  Set Key = Context.GenerateKeyFromPassword("my password")
  Set Blob = XEncrypt.CreateBlob
  Blob.Base64 = document.myForm.txtDecr.Value
  MsgBox Key.DecryptText(Blob)
End Sub

<FORM NAME="myForm">
<INPUT TYPE="TEXT" NAME="txtEncr" SIZE="60" VALUE="Text to encrypt">
<INPUT TYPE="BUTTON" OnClick="Encrypt" VALUE="Encrypt">
<INPUT TYPE="TEXT" NAME="txtDecr" SIZE="60">
<INPUT TYPE="BUTTON" OnClick="Decrypt" VALUE="Decrypt">


The VBScript code used in this sample is very similar to the ASP code we have seen in previous chapters except that here we do not explicitly create an instance of the CryptoManager object. Instead, we use the XEncrypt object. Another difference is that we pass False instead of True to the OpenContext method to instruct XEncrypt to use a key container in the HKEY_CURRENT_USER and not HKEY_LOCAL_MACHINE portion of the registry.

  Working with User Certificates

The main reason why XEncrypt was introduced is to provide easy and safe access to the user's private keys residing on the client machine. XEncrypt enables the user to generate digital signatures and decrypt data with her private key using the IE browser. The private key never has to leave the user's machine, so its security is not jeopardized.

The best way to work with private keys is to obtain a digital certificate (digital ID). Every time you enroll for a certificate, a key pair (comprised of a public and private keys) is created on your local machine. The public key wrapped in a "certificate request file" is sent to a certification authority (CA) which issues the certificate and sends it back to you. Finally, the newly issued certificate is installed on your machine pointing to its original private key.

For testing purposes, you can obtain an instant free certificate from the Persits Software demo "certification authority" at For a production environment, you should obtain a certificate from one of the real certification authorities such as Thawte or Verisign. Note that you cannot use server SSL certificates for client-side signing or data decryption.

Once a certificate has been obtained, you can start using its private key to perform digital signing or data decryption. The code sample http://localhost/aspencrypt/client_side/sign.asp demonstrates how you can use XEncrypt to compute a digital signature on a text string using your certificate's private key.


Sub Sign
' Open "MY" certificate store which contains client certs
  Set Store = XEncrypt.OpenStore("MY", False )

  ' Does the store contain certificates?
  Count = Store.Certificates.Count
  If Count = 0 Then
    MsgBox "You have no certificates."
    Exit Sub
  End If

  ' If store contains more than one, enable user to pick one
  If Count > 1 Then
    Set Cert = XEncrypt.PickCertificate(Store, 4+8+16,_
        "Select Certificate Please",_
        "Select the one you want to be used for signing")
    If Cert Is Nothing Then Exit Sub
' otherwise just pick that only one cert
    Set Cert = Store.Certificates(1)
  End If

  ' Make sure the cert has a private key associated with it
  If Cert.PrivateKeyExists = False Then
    MsgBox "This certificate has no private key associated with it."
    Exit Sub
  End If

  ' obtain private key context for this cert
  Set Context = Cert.PrivateKeyContext

  ' create empty hash object associated with this context
  Set Hash = Context.CreateHash
  Hash.AddText document.frmSign.txtToSign.value

  Set Blob = Hash.Sign(Context.KeySpec)
  document.frmSign.txtSignature.value = Blob.Base64
End Sub


<FORM NAME="frmSign" ACTION="verify.asp">
Text to sign:<BR>
<TEXTAREA NAME="txtToSign" COLS="80" ROWS="3">Hello World!</TEXTAREA><BR>
<INPUT TYPE="BUTTON" OnClick="Sign" VALUE="Sign">
<TEXTAREA NAME="txtSignature" COLS="80" ROWS="3"></TEXTAREA>
<INPUT TYPE="SUBMIT" VALUE="Submit for verification">

This code snipped uses the previously unseen method PickCertificate exposed by XEncrypt. This method uses the undocumented CryptoAPI method CryptUIDlgSelectCertificateW which displays a list of certificates from a given certificate store. In our case we use the "MY" store opened by a call to CM.OpenStore.

PickCertificate's second argument is a combination of flags that hide certain columns in the certificate list. In our case we hide all columns except "Issued To", "Issued By" and "Expiration Date." The third and fourth arguments are optional. They specify captions displayed by the title and body of the certificate list dialog.

The PickCertificate method returns a CryptoCert object for the user-selected certificate. Our code snippet then uses this certificate's private key context to create a CryptoHash object, add user-specified text to it and create a digital signature via the Sign method. Note that we pass Context.KeySpec (which can be True or False) to the Sign method to ensure we are using the correct key pair from this certificate's key container.

The file sign.asp invokes the script verify.asp which verifies the signature against a certificate's public key. For this script to work, you must export your signer certificate to a .cer file. To do that, bring up the certificate list, double-click on the certificate you want to export, open the Details tab and click the button "Copy to file." When asked whether you want to export the private key, say "No." Place the resultant .cer file on the web server for the script verify.asp to use. Below is the signature verification code:

' Verify digital signature using certificate's public key
Set CM = Server.CreateObject("Persits.CryptoManager")

Set Context = CM.OpenContext("mycontainer", True)
Set Hash = Context.CreateHash

' add the same text to hash
Hash.AddText Request("txtToSign")

' obtain certificate we will use for verification
Set Cert = CM.ImportCertFromFile("d:\mycert.cer")
Set Key = Context.ImportKeyFromCert( Cert )

' Put signature to be verified in a Blob object
Set Blob = CM.CreateBlob
Blob.Base64 = Request("txtSignature")

Verified = Hash.VerifySignature(Blob, Key)
If Verified Then
  Response.Write "Signature is verified."
  Response.Write "Signature is NOT verified."
End If

Issue Certificates Generate PKCS#7 Signatures and Envelopes

Search this Site
  This site is owned and maintained by Persits Software, Inc. Copyright © 2000 - 2010. All Rights Reserved.