Once an instance of the CryptoContext object is obtained, it can be used
to create a CryptoKey object that encapsulates the actual encryption and
decryption functionality. A key can be password-derived, imported from an external
source, or random.
2.3.1 GenerateKeyFromPassword Method
Password-derived keys are most common. To generate such a key, the CryptoContext method GenerateKeyFromPassword
should be used. This method accepts 4 arguments:
- the password string from which the key is to be derived (required);
- the hash algorithm which specifies how the password string is to be turned into a binary key (optional);
- the encryption algorithm (cipher) this key is to implement when called to perform an encryption or decryption (optional);
- the key bit size (optional).
The following tables list all possible values and their meanings for the 2nd and 3rd argument:
Available hash algorithms (2nd argument to GenerateKeyFromPassword):
| Value | Meaning | Bit size | CSP Required |
|---|
| calgMD4 | MD4 | 128 | Microsoft Strong Cryptographic Provider |
| calgMD5 | MD5 | 128 | Microsoft Strong Cryptographic Provider |
| calgSHA | SHA-1 | 160 | Microsoft Strong Cryptographic Provider |
| calgSHA256 | SHA-256 | 256 | Microsoft Enhanced RSA and AES Cryptographic Provider |
| calgSHA384 | SHA-384 | 384 | Microsoft Enhanced RSA and AES Cryptographic Provider |
| calgSHA512 | SHA-512 | 512 | Microsoft Enhanced RSA and AES Cryptographic Provider |
Default hash algorithm: calgSHA.
Available encryption algorithms / ciphers (3rd argument to GenerateKeyFromPassword):
| Value | Meaning | Default effective (total) bit size | CSP Required |
|---|
| calgRC2 | RC2 | 128 | Microsoft Strong Cryptographic Provider |
| calgRC4 | RC4 | 128 | Microsoft Strong Cryptographic Provider |
| calgDES | DES | 56 (64) | Microsoft Strong Cryptographic Provider |
| calg3DES | Triple-DES (3 keys) | 168 (194) | Microsoft Strong Cryptographic Provider |
| calg3DES2 | Triple-DES (2 keys) | 112 (128) | Microsoft Strong Cryptographic Provider |
| calgAES128 | AES-128 | 128 | Microsoft Enhanced RSA and AES Cryptographic Provider |
| calgAES192 | AES-192 | 192 | Microsoft Enhanced RSA and AES Cryptographic Provider |
| calgAES256 | AES-256 | 256 | Microsoft Enhanced RSA and AES Cryptographic Provider |
Default cipher: calgRC2.
Note that the DES family of ciphers has different effective and total bit sizes. That is because
a DES key is stored in the first 7 bits of each byte, and the 8th bit is used for parity-check purposes.
If the 4th argument (key size) to GenerateKeyFromPassword is omitted, the default key size is used as per table above.
2.3.2 CryptoKey Object
The CryptoKey object obtained from a call to GenerateKeyFromPassword encapsulates various
properties of an encryption key (such as the actual key bits, cipher, encryption mode, padding, etc.)
It provides 3 pairs of methods to encrypt and decrypt text, binary data, and files. These methods are:
- EncryptText
- DecryptText
- EncryptBinary
- DecryptBinary
- EncryptFile
- DecryptFile
EncryptText expects a single argument, a text string to encrypt. Since the encryption process turns text
into an unreadable sequence of bits, AspEncrypt provides a special auxiliary object, CryptoBob,
to store binary data. The CryptoBlob object returns the data it contains via its properties
Hex, Base64, Binary and Ansi in hexadecimal encoding,
Base64 encoding, as a byte array, or as an ASCII string, respectively.
CryptoBlob can be initialized via the same 4 properties also.
The following code snippets encrypt a text string with a password-derived Triple-DES key and stores the result
in Hex format in a variable:
| VBScript |
|---|
<!--METADATA TYPE="TypeLib" UUID="{B72DF063-28A4-11D3-BF19-009027438003}"-->
<%
Set CM = Server.CreateObject("Persits.CryptoManager")
Set Context = CM.OpenContext( "", True )
Set Key = Context.GenerateKeyFromPassword( "mypassword", calgSHA, calg3DES )
Set Blob = Key.EncryptText("some text")
txtEnc = Blob.Hex
%> |
| C# |
|---|
ICryptoManager objCM = new CryptoManager();
ICryptoContext objContext = objCM.OpenContext( "", true, Missing.Value );
ICryptoKey objKey = objContext.GenerateKeyFromPassword("mypassword",
CryptoAlgorithms.calgSHA,
CryptoAlgorithms.calg3DES,
Missing.Value);
ICryptoBlob objBlob = objKey.EncryptText("some text");
String txtEnc = objBlob.Hex; |
Note that the VBScript snippet above contains a special METADATA tag referencing AspEncrypt's type library GUID.
This is necessary to make AspEncrypt's built-in constants such as calgSHA and calg3DES available
to the script. There is no need for the METADATA tag in a .NET script but the constants must be prefixed
with their respective data types, in this case CryptoAlgorithms.
The following code snippets perform the opposite operation: decrypt the Hex-encoded string
generated by the previous snippets and store the result (original string) in another variable:
| VBScript |
|---|
<!--METADATA TYPE="TypeLib" UUID="{B72DF063-28A4-11D3-BF19-009027438003}"-->
<%
Set CM = Server.CreateObject("Persits.CryptoManager")
Set Context = CM.OpenContext( "", True )
Set Key = Context.GenerateKeyFromPassword( "mypassword", calgSHA, calg3DES )
Set Blob = CM.CreateBlob
Blob.Hex = txtEnc
txtDec = Key.DecryptText(Blob)
%> |
| C# |
|---|
ICryptoManager objCM = new CryptoManager();
ICryptoContext objContext = objCM.OpenContext( "", true, Missing.Value );
ICryptoKey objKey = objContext.GenerateKeyFromPassword("mypassword",
CryptoAlgorithms.calgSHA,
CryptoAlgorithms.calg3DES,
Missing.Value);
ICryptoBlob objBlob = objCM.CreateBlob();
objBlob.Hex = txtEnc;
txtDec = objKey.DecryptText(objBlob); |
Here we create an empty CryptoBlob object via the CreateBlob method of the CryptoManager object,
initialize it with the data obtained in the previous example, and pass it to the DecryptText
method which returns the decrypted data as a regular string.
The EncryptBinary and DecryptBinary methods work in a similar way except that
both methods have CryptoBlob objects as input and output.
The EncryptFile and DecryptFile methods expect two paths as their arguments: the path
to the input and output files:
| VBScript |
|---|
...
Key.EncryptFile "c:\path\original.txt", "c:\path\original.txt.enc"
...
Key.DecryptFile "c:\path\original.txt.enc", "c:\path\original.txt" |
| C# |
|---|
...
Key.EncryptFile( "c:\path\original.txt", "c:\path\original.txt.enc" );
...
Key.DecryptFile( "c:\path\original.txt.enc", "c:\path\original.txt" ); |
The following code sample (not shown here to conserve space) encrypts and decrypts a user-specified string with a user-specified password and cipher.
Click the links below to run this code sample:
http://localhost/aspencrypt/manual_02/02_encrypt.asp
http://localhost/aspencrypt/manual_02/02_encrypt.aspx
