AspEncrypt.com - Object Reference: CryptoContext

Main Menu:	Home \| News \| Manual \| Object Reference \| Crypto 101 \| Download & Buy \| Live Demo \| Support \| Contact
Navigator:	Home \| Object Reference \| CryptoContext Object

The CryptoContext object represents a cryptographic context which is a handle that connects a cryptographic service provider (CSP) with one of its key containers. An instance of the CryptoContext object is created with the OpenContext method of the CryptoManager object.

Properies Methods

ContainerName
KeySpec
ProviderName
ComputeHmac
CreateCertificate
CreateCertificateFromRequest
CreateCRL
CreateEmptyKey
CreateExponentOneKey
CreateHash
CreateMessage
GenerateCertificateRequest
GenerateKey
GenerateKeyFromPassword
GetUserKey
ImportKeyFromBlob
ImportKeyFromCert
ImportKeyFromFile
ImportPublicKey
ImportRawKey

CryptoContext Properties

ContainerName As String (Read-Only)

Returns the name of a key container which corresponds to this context.

KeySpec As Long (Read-Only)

Returns 1 if this context corresponds to the key exchange key of a container, or 2 if it corresponds to the signature key of a container. This property is only meaningful if this context object was returned by the PrivateKeyContext property of the CryptoCert object.

ProviderName As String (Read-Only)

Returns the name of a CSP which corresponds to this context.

CryptoContext Methods

Function ComputeHmac ( Hash As CryptoAlgorithms, Key As CryptoBlob, Message As CryptoBlob ) As CryptoBlob
Computes the hash-based Message Authentication Code (HMAC) function from the Key and Message values.
Hash specifies a hash algorithm this HMAC is based on. Valid values are: calgMD4, calgMD5, calgSHA, calgSHA256, calgSHA384 and calgSHA512. The last three hash algorithms require the Microsoft Enhanced RSA and AES Cryptographic Provider.
Return value: a CryptoBlob object populated with the HMAC value.
This method was introduced in Version 2.6.
Usage:
Set HmacBlob = Context.ComputeHmac( calgSHA, KeyBlob, MessageBlob )
Relevant Section: 3.5 Hash-based Message Authentication Code (HMAC).

Function CreateCertificate ( SignerContext As Context, Subject As String, NotBefore As Date, NotAfter As Date, IncludePrivateKey As Boolean ) As CryptoCert
Generates an X.509 digital certificate based on Subject and this context's key-exchange public key, and signed by Context's private key.
To generate a self-signed certificate, Context must be set to Nothing. To sign the new certificate with another certificate, the signer certificate's PrivateKeyContetx property must be used to obtain its private key context.
NotBefore and NotAfter specify the certificate's validity period.
IncludePrivateKey specifies whether the corresponding private key context must be saved with the certificate when the latter is copied to a certificate store. You must set this argument to True if you are to use the certificate being created for signing other certificates.
See the description of Subject in the comments to the GenerateCertificateRequest method.
Return value: a CryptoCert object representing the newly created certificate.
Usage:
Set Cert = Context.CreateCertificate( SignerCert.PrivateKeyContext, Subject, Now(), Now() + 365, True )
Relevant Section: 7.2 Certification Authority Hierarchy.

Function CreateCertificateFromRequest ( SignerContext As Context, Request As String, NotBefore As Date, NotAfter As Date ) As CryptoCert
Generates an X.509 digital certificate based on the subject and public key contained the specified certificate request string.
Request is a Base64-encoded PKCS#10 certificate request string.
See the comments to the CreateCertificate method for the description of the other arguments.
If SignerContext is set to Nothing, this context's private key will be used to sign the new certificate.
Return value: a CryptoCert object representing the newly created certificate.
Usage:
Set Cert = Context.CreateCertificateFromRequest( _
SignerCert.PrivateKeyContext, Request, Now(),
Now() + 365 )
Relevant Section: 7.5 Personal and SSL Certificate Live Demos.

Function CreateCRL ( IssuerContext As Context, ThisUpdate As Date, NextUpdate As Date, ) As CryptoCrl
Generates a certificate revocation list (CRL) signed by IssuerContext's private key.
ThisUpdate specifies when the CRL is created. NextUpdate specifies when the next CRL update is scheduled to be issued.
Returns an empty CryptoCrl object. You must call the AddRevocation method on that object one or several times to add revocation entities to the CRL. After that, the ExportToFile method must be called on the object to save the newly created CRL to a file.
Return value: a CryptoCrl object representing an empty CRL.
Usage:
Set CRL = Context.CreateCRL( SignerCert.PrivateKeyContext, Now(), Now() + 30 )

Function CreateEmptyKey ( Optional Algorithm = calgRC2, Optional BitSize = 0 ) As CryptoKey
Creates an empty key object to be used by the AspUpload component to derive a key from a user-uploaded password.
See the comments to the GenerateKey method for the description of the arguments.
Return Value: a CryptoKey object containing the newly created empty key.
Usage:
Set Key = Context.CreateEmptyKey
Related Section: 2.6 Using AspEncrypt with AspUpload.

Function CreateExponentOneKey As CryptoKey
Creates an "Exponent 1" RSA key pair. Encrypting and decrypting with this key does not change information being encrypted/decrypted. If you need to export symmetric keys in plain text (unencrypted), pass this key as the first argument to CryptoKey's ExportToFile or ExportToBlob methods.
Version 2.1 or higher of AspEncrypt is required to avoid concurrency problems. Use the "containerless" mode of operation when using this method by passing an empty string to OpenContext.
Return Value: a CryptoKey object containing the newly created Exponent 1 key.
Usage:
Set Context = CM.OpenContext("", True) ' Containerless mode required
Set Key = Context.CreateExponentOneKey

Function CreateHash ( Optional Algorithm = calgSHA ) As CryptoHash
Creates an empty hash object to be used to calculate a one-way hash function from text or files.
Algorithm specifies the hash algorithm to be used. It must be set to one of the following values: calgSHA (default), calgMD2, calgMD4 and calgMD5 for the SHA, MD2, MD4 and MD5 hash algorithms, respectively.
On Windows 2003 with the Microsoft Enhanced RSA and AES Cryptographic Provider, you can also use the values calgSHA256, calgSHA384 and calgSHA512 for the SHA-256, SHA-384 and SHA-512, respectively (version 2.3.0.3 or higher of AspEncrypt is required).
Return Value: a CryptoHash object representing the newly creates empty hash.
Usage:
Set Hash = Context.CreateHash
Relevant Sections: 3.2 Computing Hash with AspEncrypt, 6.3 Creating and Verifying Digital Signatures.

Function CreateMessage ( Optional TripleDES = False ) As CryptoMessage
Creates an empty CryptoMessage object to be used by the AspEmail component to send encrypted or signed mail.
TripleDES, if present and set to True, specifies that the message is to be encrypted using the Triple DES algorithm (168-bit encryption).
Return value: an empty CryptoMessage object.
Usage:
Set Msg = Context.CreateMessage
Relevant Sections: 5.2 CryptoMessage Object, 9.2 Encrypting & Decrypting Text Directly with Certificates.

Function GenerateCertificateRequest ( Subject As String ) As String
Generates a Base64-encoded PKCS#10 Certificate Request file based on this context's key-exchange public key and Subject.
Subject is a CR/LF-separated string of tagged name values. The most common tags are CN (common name), O (organization), OU (organizational unit), C (country), S (state/province), L (locale/city), and E (email).
Return value: a Base64-encoded Certificate Request string which can be sent to a certification authority to obtain a certificate. Usage:
Subject = "CN=John Smith" & chr(13) & chr(10)
Subject = Subject & "O=Acme Software" & chr(13) & chr(10)
Subject = Subject & "OU=Development" & chr(13) & chr(10)
Subject = Subject & "C=US" & chr(13) & chr(10)
Subject = Subject & "E=jsmoth@acmesoftware.com"
CertRequestString = Context.GenerateCertificateRequest( Subject )

Function GenerateKey ( Optional Algorithm = calgRC2, Optional BitSize = 0 ) As CryptoKey
Creates a symmetric cryptographic key of the specified algorithm and size.
If the current CSP is the Microsoft Base Cryptographic Provider, Algorithm can be set to one of the following values: calgRC2 (default) and calgRC4 for the RC2 and RC4 algorithms, respectively. If the current CSP is the Microsoft Enhanced Cryptographic Provider, Algorithm can also be set to one of the following values: calgDES, calg3DES and calg3DES2 for the DES, Triple DES, and Triple DES with 2 Keys algorithms, respectively. If the current CSP is the "Microsoft Enhanced RSA and AES Cryptographic Provider (Prototype)" (XP) or "Microsoft Enhanced RSA and AES Cryptographic Provider" (Windows 2003), Algorithm can also be set to calgAES128, calgAES192 and calgAES256 for 128-bit, 192-bit and 256-bit AES keys, respectively (AspEncrypt 2.3+ is required for AES support).
If BitSize is set to 0 (default value) it means the key size is the default one for the specified algorithm and current CSP. Otherwise, it specifies the key size. For the list of algorithms and their respective default and valid key sizes, see 2.3 Encrypting Text and Files.
Return Value: a CryptoKey object containing the newly created key.
Usage:
Set Key = Context.GenerateKey(calgRC4)

Function GenerateKeyFromPassword ( Password As String, Optional HashAlgorithm = calgSHA, Optional Algorithm = calgRC2, Optional BitSize = 0 ) As CryptoKey
Derives a symmetric cryptographic key from the specified Password.
A key is derived by computing a one-way hash function from the specified password. HashAlgorithm specifies the hash algorithm to be used. It can be set to one of the following values: calgSHA (default), calgSHA256, calgMD2, calgMD4, calgMD5 for the SHA, SHA256, MD2, MD4 and MD5 hash algorithms, respectively.
See the comments to the GenerateKey method for the description of the other arguments.
Return Value: a CryptoKey object containing the newly created key.
Usage:
Set Key = Context.GenerateKeyFromPassword("my password", calgMD4, calgRC4)
Related Section: 2.3 Encrypting Text and Files.

Function GetUserKey ( KeyExchange As Boolean ) As CryptoKey
Obtains a public/private key pair from the current container. KeyExchange specifies whether the Key Exchange (if True) or Signature (if False) key pair should be used.
Return value: a CryptoKey object representing the key pair.
Usage:
Set Key = Context.GetUserKey(True)
Relevant Section: 6.2 OpenContext Method Revisited.

Function ImportKeyFromBlob ( ExchangeKey As CryptoKey, Blob As CryptoBlob, BlobType As CryptoBlobTypes) As CryptoKey
Identical to ImportKeyFromFile except that the key blob is obtained from a CryptoBlob object rather than a file.

Function ImportKeyFromCert ( Cert As CryptoCert ) As CryptoKey
Imports a certificate's public key into a CryptoKey object.

Return value: a CryptoKey object representing a certificate's public key.
Usage:
Set Key = Context.ImportKeyFromCert(Cert)
Relevant Section: 6.4 Signing with a Certificate Private Key Context.

Function ImportKeyFromFile ( ExchangeKey As CryptoKey, Path As String, BlobType As CryptoBlobTypes) As CryptoKey
Imports a previously saved key from a file into a CryptoKey object.
ExchangeKey specifies a key to be used to decrypt the key if it was encrypted during exporting. If a symmetric key is being imported, ExchnageKey must be a key pair. If a key pair is being imported, ExchangeKey must be a symmetric key. If a public key is being imported no decryption is necessary and the argument should be set to Nothing.
Path specifies the path to the file containing the key being imported.
BlobType specifies what type of key blob is being imported. It can be set to one of the following values: cbtSimpleBlob, cbtPrivateKeyBlob, or 0 (if a public key alone is being imported).
Return value: a CryptoKey object representing the newly created key.
Usage:
Set Key = Context.ImportKeyFromFile( XChangeKey, "d:\path\mykey.key", cbtSimpleBlob )
Relevant Section: 6.2 OpenContext Method Revisited.

Function ImportPublicKey ( PublicKey As CryptoBlob ) As CryptoKey
Imports a public key in PEM format into a CryptoKey object. PublicKey is a CryptoBlob object containing the key data without the header and footer -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----.
This method was introduced in version 2.6.
Return value: a CryptoKey object representing the specified key.
Usage:
sKey = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDIxa9c7tYDvCL5ZCk5FGT2Zlo2"
sKey = sKey & "nYLEpX1KocTjfggXjrnL6+92HZMJs2jcbxp6Q4lyMPhlGP3t7/DCBpXM39v7w3U7"
sKey = sKey & "HRy0GAxa7tWICCnvXZRoI2BKF3bZDuWSeNyHXJtkJwnId6udn7eLj2q5TdTxc8On"
sKey = sKey & "JpCKjheJ/xs9fFHmSwIDAQAB"
Set Blob = CM.CreateBlob
Blob.Base64 = sKey
Set Key = Context.ImportPublicKey( Blob )
Relevant Section: 9.5.2 Importing Public Keys in PEM Format.

Function ImportRawKey ( KeyBits As CryptoBlob, Alg As CryptoAlgorithms, Optional ReverseBytes = False ) As CryptoKey
Imports a symmetric (session) key into a CryptoKey object from given "raw" key bits. KeyBits is a CryptoBlob object containing the key bits. Alg specifies a symmetric encryption algorithm such as calgRC2, calgRC4, calgDES, calg3DES etc. The difference between the methods ImportRawKey and ImportKeyFromBlob is that the former accepts a key in a "raw" format - no headers, version information, padding, etc. This method is useful for compatibility with other encryption packages.
ReverseBytes (introduced by AspEncrypt 2.1.0.2) is an optional parameter which is set to False by default. If set to True, causes the byte order of the key to be reversed. This is useful if a 3rd party encryption package supplies its keys with the byte order opposite to the order CryptoAPI (and AspEncrypt) use. Whether you should use this parameter can usually be determined by trial and error.
Version 2.1 or higher of AspEncrypt is required to avoid concurrency problems. Use the "containerless" mode of operation when using this method by passing an empty string to OpenContext.
Return value: a CryptoKey object representing the specified key.
Usage:
Set Context = CM.OpenContext("", True) ' Containerless mode required
Set Blob = CM.CreateBlob
Blob.Hex = "1804A391BBD829605AE7DC3D30B8708B" ' 128 bit
Set Key = Context.ImportRawKey(Blob, calgRC2)
Relevant Section: 2.5 Key Importing and Exporting.

Search this Site