AspEncrypt always works with the default Cryptographic Service Provider (CSP). The CryptoManager object provides a method, SetDefaultProvider, that sets the current default provider. The following VB code snippet sets the default CSP for the current logged-in user to the Microsoft Base Cryptographic Provider:

Dim CM As CryptoManager Set CM = New CryptoManager CM.SetDefaultProvider "Microsoft Base Cryptographic Provider v1.0"

When AspEncrypt is used in an ASP environment, the following code may be used:

<% Set CM = Server.CreateObject("Persits.CryptoManager") CM.LogonUser "domainname", "username", "password" CM.SetDefaultProvider "Microsoft Base Cryptographic Provider v1.0" %>

The line CM.LogonUser... impersonates an admin account. If that line were omitted the CM.SetDefaultProvider would probably result in an "Access Denied" error as setting a default provider involves making changes to the system registry and the anonymous user IUSR_MACHINENAME usually does not have sufficient permissions to do so.

To set the default CSP to the Microsoft Enhanced Provider, change the argument passed to SetDefaultProvider accordingly:

... CM.SetDefaultProvider "Microsoft Enhanced Cryptographic Provider v1.0"

You must make sure the Microsoft Enhanced Cryptographic Provider has been installed on your machine. All available providers on your machine are listed under the registry key

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\Defaults\Providers.

Note. Typical applications will not use the SetDefaultProvider method. It is intended for use solely by administrative applications.

The notion of a cryptographic context is central to CryptoAPI. It is a handle that connects a certain Cryptographic Service Provider with one of its key containers. AspEncrypt provides an object, CryptoContext, that encapsulates the functionality of a cryptographic context. An instance of the CryptoContext object is created using CryptoManager's method OpenContext.

In Windows NT, the Microsoft CSPs stores key containers in two sections of the system registry: HKLM\...\Cryptography\MachineKeys and HKCU\...\Cryptography\UserKeys. Therefore, a key container is uniquely identified by its name and a flag indicating whether the key is located under the HKLM or HKCU sections of the registry. Likewise, Windows 2000 stores key containers in two folders underneath the \Documents and Settings tree: \<current user>\Application Data\Mcrosoft\Crypto\RSA and \All Users\Application Data\Microsoft\Crypto\RSA.

Accordingly, the CM.OpenContext method accepts two arguments: a key name and a Boolean value which means HKLM if set to True and HKCU otherwise (in Windows 2000 it means the All Users or <current user> folders, respectively). Generally, the following rule applies: if you are using AspEncrypt from a stand-alone application with a user interface you should set the Boolean parameter to False. If AspEncrypt is to run in the context of a non-interactive user (such as in an ASP or ISAPI application) you should set the Boolean parameter to True.

' VB code Dim CM As CryptoManager Dim Context As ICryptoContext Set CM = New CryptoManager Set Context = CM.OpenContext("mycontainer", False)

<% ' ASP code Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("mycontainer", True) %>

The OpenContext method attempts to open the specified key container. If a container by the specified name does not exist the method creates it. If the container happens to be empty (i.e. contains no key pairs) the method creates two key pairs: one for key exchange and the other for digital signatures.

On Windows NT, you may experience the following error when calling OpenContext in the ASP environment:

Persits.CryptoManager.1 error '800a0001'
Keyset does not exist

This is a security problem and can be fixed by modifying permissions on the corresponding container key in the system registry. See question Q202 of the FAQ.

The Windows 2000 equivalent of this error message is, surprisingly,

Persits.CryptoManager.1 error '800a0001'
Object already exists

Question Q204 of the FAQ covers this error. It's not clear why CryptoAPI developers insist on using error messages that are rather irrelevant to the actual error condition, in this case - lack of permissions.

  Using the "Containerless" Mode

Starting with Version 2.1, AspEncrypt supports a "containerless" mode of operation which does not require a container name to be specified.

<% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("", True) %>

When a container name is not specified, AspEncrypt does not attempt to access private keys, which results in a significant improvement in performance and eliminates certain concurrency problems.

You should not use the containerless mode if you call the method Context.GetUserKey .

You must use this mode if you call the methods Context.CreateExponentOneKey and Context.ImportRawKey.

  Specifying Cryptographic Service Providers Explicitly

Starting with Version 2.0, AspEncrypt enables you to specify both the cryptographic provider and context via the method OpenContextEx. This relieves you of the necessity to set a default cryptographic provider via the SetDefaultProvider method as described above. The following line of code invokes the Enhanced Crypographic Provider no matter what the current default provider is:

<% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContextEx("Microsoft Enhanced Cryptographic Provider v1.0", "mycontainer", True) %>

  Obtaining the CSP of a Context

For debugging purposes, it is a good idea to make sure your CryptoContext object is associated with the right cryptographic provider. To obtain the name of the context's CSP, use CryptoContext's ProviderName read-only property, as follows:

<% Set CM = Server.CreateObject("Persits.CryptoManager") Set Context = CM.OpenContext("mycontainer", True) Response.Write Context.ProviderName %>

  What is the CryptoContext Object For?

The CryptoContext object's responsibilities include the creation and management of keys, hashes, messages, certificates and certificate requests, as shown in the following sections.