 |
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.
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.
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)
%>
|
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
%>
|
The CryptoContext object's responsibilities include
the creation and management of keys, hashes, messages, certificates and certificate requests, as shown
in the following sections.
|
|
|
|
|
