Encryption
Component Reference
Chilkat
Crypt makes it easy for applications to encrypt/decrypt data or
files using the latest AES symmetric compression algorithms. You
can also PKI-enable your applications to encrypt/decrypt data
using public-key algorithms or generate/verify digital signatures.
Choosing
An Algorithm
Algorithm Parameters
Encrypting Data
Decrypting Data
Creating Digital Signatures
Verifying Digital Signatures
*
Chilkat grants permission to Internet Service Providers and Web
Hosting Companies to reproduce this content for the benefit of
its clients.
Unlocking
the Component
|
(Method)
UnlockComponent(String unlockCode)
This method must be called once at the beginning of a program
to unlock the component. A 30-day unlock code can be obtained
from http://www.chilkatsoft.com/chilkatCrypt.asp.
|
Choosing
an algorithm
|
(Method)
SetAlgorithmBlowfish()
Sets the algorithm to Blowfish.
This implementation of Blowfish will accept key lengths
from 40 bits to 448 bits, the default being 128 bits.
(Method)
SetAlgorithmRijndael()
Sets the algorithm to Rijndael.
This implementation of Rijndael will accept key lengths
of 128, 192, or 256 bits, the default being 128 bits. Chilkat
Crypt runs this algorithm in CBC (Cipher Block Chaining)
mode, which cannot be changed. (CBC mode is typically the
default mode used for the Rijndael algorithm.) For a good
explanation of block cipher modes, click HERE.
(Method)
SetAlgorithmTwofish()
Sets the algorithm to Twofish.
This implementation of Twofish will accept key lengths of
128, 192, or 256 bits, the default being 128 bits. Chilkat
Crypt runs this algorithm in CBC (Cipher Block Chaining)
mode, which cannot be changed. (CBC mode is typically the
default mode used for the Twofish algorithm.) For a good
explanation of block cipher modes, click HERE.
(Method)
SetAlgorithmPKI()
Uses a public-key encryption algorithm to encrypt. Before
encrypting data or a file, you must first specify a certificate
either directly with the SetEncryptCertificate
method, or indirectly using the EncryptCertSubject
property. By default, the RC4 algorithm is used for encryption,
unless one of the following methods is called: SetAlgorithmPkiRC2,
SetAlgorithmPkiDES, or SetAlgorithmPki3DES.
- (Method)
SetAlgorithmPkiRC2()
- No longer
used, use SetCSP instead.
- (Method)
SetAlgorithmPkiRC4()
- No longer
used, use SetCSP instead.
- (Method)
SetAlgorithmPkiDES()
- No longer
used, use SetCSP instead.
- (Method)
SetAlgorithmPki3DES()
- No longer
used, use SetCSP instead.
- (Method)
SetCSP(csp
As ChilkatCSP)
- Sets the
encryption and digital signature preferences for public-key
encryption. The ChilkatCSP
object will control the Cryptographic Service Provider
used, the key container within the CSP to be used, and
the encryption/hash algorithms.
IMPORTANT:
Click HERE
for important information regarding Warning Dialogs displayed
by Microsoft Windows when directly or indirectly accessing
private keys.
|
Setting
Algorithm Parameters
Symmetric
encryption algorithms
Symmetric algorithms (Blowfish,
Twofish, and Rijndael) have only 2 parameters: the key length
and a password. The key length is 128 bits by default, and this
is typically more than adequate. The longer the key length, the
more secure. When decrypting, the password and key length must
match the original values used for encryption.
- (Property)
KeyLength As Long read/write
The length of the symmetric algorithm encryption key,
in bits. The default is 128. The Rijndael and Twofish
algorithms only accept key lengths of 128, 192, and 256
bits. The Blowfish algorithm will accept anything from
40 to 448 bits.
(Property)
Password As String read/write
The symmetric algorithm password. To decrypt successfully,
the password and key length must match the values used during
encryption.
|
- Public-key
encryption algorithms (PKI)
In a public key system (PKI), a
message is encrypted by the sender using the public key of the
receiver. The receiver decrypts the message using a certificate
containing his private key, and since nobody else has this key,
he is the only one that can read the message. So... for PKI you
need to identify the receiver's certificate to be used for encryption.
This can be specified either directly (with SetEncryptCertificate)
or indirectly with the EncryptCertSubject
property. The details of the
certificate are stored in the encrypted data, and this information
is used by the decrypt function to locate the matching certificate
(containing the private key). Certificates are stored in "certifcate
stores", which in Microsoft Windows systems, are usually
persisted in the registry. By default, Chilkat Crypt looks for
the matching certificate in the most common (standard) certificate
stores, so you probably don't need to worry about this -- Chilkat
Crypt will just magically find the matching certificate for decryption.
If however you do need to specify a list of certificate stores
to be searched, you can use the AddSearchCertStore
method.
Standard
Certificate Store Search List
By default, Chilkat searches the
following certificate stores for certificates for PKI encryption,
decryption, or signing:
- Local Machine Certificate Store:
This exists on every MS Windows system and is located in the
registry. These certificates are shared amongst all users of
the system.
- Chilkat Mail Certificate Store:
This is the certificate store used with Chilkat Mail, and is
located in the registry under HKEY_LOCAL_MACHINE:Software/Chilkat/SystemCertificates
- Microsoft AddressBook: This
is the certificate store used by Microsoft Outlook and is located
in the registry under HKEY_CURRENT_USER:Software/Microsoft/SystemCertificates/AddressBook.
- Current User Certificate Store:
This exists on every MS Windows system and is located in the
registry. Each user has his own private certificate store.
Here is a simple
program (executable) that displays the subjects and emails of
certificates in each of the above certificate stores:
CertPeek.exe
(You need to have the Chilkat Certificate
component installed, as well as the Visual Basic runtime.)
|
(Method)
SetEncryptCertificate( certificate As ChilkatCert
)
Explicitly sets the certificate that should be used for
PKI encryption. No certificate stores are searched when
this is set. (See Chilkat Certificate
for details regarding the ChilkatCert object.)
(Property)
EncryptCertSubject As String read/write
An indirect way of specifying the certificate to be used
for public-key encryption. This string should match one
of the subject fields in a certificate, such as the common
name (CN), email address (E), organization (O), organizational
unit (OU), locality (L), state (ST), or country (C). See
Chilkat Certificate for
more information. (In most cases, it is easiest to identify
the certificate uniquely by specifying the email address.)
When encrypting data using
PKI, ChilkatCrypt will automatically attempt to locate and
use a certificate mathing this property's value. If a certificate
cannot be found, the encryption will fail. Otherwise, the
full subject and actual public-key encryption algorithm
will be saved in LastCertSubject
and LastAlgorithm.
(Property)
UseStandardSearchCertStores As Boolean read/write
If TRUE, the standard list of
certificate stores will be searched when a certifcate is
needed for public-key encryption, decryption, or digital
signature creation. If FALSE, the certificate stores added
via AddSearchCertStore
will be searched.
(Method)
AddSearchCertStore( certStore As ChilkatCertStore
)
Adds a certificate store to the list of certificate stores
to be searched when a private key is needed for PKI decryption,
or when a public-key is needed for PKI encryption. The ChilkatCertStore
object can be obtained from the Chilkat
Certificate component.
(Property)
LastCertSubject As String
read-only
Contains the full subject of the last certificate used for
PKI encryption or digital signature creation.
(Property)
LastAlgorithm As String
read-only
Contains a description of the public-key algorithm of the
last certificate used for PKI encryption or digital signature
creation.
|
Digital
Signatures
A digital signature is just a blob
of binary data containing information that allows the receiver
to verify that a message has not been modified. The message is
not encrypted, and the digital signature is a file or block of
data separate (detached) from the message. To create a digital
signature, a certificate with a private key is needed, and this
can be set directly with SetSigningCertificate
or indirectly with the SigningCertSubject
property. To verify, the matching public key is needed. Since
the public key and other details about the signing certificate
are stored in the signature, no certificate need be located from
a system certificate store to verify the signature.
|
(Method)
SetSigningCertificate( certificate As ChilkatCert
)
Explicitly sets the certificate that should be used for
digital signature creation. No certificate stores are searched
when this is set. (See Chilkat
Certificate for details regarding the ChilkatCert object.)
(Property)
SigningCertSubject As String read/write
An indirect way of specifying the certificate to be used
for creating digital signatures. This string should match
one of the subject fields in a certificate, such as the
common name (CN), email address (E), organization (O), organizational
unit (OU), locality (L), state (ST), or country (C). See
Chilkat Certificate for
more information. (In most cases, it is easiest to identify
the certificate uniquely by specifying the email address.)
When creating a digital signature,
ChilkatCrypt will automatically attempt to locate and use
a certificate mathing this property's value. If a certificate
cannot be found, the method call will fail. Otherwise, the
full subject and actual algorithm will be saved in LastCertSubject
and LastAlgorithm.
|
Encrypting
Data
Chilkat Crypt makes it easy to encrypt/decrypt
data by allowing for the input/output of the following types:
- Variant
- This type is used to hold binary
data, such as an array of bytes.
- String
- Even though encrypted data is
binary, it can still be returned as a string in Base64 format.
- CkData
- This object is provided as a
potential source or target for encryption/decryption. The reason
for doing so is to provide the ability to encrypt or decrypt
without returning the actual data from server to client.
- File
- Files can be directly encrypted
or decrypted.
Encrypting
Binary Data
The following functions accept a
Variant as input, and return encrypted data in the form of a Variant,
String, or CkData object.
|
(Method)
EncryptVar2Var( binaryData As Variant) As
Variant
Encrypt binary data, and return the encrypted data as a
Variant.
(Method)
EncryptVar2Str( binaryData As Variant) As
String
Encrypt binary data, and return the encrypted data as a
Base64 encoded string.
(Method)
EncryptVar2Obj( binaryData As Variant) As
CkData
Encrypt binary data, and return a reference to a CkData
object that holds the encrypted data.
|
Encrypting
Strings
The following functions accept a
String as input, and return encrypted data in the form of a Variant,
String, or CkData object.
|
(Method)
EncryptStr2Var( str As String) As Variant
Encrypt a string, and return the encrypted data as a Variant.
(Method)
EncryptStr2Str( str As String) As String
Encrypt a string, and return the encrypted data as a Base64
encoded string.
(Method)
EncryptStr2Obj( str As String)
As CkData
Encrypt a string, and return a reference to a CkData object
that holds the encrypted data.
|
Encrypting
CkData
The following functions accept a
CkData object as input, and return encrypted data in the form
of a Variant, String, or another CkData
object.
|
(Method)
EncryptObj2Var( dataObject As CkData) As
Variant
Encrypt the data contained within the CkData object, and
return the encrypted data as a Variant.
(Method)
EncryptObj2Str(
dataObject
As CkData)
As String
Encrypt the data contained within the CkData object, and
return the encrypted data as a Base64 encoded string.
(Method)
EncryptObj2Obj(
dataObject
As CkData)
As CkData
Encrypt the data contained within the CkData object, and
return a reference to a CkData object that holds the encrypted
data.
|
Encrypting
a File
The following function encrypts
a file.
|
(Method)
EncryptFile( inFileName
As String, outFileName As String) As Boolean
Encrypts a file, an creates an output file containing the
encrypted data. If outFileName is the same as inFileName,
the input file is replaced. This method returns TRUE for
success, and FALSE for failure.
(Method)
IsFileEncrypted( fileName
As String) As Boolean
Returns TRUE (1) if the file contains encrypted data produced
by Chilkat Crypt. Otherwise returns FALSE (0).
|
Decrypting
Data
Decrypting data is as flexible and
easy as encrypting data...
Decrypting
Binary Data
The following functions accept a
Variant as input, and return decrypted data in the form of a Variant,
String, or CkData object.
|
(Method)
DecryptVar2Var( encryptedData As Variant)
As Variant
Decrypt binary data, and return the decrypted data as a
Variant.
(Method)
DecryptVar2Str( encryptedData
As Variant) As String
Decrypt binary data, and return the decrypted data as a
string.
(Method)
DecryptVar2Obj( encryptedData
As Variant) As CkData
Decrypt binary data, and return a reference to a CkData
object that holds the decrypted data.
|
Decrypting
Strings
The following functions accept a
String containing encrypted data in Base64 format as input, and
return decrypted data in the form of a Variant, String, or CkData
object.
|
(Method)
DecryptStr2Var( str As String) As Variant
Decrypt a Base64 encoded string, and return the decrypted
data as a Variant.
(Method)
DecryptStr2Str( str As String) As String
Decrypt a Base64 encoded string, and return the decrypted
data as a string.
(Method)
DecryptStr2Obj( str As String)
As CkData
Decrypt a Base64 encoded string, and return a reference
to a CkData object that holds the decrypted data.
|
Decrypting
CkData
The following functions accept a
CkData object as input, and return decrypted data in the form
of a Variant, String, or another CkData
object.
|
(Method)
DecryptObj2Var( dataObject As CkData) As
Variant
Decrypt the data contained within the CkData object, and
return the decrypted data as a Variant.
(Method)
DecryptObj2Str(
dataObject
As CkData)
As String
Decrypt the data contained within the CkData object, and
return the decrypted data as a string.
(Method)
DecryptObj2Obj(
dataObject
As CkData)
As CkData
Decrypt the data contained within the CkData object, and
return a reference to a CkData object that holds the decrypted
data.
|
Decrypting
a File
The following function decrypts
a file.
(Method)
DecryptFile( inFileName
As String, outFileName As String) As Boolean
Decrypts a file, an creates an output file containing the
decrypted data. If outFileName is the same as inFileName,
the input file is replaced. This method returns TRUE for success,
and FALSE for failure. |
Creating
Digital Signatures
Digital signatures can be created
for a variety of data sources:
Creating
Digital Signatures for Binary Data
The following functions accept a
Variant as input, and return a signature in the form of a Variant,
String, or CkData object.
|
(Method)
CreateSigVar2Var( binaryData As Variant)
As Variant
Create a signature and return it as a Variant.
(Method)
CreateSigVar2Str(
binaryData As Variant) As String
Create a signature and return it as a Base64 encoded string.
(Method)
CreateSigVar2Obj(
binaryData As Variant) As CkData
Create a signature and return a reference to a CkData object
that holds it.
|
Creating
Digital Signatures for Strings
The following functions accept a
String as input, and return a signature in the form of a Variant,
String, or CkData object.
|
(Method)
CreateSigStr2Var(
str As String) As Variant
Create a signature and return it as a Variant.
(Method)
CreateSigStr2Str(
str As String) As String
Create a signature and return it as a Base64 encoded string.
(Method)
CreateSigStr2Obj(
str As String)
As CkData
Create a signature and return a reference to a CkData object
that holds it.
|
Creating Digital
Signatures for CkData Objects
The following functions accept a
CkData object as input, and return a signature in the form of
a Variant, String, or another CkData
object.
|
(Method)
CreateSigObj2Var(
dataObject As CkData) As Variant
Create a signature and return it as a Variant.
(Method)
CreateSigObj2Str(
dataObject
As CkData)
As String
Create a signature and return it as a Base64 encoded string.
(Method)
CreateSigObj2Obj(
dataObject
As CkData)
As CkData
Create a signature and return a reference to a CkData object
that holds it.
|
Creating
Digital Signatures for Files
The following functions accept a
filename as input, reads the file, and return a signature in the
form of a Variant, String, or another CkData
object.
|
(Method)
CreateSigFile2Var(
fileName As String ) As Variant
Create a signature and return it as a Variant.
(Method)
CreateSigFile2Str(
fileName
As String )
As String
Create a signature and return it as a Base64 encoded string.
(Method)
CreateSigFile2Obj(
fileName
As String )
As CkData
Create a signature and return a reference to a CkData object
that holds it.
|
Verifying
Digital Signatures
Each of the methods listed below
accept the original data and a signature, and return TRUE if the
original data hasn't been modified, or FALSE if it has, or if
there was an error in verifying the signature. If an error occured,
check the Chilkat Log for error messages.
|
(Method)
VerifySigFile2Var(
fileName As String, signature As Variant ) As Boolean
(Method)
VerifySigFile2Str(
fileName As String, signature As String ) As Boolean
(Method)
VerifySigFile2Obj(
fileName As String, signature As CkData ) As Boolean
(Method)
VerifySigVar2Var(
binaryData As Variant, signature As Variant ) As Boolean
(Method)
VerifySigVar2Str(
binaryData
As Variant,
signature As String ) As Boolean
(Method)
VerifySigVar2Obj(
binaryData
As Variant,
signature As CkData ) As Boolean
(Method)
VerifySigStr2Var(
str As String, signature As Variant ) As Boolean
(Method)
VerifySigStr2Str(
str
As String,
signature As String ) As Boolean
(Method)
VerifySigStr2Obj(
str
As String,
signature As CkData ) As Boolean
(Method)
VerifySigObj2Var(
dataObject As CkData, signature As Variant ) As Boolean
(Method)
VerifySigObj2Str(dataObject
As CkData,
signature As String ) As Boolean
(Method)
VerifySigObj2Obj(
dataObject
As CkData,
signature As CkData ) As Boolean
|
|
