AspEncrypt provides symmetric encryption functionality via the CryptoKey object. CryptoKey's core methods, EncryptFile, DecryptFile, EncryptText and DecryptText, allow you to implement file and text encryption in your application in just a few lines of code.

An instance of the CryptoKey object is created using CryptoContext's methods GenerateKey and GenerateKeyFromPassword. The former generates a random key, while the latter generates a key based on a text password. A key generated by the GenerateKey method must be serialized to a file or other permanent storage in order to be used for decryption later. A password-derived key does not have to be serialized as it can always be re-created using the same password and CSP.

Both GenerateKey and GenerateKeyFromPassword methods accept optional arguments KeyAlgorithm and BitSize. By default, the encryption algorithm is RC2, and the key bit size depends on the algorithm and the default CSP. For example, if the default CSP is the Microsoft Base Provider and the encryption algorithm is RC4 the default key bit size is 40. If the default CSP is the Microsoft Enhanced Provider, the key bit size is 128 for the encryption algorithms RC2 or RC4. You can specify the key size to be from 40 to 128 bits in 8-bit increments. If the encryption algorithm is DES, Triple DES or Triple DES with two keys, the key size is fixed and equals 56, 168 and 112, respectively. You cannot change the key size for the DES familiy of algorithms.

The GenerateKeyFromPassword method also accepts the required Password argument and optional HashAlgorithm argument. The latter is SHA by default. The password on which a key is based can be as long as you want.

The following VB code snippet encrypts a given file with the RC4 algorithm using a 40-bit password-derived key:

Dim CM As CryptoManager Dim Context As ICryptoContext Set CM = New CryptoManager Set Context = CM.OpenContext("mycontainer", False) Set key = Context.GenerateKeyFromPassword("my password", calgSHA, calgRC4, 40) key.EncryptFile "d:\myfile.txt", "d:\myfile.txt.xxx"

The corresponding decryption code is identical except for the last line:

... key.DecryptFile "d:\myfile.txt.xxx", "d:\myfile.txt"

Notice the use of constants calgSHA and calgRC4. These constants are defined in the AspEncrypt type library and become available to your VB project when AspEncrypt is included in the list of project references. To use the AspEncrypt-defined constants in an ASP environment, you must use the construct METADATA TYPE="TypeLib" in your pages to make the AspEncrypt type library available to ASP, as follows:

<!--METADATA TYPE="TypeLib" UUID="{B72DF063-28A4-11D3-BF19-009027438003}"--> <% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("mycontainer", True) Set key = Context.GenerateKeyFromPassword("my password", calgSHA, calgRC4, 40) key.EncryptFile "d:\somefile.txt", "d:\somefile.txt.xxx" %>

  Managing Random Keys

In an enterprise environment, using password-derived keys may not be feasible as everybody would have to share a password to encrypt and decrypt files. It makes more sense to encrypt files using randomly generated keys that are stored in a key repository and dispensed to eligible authenticated users upon request. Needless to say, these keys would have to be encrypted.

AspEncrypt provides methods to generate random keys of desired length and export them to a file in an encrypted form using a public key from a key container. To obtain a key pair object, we must use CryptoContext's GetUserKey method. The method's only argument specifies whether the key pair is the Key Exchange pair (if set to True) or Signature key pair (if set to False). For example:

<!--METADATA TYPE="TypeLib" UUID="{B72DF063-28A4-11D3-BF19-009027438003}"--> <% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("mycontainer", True) Set key = Context.GenerateKey ' use default algorithm and key size key.EncryptFile "d:\somefile.txt", "d:\somefile.txt.xxx" 'use the key Set ExchangeKey = Context.GetUserKey( True ) ' obtain Key Exchange key pair key.ExportToFile ExchangeKey, "d:\mykey.key", cbtSimpleBlob ' export key to file %>

Decryption code may look like this:

<% ... Set Key = Context.ImportKeyFromFile( ExchangeKey, "d:\mykey.key", cbtSimpleBlob ) key.DecryptFile "d:\somefile.txt.xxx", "d:\somefile.txt" %>

This time we use the private key component of a key container to decrypt the symmetric key stored in a file.

If you do not wish to encrypt symmetric keys being exported, you should pass a special Exponent 1 key pair as the first argument. The Exponent 1 key pair does nothing to information being encrypted/decrypted (encrypting with the Exponent 1 key is equivalent to multiplying a number by 1). An instance of the Exponent 1 key is created using the CryptoContext.CreateExponentOneKey method.

Due to certain concurrency issues, you must use the "containerless" mode when calling the CreateExponentOneKey method, i.e. an empty string must be passed to OpenContext as the first argument. Version 2.1 or higher of AspEncrypt is required to use this feature.

<% Set Context = CM.OpenContext("", True) ' containerless mode ... Set ExchangeKey = Context.CreateExponentOneKey ' obtain Exponent 1 key pair key.ExportToFile ExchangeKey, "d:\mykey.key", cbtSimpleBlob ' do not encrypt %>

  Encrypting Messages using the CryptoBlob Object

The CryptoKey object is capable of encrypting text messages as well as files. Once a message is encrypted it becomes an unreadable binary sequence. To store, export and import binary data, AspEncrypt offers a special object, CryptoBlob. The object has three read/write properties: Hex, Base64 and Binary. The Hex property returns binary data as a string oh hexadecimal characters. Base64 return the data in the Base64 encoding. Binary returns the data as VARIANT-wrapped Safe Array of bytes. The latter form can be used to store and retrieve binary data to and from the database using ADO.

The following example encrypts a text message and places the result binary data in a CryptoBlob object. The content of the blob is then dumped to a file and saved in an IMAGE field of a SQL Server database.

<% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("mycontainer", True) Set key = Context.GenerateKeyFromPassword("My secret password") ' use defaults Set Blob = key.EncryptText("My secret phrase.") ' use the key to encrypt a text Blob.DumpToFile "d:\blob.txt" ' dump blob content to a file ' Save blob in the database table BlobTest (IMAGE field Blob) set rs = Server.CreateObject("adodb.recordset") rs.Open "BlobTest", "dsn=crypto;uID=sa;PWD=;", 2, 3 rs.AddNew rs("Blob").Value = Blob.Binary ' Use the Binary property rs.Update %>

The corresponding decryption code may look like this:

<% ... Set Blob2 = CM.CreateBlob ' Create an empty CryptoBlob object Blob2.LoadFromFile "d:\blob.txt" ' Load from file Response.Write Key.DecryptText(Blob2) ' Decrypt and display %>

Starting with version 2.3, AspEncrypt supports Unicode versions of the EncryptText/DecryptText methods. The new methods are EncryptTextWide and DecryptTextWide. If you are encrypting a non-English text, you should always use EncryptTextWide instead of EncryptText.

Starting with AspEncrypt 2.01, you can use symmetric keys provided to you in a "raw" form - as a sequence of bits. This is useful for compatibility with other encryption packages. A raw key is imported into a CryptoKey object via the method Context.ImportRawKey which accepts two parameters: a CryptoBlob object containing the key bits, and an algorithm identifier.

Due to certain concurrency issues, you must use the "containerless" mode when calling the ImportRawKey method, i.e. an empty string must be passed to OpenContext as the first argument. Version 2.1 or higher of AspEncrypt is required to use this feature.

The following code snippet takes a 128-bit RC2 key in a Hex format and encrypts a file with it:

<% Set Context = CM.OpenContext("", True) ' must use containerless mode Set Blob = CM.CreateBlob ' Create an empty CryptoBlob object Blob.Hex = "1804A391BBD829605AE7DC3D30B8708B" ' 128 bit key in Hex format Set Key = Context.ImportRawKey( Blob, calgRC2 ) ' Import into CryptoKey Key.EncryptFile "c:\file.txt", "c:\file.txt.xxx" %>

Starting with AspEncrypt 2.3, you can easily retrieve raw bits of a key via the property Key.RawBits, which returns a CryptoBlob object containing the key bits. For example:

<% Set Context = CM.OpenContext("", True) Set Key = GenerateKey(...) Response.Write Key.RawBits.Hex %>