Chapter 1: Introduction & Quick Start
Contents
1.1 What is AspEncrypt?
AspEncrypt is an ActiveX server component that brings security to your ASP or .NET application through encryption. With AspEncrypt, you can encrypt text and files, send certificate-based secure mail, compute one-way hash values, generate and verify digital signatures, issue and manage X.509 digital certificates.
Although this user manual is written primarily for ASP and ASP.NET developers, AspEncrypt can be used with any development environment supporting COM, such as VB, Access, SQL Server, PHP, etc.
1.2 Feature Summary
- Easy, intuitive programming interface, most tasks can be implemented in just a few lines of script.
- Encrypts text and files with all major symmetric ciphers: RC2, RC4, DES, Triple-DES, AES.
- Encryption keys can be created randomly, generated from a password, or imported from an external source.
- Ability to specify an initialization vector (IV), cipher mode and padding.
- Computes one-way hash functions of text and files. All major hash functions are supported: MD4, MD5, SHA, SHA256.
- Encrypts files as they are being uploaded, and decrypts files as they are being downloaded, when used in conjunction with AspUpload.
- Sends certificate-based secure email in S/MIME format when used in conjunction with AspEmail. Email can be encrypted, digitally signed, or both.
- Creates and manages digital certificates. Can be used to set up a local certification authority.
- Manages certificate stores.
- Supports the .cer, .spc and .pfx (.p12) certificate and store formats.
- Creates and verifies digital signatures in PKCS#1 and PKCS#7 formats.
- Encrypts (decrypts) data directly with a digital certificate's public (private) key.
- Supports PKCS#7-based signatures and envelopes.
- Can be use as a client-side ActiveX control to perform cryptographic functions on a user machine without needing additional licenses.
1.3 System Requirements
- Windows NT • 2000 • XP • 2003 • Vista • 2008 • 7 • 2012 • 8 • 2016 • 2019;
- IIS with ASP or ASP.NET, or
- Any development environment supporting COM.
1.4 Installation & Expiration Mechanism
The AspEncrypt component consists of a single file, aspencrypt.dll (or, in case of the 64-bit version, aspencrypt64.dll). Being a COM object, this DLL needs to be registered on the server. The installer aspencrypt.exe (aspencrypt64.exe) performs the registration automatically. If manual installation is needed, the DLL must be registered with regsvr32.
To use AspEncrypt under .NET, the interop assembly ASPENCRYPTLib.dll (shipped with the component) needs to be placed in the /Bin subfolder of the application. The main DLL aspencrypt.dll still needs to be properly registered.
AspEncrypt works for 30 days without a registration key, and throws an expiration error afterwards. The purchased key needs to be placed in the system registry, as the default value, under
Alternatively, the registration key can be specified in your code via the RegKey property of the top-level CryptoManager object, as follows:
CM.RegKey = "12345-12345-12345"
...
The current expiration date of the component can be retrieved via the Expires property, as follows:
Response.Write CM.Expires
If this property returns 9/9/9999 it means a permanent registration key is being used.
1.5 Quick Start
At first, the top-level CryptoManager object is created, which serves as an object factory for all other AspEncrypt objects. Then a cryptographic context is opened via the method OpenContext. An instance of the CryptoContext object encapsulates the handle to a cryptographic provider, a Windows library that actually contains the cryptographic functionality we need (in this case, symmetric encryption.) The OpenContext method and cryptographic providers will be covered in detail in the next chapter.
Using CryptoContext, an instance of the CryptoKey object is then created via the method GenerateKeyFromPassword. CryptoKey encapsulates symmetric encryption and decryption functionality via the methods EncryptText and DecryptText, among others.
Once text is encrypted, it becomes an unreadable binary sequence. To store, export and import binary data, AspEncrypt offers a special object, CryptoBlob. An instance of CryptoBlob is the return value of the EncryptText method, and the input argument to the DecryptText method. An empty CryptoBlob object can be created via CryptoManager's CreateBlob method.
Set Context = CM.OpenContext( "", True )
' Create key from a password. Use default hash, cipher, and key size.
Set Key = Context.GenerateKeyFromPassword("mypassword")
Text = "my secret text"
Response.Write "Original text: " & Text
' Encrypt
Set Blob = Key.EncryptText( Text )
Response.Write "<P>Encrypted text in Base64 format: " & Blob.Base64
' Decrypt
Set Blob2 = CM.CreateBlob
Blob2.Base64 = Blob.Base64
ClearText = Key.DecryptText( Blob2 )
Response.Write "<P>Decrypted text: " & ClearText
<%@ Import Namespace="System.Reflection" %>
<%@ Import Namespace="ASPENCRYPTLib" %>
<script language="c#" runat="server">
void Page_Load(Object Source, EventArgs E)
{
ICryptoManager objCM = new CryptoManager();
ICryptoContext objContext = objCM.OpenContext( "", true, Missing.Value );
// Create key from a password. Use default hash, cipher, and key size
ICryptoKey objKey = objContext.GenerateKeyFromPassword("mypassword",
Missing.Value, Missing.Value, Missing.Value);
String strText = "my secret text";
txtResult.Text = "Original text: " + strText;
// Encrypt
ICryptoBlob objBlob = objKey.EncryptText( strText );
txtResult.Text += "<P>Encrypted text in Base64 format: " + objBlob.Base64;
// Decrypt
ICryptoBlob objBlob2 = objCM.CreateBlob();
objBlob2.Base64 = objBlob.Base64;
String strClearText = objKey.DecryptText( objBlob2 );
txtResult.Text += "<P>Decrypted text: " + strClearText;
}
</script>
<asp:Label runat="server" id="txtResult"/>
Click the links below to run this code sample:
