 |
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.
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:
<OBJECT
CLASSID="CLSID:F9463571-87CB-4A90-A1AC-2284B7F5AF4E"
CODEBASE="aspencrypt.dll"
ID="XEncrypt">
</OBJECT>
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:
<HTML>
<HEAD>
<OBJECT
classid="CLSID:F9463571-87CB-4A90-A1AC-2284B7F5AF4E"
codeBase="aspencrypt.dll"
id="XEncrypt">
</OBJECT>
<SCRIPT LANGUAGE="VBSCRIPT">
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
</SCRIPT>
</HEAD>
<BODY>
<FORM NAME="myForm">
<INPUT TYPE="TEXT" NAME="txtEncr" SIZE="60" VALUE="Text to encrypt">
<INPUT TYPE="BUTTON" OnClick="Encrypt" VALUE="Encrypt">
<P>
<INPUT TYPE="TEXT" NAME="txtDecr" SIZE="60">
<INPUT TYPE="BUTTON" OnClick="Decrypt" VALUE="Decrypt">
</FORM>
</BODY>
</HTML>
|
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.
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 http://www.persits.net/encrypt/demo_cert.asp.
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.
...
<SCRIPT LANGUAGE="VBSCRIPT">
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
Else
' 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
</SCRIPT>
</HEAD>
<BODY>
<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">
<P>
<TEXTAREA NAME="txtSignature" COLS="80" ROWS="3"></TEXTAREA>
<P>
<INPUT TYPE="SUBMIT" VALUE="Submit for verification">
</FORM>
...
|
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."
Else
Response.Write "Signature is NOT verified."
End If
%>
|
|
|
|
|
|
