What is it

key4.gif (2936 bytes) ActiveCRYPT 2.3

What is it:

Features:

  • Fast (ATL)
  • Reliable (OPENSSL)
  • Async mode
  • Longer keys than in WinCrypto API
  • Easy to use

How to:

  • Generate pair
  • Generate public key from private
  • Encrypt string
  • Decrypt string
  • Save keys
  • Load keys
  • Free keys

Legal notices

Disclaimer

©2001-2002 ActiveCrypt software


What is it

Features

Reliable (OPENSSL)

Just like an encryption/decryption core ActiveCrypt uses the fast and reliable OPENSSL library. This Library has a long history of development. It is widely used in different software systems. The functions of the library are fully compliant with RFC standards.

Speed

This component is written with ATL programming library which provides a set of fast functions to work with ActiveX objects.

Async mode

Asynchronous mode is a special feature of ActiveCrypt. It allows your program to continue its work after submitting a task. This feature prevents your program from being blocked andis very useful for the procession of large blocks of data.

Long keys then WinCrypto API

As soon as the core of the component is not bound to WinCrypto API or any other encryption features of Windows, it can use a stronger encryption than it is allowed by USA export limitations. 128bit keys should be considered to be unreliable in the world of quickly growing technical progress. The presence of the encryption core inside of the component doesn't require from you any additional installations.

Easy

ActiveCrypt provides very simple functions to deal with encryption and hides all low level details. Thanks to its ActiveX structure, the ActiveCrypt component can be used in all programming languages such as VisualBasic, C++/C#, Delphi, Perl, etc.


Generate pair

Generation of a pair means a generation of pair of keys - private one and corresponding public key. The public key is used for encryption and the private key is usedfor decryption. Each key is represented by long value. The longer is the bit length of the key, the harder it is to bruteforce it. Unlike Windows build-in crypto system, the full version of ActiveCrypt provides an unlimited length of the key. It is only limited by the power of CPU you have. The shareware version of ActiveCrypt provides a maximum key length equal to 256 bit.
Key generation is quite easy. You must only call function GenerateCouple. In the following example 2 keys with size of 256 bits are created:

        Dim PrivateKey As Variant, PublicKey As Variant

        Set ActiveCryptObject = new ActiveCryptLib.RSACrypt
        ActiveCryptObject.GenerateCouple 256, PrivateKey, PublicKey
        ...

Usually, you will want to save those keys. To do this you should use SaveKey function. The keys will remain valid until you destroy ActiveCryptObject or explicitly free it with FreeKey function.


Generate public key from private

Generation of public key from private

Sometimes it is needed to create a public key from the private one. This, unlike the reverse procedure, is quite easy. To do this, you should only have the private key in memory (created with the GenerateCouple or loaded with the LoadKey ) and call GeneratePublicKey.

Example :

        PublicKey = ActiveCryptObject.GeneratePublicKey(PrivateKey)
        IF ActiveCryptObject.Error <> ERR_OK THEN MsgBox "Error happened"


How to decrypt string

How to decrypt strings.

ActiveCrypt makes the decryption of strings very easy. To do this, you must have a private key loaded in memory (created with the GenerateCouple or loaded with the LoadKey ). Please note:to load the private key, you must also specify a password.

        DecryptedString = ActiveCryptObject.PrivateDecrypt(PrivateKey, EncryptedString)
        If ActiveCryptObject.Error <> ERR_OK then MsgBox "Error happened!"

In an asynchronous mode you do not get a result immediately. Instead if this ActiveCryptimmediately returns you an empty string and starts thread to process the decryption internally. After the decryption is done the event OnDecryptionFinished is fired. For more information about the decryption in an asynchronous mode please read Async mode


How to encrypt string

How to encrypt strings

ActiveCrypt makes the encryption of strings very easy. To do this you must have the public key loaded in memory (created with theGenerateCouple or loaded with the LoadKey)

Example :

        ActiveCryptObject.Async = False
        CryptedString = ActiveCryptObject.PublicEncrypt(PublicKey, "Hello RSA!")
        If ActiveCryptObject.Error <> ERR_OK then MsgBox "Error happened!"

If you don't want your application to be locked and wait until the encryption is finished, you can use Async mode. In this case OnEncryptionFinised is fired when the encryption is finished. You can also pass the Cookie identificator to find which event returns which string. The Cookie is just any integer meaningful to you.

Here is an example:

        ActiveCryptObject.Async = True
        CryptedString1 = ActiveCryptObject.PublicEncrypt(PublicKey, "Hello RSA!", 12345)
        CryptedString2 = ActiveCryptObject.PublicEncrypt(PublicKey, "Hello World!", 54321)
        'in Async mode empty string returns immediately to CryptedString1 and CryptedString2
        ...
        Sub ActiveCryptObject_OnEncryptionFinished(ByVal Cookie As Long, ByVal CryptedText As String)
                ListBox1.AddItem "Cookie: "+Str(Cookie)+" "+CryptedText
        End Sub

If you use the synchronous mode you don't need Cookies and you may not pass them to PublicEncrypt. After the decryption is doneOnDecryptionFinished event is fired. For more information about decryption in asynchronous mode please read Async mode.


Save keys

After generating the keys, at least the private key should be saved using the SaveKey or SaveKeyToString function. Otherwise you will not be able to decrypt your data later in NO WAY. Please hold a few copies of your private keys. And please always remember that. If you loose the private key, you loose all your encrypted data. Public key can be created from the private key, but the private key can never be reproduced.

Another aspect you should consider is security and a place where to store keys. The ideal solution would be the following: only the public key should be stored in place where encryption is done (for example web server which accepts user data) . This means that even if a hacker breaks into your server and get the file with the public key he still won't be able to decrypt data.


Free keys

You must free the keys when you don't want to use them anymore. Although the keys are a small memory resource, it is better to free them in time. When you destroy RSACrypt object all keys produced by this object will be freed automatically.

Here is an example:

        Set ActiveCryptObject = new ActiveCryptLib.RSACrypt
        ActiveCryptObject.GenerateCouple 256, PrivateKey, PublicKey
        ...
        ActiveCryptObject.FreeKey PrivateKey
        ActiveCryptObject.FreeKey PublicKey
        ' continue to work with ActiveCryptObject


What is hash ?

A hash value (or simply hash) is a number generated from a string of text. The hash is substantially smaller than the text itself, and is generated by a formula in such a way that it is extremely unlikely that some other text will produce the same hash value. The purpose of using hash functions could be a password verification.

SHA1

The Secure Hash Algorithm (SHA), developed by NIST, along with the NSA, for use with the Digital Signature Standard (DSS) is specified within the Secure Hash Standard (SHS) [National Institute of Standards and Technology (NIST). FIPS Publication 180: Secure Hash Standard (SHS). May 1993.]. SHA-1 [National Institute of Standards and Technology (NIST). Announcement of Weakness in the Secure Hash Standard. May 1994.] was a revision to SHA that was published in 1994. The revision corrected an unpublished flaw in SHA.

SHA1 is a cryptographic message digest algorithmdeveloped by Ronald L. Rivest .The Secure Hash Algorithm takes a message of less than 264 bits in length and produces a 160-bit message digest which is designed so that it should be computationally expensive to find a text which matches a given hash. i.e. if you have a hash for document A, H(A), it is difficult to find a document B which has the same hash, and even more difficult to arrange that document B says what you want it to say. Further reading

MD5

MD5 was developed by Ronald L. Rivest of MIT. The MD5 algorithm takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest. The MD5 algorithm is intended for digital signature applications, where a large file must be "compressed" in a secure manner before being encrypted with a private (secret) key under a public-key cryptosystem such as RSA. In essence, MD5 is a way to verify data integrity, and is much more reliable than checksum and many other commonly used methods. Further reading

RIPEMD-160

RIPEMD-160 is a 160-bit cryptographic hash function, designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel. It is intended to be used as a secure replacement for the 128-bit hash functions MD4, MD5, and RIPEMD. MD4 and MD5 were developed by Ron Rivest for RSA Data Security, while RIPEMD was developed in the framework of the EU project RIPE (RACE Integrity Primitives Evaluation, 1988-1992). Further reading


LoadKeyFromString

HashFile

Sub HashFile ( Filename As String, HashType As HASH_METHODS ) As String

The HashFile function computes the hash value of the given file and return it As String.

See HashVariant for available hash methods.

See also: Hashes overview, HashString


LoadKeyFromString

HashVariant

Sub HashVariant ( SourceString As String, HashType As HASH_METHODS ) As String

The HashVariant function computes the hash value of the given variable and return it as a string.

Available hash methods are :

Symbolic name | Numeric value | Description
HASH_SHA1 | 0 | Produces SHA1 hash
HASH_MD5 | 1 | Produces MD5 hash
HASH_RIPEMD160 | 2 | Produces RIPEMD160 hash

See also Hash overview, HashFile


Error

property AC_ERRORS Error

This property has the result of the last operation.

Here you can find all possible values of Error and their short meaning.


CAST5

In RFC 2144 dated May 1997, Carlisle Adams (the CA in CAST, ST standing for Stafford Tavares) describes CAST5 as:

"...a DES-like Substitution-Permutation Network (SPN) cryptosystem which appears to have good resistance to differential cryptanalysis, linear cryptanalysis, and related-key cryptanalysis. This cipher also possesses a number of other desirable cryptographic properties, including avalanche, Strict Avalanche Criterion (SAC), Bit Independence Criterion (BIC), no complementation property, and an absence of weak and semi-weak keys."

CAST5 is a symmetric block cipher with a block-size of 8 bytes and a variable key-size of up to 128 bits. Its authors and their employer (Entrust Technologies, a Nortel majority-owned company) made it available worldwide on a royalty-free basis for commercial and non-commercial uses.

http://www.ietf.org/rfc/rfc2144.txt

IDEA

International Data Encryption Algorithm (IDEA) is a method to encrypt and decrypt data. A key (which must be randomly chosen) is used to encrypt the data, and that same secret key is needed for decrypting the data again.

IDEA is the second version of a block cipher designed by Xuejia Lai and James L. Massey. RSA Security describes it this way:

[IDEA] is a 64-bit iterative block cipher with a 128-bit key. The encryption process requires eight complex rounds. Decryption is carried out in the same manner as encryption once the decryption subkeys have been calculated from the encryption subkeys. The cipher structure was designed to be easily implemented in both software and hardware, and the security of IDEA relies on the use of three incompatible types of arithmetic operations on 16-bit words. However some of the arithmetic operations used in IDEA are not that fast in software. As a result the speed of IDEA in software is similar to that of DES. [2]

RSA Security goes on to say that IDEA was analyzed to measure its strength against differential cryptanalysis. The analysis concluded that IDEA is immune to that technique. In fact, (says RSA Security), there are no linear cryptanalytic attacks on IDEA, and there are no known algebraic weaknesses in IDEA. The only weakness of note was discovered by Daemen [DGV94]: using any of a class of 251 weak keys during encryption results in easy detection and recovery of the key. "However, since there are 2128 possible keys, this result has no impact on the practical security of the cipher for encryption provided the encryption keys are chosen at random. IDEA is generally considered to be a very secure cipher and both the cipher development and its theoretical basis have been openly and widely discussed." [ibid.]

IDEA encryption is somewhat faster and generally considered to be more secure than DES encryption. But IDEA is newer and therefore has not been as extensively tested, and it is patented which restricts its commercial use. The patent will expire in 2011.

Blowfish

Blowfish is a symmetric, secret key, block cipher designed in 1993 by Bruce Schneier. There is an official Blowfish website.

Blowfish has a 64 bit block size and a key length of anywhere from 32 bits to 448 bits. It is based on Schneier's idea that good security against both known and future cryptanalysis can hopefully be obtained by using large, pseudo-random, key dependent s-boxes.

It is one of the faster block ciphers in widespread use, except for changing keys. Each new key requires pre-processing equivalent to encrypting about 4 kilobytes of text, which is very slow compared to other block ciphers. This prevents its use in certain applications, but is not a problem in others.

Also, Blowfish has a relatively large memory footprint of just over 4 kilobytes of RAM. This is not a problem even for older smaller desktop and laptop computers, but it does prevent use in the smallest embedded systems such as smartcards.

There is no effective cryptanalysis of Blowfish known publicly as of Sept. 2002. It should be noted that, like other block cyphers with a 64 bit block, it is risky to encrypt extremely large texts (more than a few hundred megabytes) with a single key. If more data is to be encrypted a block cipher with a larger block size should be used.

Within the limitations noted, Blowfish is a very useful and respected cipher and has seen widespread application.

AES

The Advanced Encryption Standard, more commonly referred to as AES, is a block cipher with a block size of 128 bits and key sizes of 128, 192, and 256 bits. It was adopted by NIST as US FIPS PUB 197 in November 2001 after a 5-year standardisation process.

AES was developed by two Belgian cryptographers, Joan Daemen and Vincent Rijmen. It is also known by the name in the original submission "Rijndael", something best pronounced as "Rine dahl" with a long "i" and a silent "e" for those that don't speak Dutch. Strictly speaking AES is not precisely the same as Rijndael, because Rijndael supports larger block sizes (as requested in NIST's invitation to submit algorithms?)whereas AES has a fixed block size of 128 bits.

AES is fast in both software and hardware, is relatively easy to implement, and requires little memory. As the new block cipher standard it is currently being deployed on a large scale. Further reading

RC4

RC4 is a symmetric, secret key, stream cryptographic cipher designed by Ron Rivest. RC apparently stands for "Ron's Code". Also publicly known are the block ciphers RC2 and RC5. RC4 was initially a trade secret, but in September of 1994 an anonymous person reverse engineered it and posted it to the Cypherpunks mailing list. It quickly spread to Usenet on the sci.crypt newsgroup, and on to many sites on the Internet. Because the algorithm is known, it is no longer a trade secret. The name RC4 is trademarked. The current status seems to be that "unofficial" implementations are legal, but can't use the RC4 name. RC4 is often referred to as "ARCFOUR", to avoid possible trademark problems. It has become part of some commonly used encryption protocols and standards, including SSL, that is used for secure network web browsers.

RC4 is initialised from a secret key. Then it generates a "keystream" which is simply XORd with the plaintext to produce the ciphertext. Decryption is exactly the same as encryption. One reason for its popularity is its simplicity. The algorithm can be memorized and quickly implemented from memory. It uses 256 bytes of memory, S[0] through S[255], and it uses integer variables, i, j, and k. A message is encrypted or decrypted with this algorithm:

for i = 0...255
S[i]=i
for i = 0...255
j=(j+S[i]+key[i mod key_length]) mod 256
swap S[i] and S[j]
i=0
j=0
loop until the entire message is encrypted/decrypted
i=(i+1) mod 256
j=(j+S[i]) mod 256
swap S[i] and S[j]
k=S[(S[i]+S[j]) mod 256]
output the XOR of k with the next byte of input

RC4 is one of the fastest ciphers to be widely used for serious work.

Cryptanalysis of RC4 is at a rather uncertain stage. Theoretical breaks may be possible if gigabytes of known plaintext/known ciphertext stream are available, but this is not necessarily a major problem in practice. In 2001 a new and surprising discovery was made: over all possible RC4 keys, the statistics for the first byte of output keystream are seriously non-random. It remains to be seen if this is an academic curiousity, or a sign of more serious problems to be discovered soon. Current implementations often discard the first 256 bytes of the stream to avoid potential problems.

As with all stream ciphers, RC4 is easily broken if the same key is used twice. This problem is usually solved by hashing the key with a unique initialization vector (IV) each time it is used, and sending the IV along with the message.

RC5

RC5 is a fast block cipher designed by Ronald Rivest for RSA Data Security (now RSA Security) in 1994. It is a parameterized algorithm with a variable block size, a variable key size, and a variable number of rounds. Allowable choices for the block size are 32 bits (for experimentation and evaluation purposes only), 64 bits (for use a drop-in replacement for DES), and 128 bits. The number of rounds can range from 0 to 255, while the key can range from 0 bits to 2040 bits in size. Such built-in variability provides flexibility at all levels of security and efficiency.

There are three routines in RC5: key expansion, encryption, and decryption. In the key-expansion routine, the user-provided secret key is expanded to fill a key table whose size depends on the number of rounds. The key table is then used in both encryption and decryption. The encryption routine consists of three primitive operations: integer addition, bitwise XOR, and variable rotation. The exceptional simplicity of RC5 makes it easy to implement and analyze. Indeed, like the RSA system, the encryption steps of RC5 can be written on the "back of an envelope". The heavy use of data-dependent rotations and the mixture of different operations provide the security of RC5.

RSA

RSA is an asymmetric algorithm for public key cryptography. Credit for its development is given to Ron Rivest, Adi Shamir and Len Adleman, who described the algorithm in 1977, the letters RSA being the initials of their surnames.

The security of the RSA system relies on the difficulty of factoring very large numbers. RSA is widely used in electronic commerce.

It should be noted that Clifford Cocks, a British mathematician working for GCHQ, developed an equivalent system several years earlier. His discovery, however, was not revealed until much later due to its top-secret nature.

The algorithm was patented by MIT in 1983 in the United States of America. The patent expired in September 2000. Since the algorithm had been published prior to the patent application, it could not be patented in other countries.


DecryptFile

Sub DecryptFile ( InputFile As String, OutputFile As String, Method As ENCRYPTION_METHODS, [Password As Variant]) As Boolean

The is function provides common way for decryption of files encrypted with different encryption algorithms. InputFile contains the source file name, OutputFile resulting file. Method defines encryption method. See EncryptVariant for available methods.

If the function fails the return value is False and the Error property contains the error code. Analyzing this property you can find the reason of the failure. If you want to decrypt single values you should use DecryptVariant function.


DecryptVariant

Sub DecryptVariant ( InputString As String, Method As ENCRYPTION_METHODS, Password As Variant) As Variant

This function provides common way for decryption of files encrypted with different encryption algorithms. InputFile contains the source file name, OutputFile resulting file. Method defines encryption method. See EncryptVariant for available methods.

If you use ENC_RSA method you should pass handle of the loaded key in the Password parameter. You can load a key with LoadKey function.

If an error happens, the return value is false and the Error property component contains the error code. Analyzing this property you can find the reason of the failure. If you want to decrypt filesyou should use DecryptFile function.


EncryptFile

Sub EncryptFile ( InputFile As String, OutputFile As String, Method As ENCRYPTION_METHODS, Password As Variant) As Boolean

This function provides common way for encryption of files with different encryption algorithms. InputFile contains the source file name, OutputFile resulting file. Method defines encryption method. See EncryptVariant for available encryption methods.

If you use ENC_RSA method you should pass handle of the loaded key in the Password parameter. You can load a key with LoadKey function.

If an error happens, the return value is False and the Error property contains the error code. Analyzing this property you can find the reason of the failure. If you want to encrypt single value you should use EncryptVariant function.


EncryptVariant

Sub EncryptVariant ( InputVariant As Variant, Method As ENCRYPTION_METHODS, Password As Variant ) As String

This function provides common way for encryption of variants with different encryption algorithms. Method defines encryption method. Currently Method can be one of the following:

Symbolic name | Numeric value | Description
ENC_AES | 0 | Advanced encryption standard
ENC_RC4 | 1 | RC4 by Ron Rivest
ENC_RC5 | 2 | RC5 by Ron Rivest.
ENC_RSA | 3 | RSA is an asymmetric algorithm for public key cryptography.
ENC_IDEA | 4 | International Data Encryption Algorithm
ENC_CAST5 | 5 | CAST5 accordingly to RFC 2144
ENC_BLOWFISH | 6 | Blowfish encryption
ENC_DES3 | 7 | Tripple DES
ENC_DESX | 8 | DESX ( a strengthened variant of DES)

If you use ENC_RSA method you should pass handle of the loaded key in the Password parameter. You can load a key with LoadKey function.

If the function fails the return value is False and the Error property contains the error code . Analyzing this property you can find the reason of the failure. If you want to encrypt files you should use EncryptFile function.


FreeKey

Sub FreeKey ( Key As Variant )

This function is used to free keys, public or private, allocated previously with GenerateCouple or LoadKey functions.


LoadKeyFromString

Sub LoadKeyFromString ( KeyString As String [, Password As String] ) As Variant

The LoadKeyFromString function loads public or private keys from a string. When the password value is given , the string is supposed to hold a private key. You cannot load the public key with a password and cannot load the private key without one. If a key is successfully loaded, the return value is not equal to 0. If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


LoadKey

Sub LoadKey ( Filename As String [, Password As String] ) As Variant

The LoadKey function loads public or private keys from a file into memory. The file path can be an absolute or relative path or a network drive. When the password value is given the file is supposed to hold a private key. You cannot load the public key with a password and cannot load the private key without one. If a key is successfully loaded the return value is not equal to 0. If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


AddCRLF

Property AddCRLF As Boolean

This property defines if encoding engine needs to add new line feed to encrypted output or not. This property affects only on Variant encryption/signing functions. By the existing standard it's required that string encoded by base64 algorithms contained new line characters. However many developers finds it uncomfortable when string has non printable characters. By the default this value is set to False, this means resulting string will have no new line characters, if you need them set property to True.


FreeKey

KeySize

Property KeySize as Integer

This property defines the key size that applied to symmetric encryption in bits. This keys does not affect RSA or AES encryption/decryption functions, they have their own ways of defining the size of the key. This is not a length of the password, it's a length of the key that created internally based upon the password.

Default value is 128, that means that 128 bit key will be created and used for encryption/decryption procedures. For example VISA cardholder requirements demands TrippleDES encryption with minimum 768 bit key. This means that before using TrippleDES encryptionyou should set this property to 768.


Base64 overview

Base64 encoding overview

The MIME (Multipurpose Internet Mail Extensions) specification (RFC 1341 and successors) defines a mechanism for encoding arbitrary binary information for transmission by electronic mail. Triplets of 8-bit octets are encoded as groups of four characters, each representing 6 bits of the source 24 bits. Only characters present in all variants of ASCII and EBCDIC are used, avoiding incompatibilities in other forms of encoding such as uuencode/uudecode

ActiveCrypt provides base64 encoding for string and files.


LoadKey

DecodeFile

Sub DecodeFile ( InputFile As String , OutputFile As String ) As Boolean

The DecodeFile function decodes InputFile into Base64 format and saves it in the OutputFile. Decoding is compatible to RFC 2045. If the function fails the return value is False and the Error property contains the error code. Analyzing this property you can find the reason of the failure. If you want to decode single values you should use DecodeVariant function.

See also Base64 overview, EncodeFile


DecodeVariant

Sub DecodeVariant ( SourceString As String ) As Variant

The DecodeVariant function decode data encoded with BASE64 algorithm and returns data As Variant. If an error happens the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.

See also Base64 overview, EncodeVariant


EncodeFile

Sub EncodeFile ( InputFile As String, OutputFile As String) As Boolean

The EncodeFile function encodes InputFile into Base64 format and saves it in the OutputFile. Encoding is compatible to RFC 2045.InputFile contains the source file name, OutputFile resulting file. If the function fails the return value is False and the Error property contains the error code. If you want to encode single strings.you should use EncodeVariant function.


EncodeVariant

Sub EncodeVariant ( SourceData As Variant ) As String

The EncodeVariant function encodes the SourceData data into Base64 format. Encoding is compatible to RFC 2045. if an error happens the Error property differs from ERR_OK. Analyzing this property you can find the reason of the failure. If you want to encode the whole file you should better use EncodeFile function.


Error

AC_ERRORS Error

This property has the result of the last operation.

Here you can find all possible values of Error and their short meaning.


Digital signatures overview

Authentication is any process through which one proves and verifies certain information. Sometimes one may want to verify the origin of a document, the identity of the sender, the time and date a document was sent and/or signed, the identity of a computer or user, and so on. A digital signature is a cryptographic means through which many of these may be verified. The digital signature of a document is a piece of information based on both the document and the signer's private key. It is typically created through the use of a hash function and a private signing function (encrypting with the signer's private key), but there are other methods.

Every day, people sign their names to letters, credit card receipts, and other documents, demonstrating they are in agreement with the contents. That is, they authenticate that they are in fact the sender or originator of the item. This allows others to verify that a particular message did indeed originate from the signer. However, this is not foolproof, since people can 'lift' signatures off one document and place them on another, thereby creating fraudulent documents. Written signatures are also vulnerable to forgery because it is possible to reproduce a signature on other documents as well as to alter documents after they have been signed.

Digital signatures and hand-written signatures both rely on the fact that it is very hard to find two people with the same signature. People use public-key cryptography to compute digital signatures by associating something unique with each person. When public-key cryptography is used to encrypt a message, the sender encrypts the message with the public key of the intended recipient. When public-key cryptography is used to calculate a digital signature, the sender encrypts the "digital fingerprint" of the document with his or her own private key. Anyone with access to the public key of the signer may verify the signature.

Suppose Alice wants to send a signed document or message to Bob. The first step is generally to apply a hash function to the message, creating what is called a message digest. The message digest is usually considerably shorter than the original message. In fact, the job of the hash function is to take a message of arbitrary length and shrink it down to a fixed length. To create a digital signature, one usually signs (encrypts) the message digest as opposed to the message itself. This saves a considerable amount of time, though it does create a slight insecurity (addressed below). Alice sends Bob the encrypted message digest and the message, which she may or may not encrypt. In order for Bob to authenticate the signature he must apply the same hash function as Alice to the message she sent him, decrypt the encrypted message digest using Alice's public key and compare the two. If the two are the same he has successfully authenticated the signature. If the two do not match there are a few possible explanations. Either someone is trying to impersonate Alice, the message itself has been altered since Alice signed it or an error occurred during transmission.

There is a potential problem with this type of digital signature. Alice not only signed the message she intended to but also signed all other messages that happen to hash to the same message digest. When two messages hash to the same message digest it is called a collision; the collision-free properties of hash functions are a necessary security requirement for most digital signature schemes. A hash function is secure if it is very time consuming, if at all possible, to figure out the original message given its digest. However, there is an attack called the birthday attack that relies on the fact that it is easier to find two messages that hash to the same value than to find a message that hashes to a particular value. Its name arises from the fact that for a group of 23 or more people the probability that two or more people share the same birthday is better than 50%.

In addition, someone could pretend to be Alice and sign documents with a key pair he claims is Alice's. To avoid scenarios such as this, there are digital documents called certificates that associate a person with a specific public key.

Digital timestamps may be used in connection with digital signatures to bind a document to a particular time of origin. It is not sufficient to just note the date in the message, since dates on computers can be easily manipulated. It is better that timestamping is done by someone everyone trusts, such as a certifying authority. There have been proposals suggesting the inclusion of some unpredictable information in the message such as the exact closing share price of a number of stocks; this information should prove that the message was created after a certain point in time.


LoadKeyFromString

MakeVariantSignature

Sub MakeVariantSignature ( SourceData As Variant, SignMethod As SIGN_METHODS, Key As Variant [, Password As String] ) As String

The MakeVariantSignature function uniquely signs the content of the variant with the private key. Key must be valid loaded private key. SignMethod can be one of the following:

Symbolic value | Numeric value | Description
SIGN_RSAMD5 | 0 | Performs MD5-RSA signature method
SIGN_RSASHA1 | 1 | Performs SHA1-RSA signature method

Parameter Password is currently ignored and reserved for future use.

If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


LoadKeyFromString

MakeFileSignature

Sub MakeFileSignature ( Filename As String, SignMethod As SIGN_METHODS, Key As Variant [, PasswordAs String ) As String

The MakeFileSignature function uniquely signs the content of the variant with the private key. Key must be valid loaded private key.Available values for SignMethod parameter see here.

Parameter Password is currently ignored and reserved for future use.

If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


LoadKeyFromString

VerifyFileSignature

Sub VerifyFileSignature ( Filename As String, SignMethod As SIGN_METHODS, Sign As String, Key As Variant) As Boolean

VerifyFileSignature function checks the content of the file and given signature. It identify if this content was really signed by the MakeFileSignature function and valid private key. Key parameter must be valid loaded public key and corresponds to the private key used for signing. Available values for SignMethod parameter see here.

If the sign is correct the return value is True and False otherwise.

If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


LoadKeyFromString

VerifyVariantSignature

Sub VerifyVariantSignature ( SourceString As String, SignMethod As SIGN_METHODS, Sign As String, Key As Variant) As Boolean

VerifyVariantSignature function checks the content of the variant and given signature. It identify if this content was really signed by the MakeVariantSignature function and valid private key. Key parameter must be valid loaded public key and corresponds to the private key used for signing.Available values for SignMethod parameter see here.

If the sign is correct the return value is True and False otherwise.

If an error happens, the return value is 0 and the Error property of the ActiveCrypt component differs from ERR_OK. Analyzing this property you can find the reason of the failure.


GenerateCouple

Sub GenerateCouple (Size As Long, PrivateKey As Variant, PublicKey As Variant [,Cookie As Long])

The GenerateCouple function is used to generate a new couple of private and public keys with a given bit length. In synchronous mode after the execution is succeeded PrivateKey and PublicKey variables are not equal to 0. In the case of an error Error property has an actual error code and OnError event is fired.

This function runs asynchronously in asynchronous mode. Thus, in this mode the function returns immediately and when it is completed, OnGenerationKeyFinished event is fired. If an error happens the OnError event is fired.

To see the example of usage please see How to generate keys


GeneratePublicKey

Sub GeneratePublicKey ( PrivateKey As Long ) As Variant

This function is used when it is needed to generate public key using a private key. Function accepts the private key and returns the public key. Public key should be explicitly freed by user when it is not needed. For generation of a new pair of keys see GenerateCouple function.

If an error happens theError property of ActiveCrypt contains the error code. For information about the error code, please see Error property. If the function succeeds the Error contains the value of ERR_OK.


GetVersion

Sub GetVersion(ByRef MajorVersion As Variant, ByRef MinorVersion As Variant)

This function returns you a minor and major versions of the ActiveCrypt.


PublicEncrypt

Sub PublicEncrypt ( PublicKey As Long, ClearText As String, [Cookie As Long] ) As String

In the synchronous mode the PublicEncrypt function encrypts given string with a public key and returns encrypted string. In the asynchronous mode, the function returns empty string immediately and spawns encryption internally. After encryption is done, OnEncryptionFinished is fired. For more information about encryption in the asynchronous mode please see Async mode.

If an error happens the Error property of ActiveCrypt contains the error code. For information about the error code, please see Error property. If the function is succeeded the Error has value of ERR_OK.


PrivateDecrypt

Sub PrivateDecrypt ( PrivateKey As Long, ClearText As String [, Cookie As Long] ) As String

In the synchronous mode the PrivateDecrypt function decrypts given encrypted string with a private key and returns decrypted string. In the asynchronous mode, the function returns empty string immediately and spawns decryption internally. After the decryption is done, OnDecryptionFinished is fired. For more information about decryption in the asynchronous mode please see Async mode.

If an error happens theError property of ActiveCrypt contains the error code. For information about an error code, please see Error property. If the function succeeds the Error contains the value of ERR_OK.


SaveKeyToString

Sub SaveKeyToString ( Key As Long [, Password As String]) As String

The SaveKeyToString function saves public or private keys from memory into string. Public keys are stored without a password unlike private keys. The private key MUST be stored with a password. The password should be longer than 4 chars. After saving, the key still remains valid.

Here is an example :

        Dim Privatekey As Variant, Publickey As Variant
        Dim PrivateKeyString As String
        Dim PublicKeyString As String
        ...
        Set ActiveCryptObject = newActiveCryptLib.RSACrypt
        ActiveCryptObject.GenerateCouple 256, PrivateKey, PublicKey
        ...
        PrivateKeyString = ActiveCryptObject.SaveKey (PrivateKey, "SecurePassword")
        PublicKeyString = ActiveCryptObject.SaveKey (PublicKey)
        ActiveCryptObject.FreeKey PrivateKey
        ActiveCryptObject.FreeKey PublicKey
        ' We must save strings PrivateKeyString, PublicKeyString to some persistent storage ( for example: registry or database )


SaveKey

Sub SaveKey ( Key As Variant, FilenameAs String [, Password As String])

The SaveKey function saves public or private keys from memory into file. Public keys are stored without a password unlike private keys. The private key MUST be stored with a password. The password should be longer than 4 chars. After saving, the key still remains valid.

Here is an example :

        Dim PrivateKey As Variant, PublicKey As Variant
        ...
        Set ActiveCryptObject = new ActiveCryptLib.RSACrypt
        ActiveCryptObject.GenerateCouple 256, PrivateKey, PublicKey
        ...
        ActiveCryptObject.SaveKey PrivateKey, "privatekey.pem", "SecurePassword"
        ActiveCryptObject.SaveKey PublicKey, "publickey.pem"
        ActiveCryptObject.FreeKey PrivateKey
        ActiveCryptObject.FreeKey PublicKey


About

Sub About () As String

This function provides some important information about the author.


Async

property boolean Async

It is a special property of ActiveCrypt component that lets you execute long running operations in the background thread. The functions that benefit from Asynchronous mode are : GenerateCouple, PublicEncrypt, PrivateDecrypt. By default that property is set to FALSE. This means that your program will wait for a request to be completed by ActiveCrypt component. This is quite an easy mode and it is enough for the successful functioning of the program. Bun in this case the program will be blocked during data procession. If you need to process large amounts of data simultaneously without blocking you should choose the asynchronous mode.

To turn the the asynchronous mode you need to set the property to TRUE. Since that, the functionsGenerateCouple, PublicEncrypt, PrivateDecrypt return immediately invalid keys or empty strings. And after the work of those functions is completed successfully they fire the following events: OnKeyGenerationFinished, OnEncryptionFinished, OnDecryptionFinished respectively or OnError in the case of an error.

In order to handle data in events correctly and define what this data refers to, a special cookie ID should be added to GenerateCouple, PublicEncrypt, PrivateDecrypt. You can omit them in the synchronous mode, but in the asynchronous mode they are quite useful. The following example demonstrates how to take advantage of asynchronous encryption and use cookies.

Example:

        Dim WithEvents ActiveCryptObject As ActiveCryptLib.RSACrypt
        'do not forget to specify WithEvents keyword, otherwise, it will not get any events at all
        Dim PrivateKey As Variant
        Dim PublicKey As Variant

        Private Sub ActiveCryptObject_OnDecryptionFinished(ByVal Cookie As Long, ByVal DecryptedText As String)
                'do with DecryptedText what you want, or just put it in a ListBox ;)
                List1.AddItem Str(Cookie)+" "+DecryptedText
        End Sub

        Private Sub ActiveCryptObject_OnEncryptionFinished(ByVal Cookie As Long, ByVal CryptedText As String)
                ActiveCryptObject.PrivateDecrypt PrivateKey, CryptedText, Cookie
        End Sub

        Private Sub ActiveCryptObject_OnError(ByVal Cookie As Long, ByVal ErrorNumber As Long, ByVal ErrorMsg As String)
                List1.AddItem "Error: "+ErrorMsg
        EndSub

        Private Sub Command1_Click()
                ActiveCryptObject.Async =True
                ' let's say here we open some looooong file and read 20000
                ' records into ClearData string and then encrypt it in the asyncronous mode
                For  i = 0 To20000
                        'read into ClearData
                        ActiveCryptObject.PublicEncrypt, PublicKey, ClearData, i
                Next i
                'the program goes further ....
        End Sub


Error

property AC_ERRORS Error

In the synchronous mode this field holds the result of the last function.In the asynchronous mode this field has actual value only for functions executed synchronously. For functions that can be executed asynchronously the result is always set to ERR_OK. To get a result of asynchronous functions you must use events. The OnError event is fired in both modes. And its up to developer do define what style of error detection to choose - OnError or examining the Error property. If you do not use the asynchronous feature it is better to check Error property after each function.

Here you can find all possible values of Error and their short meaning.


OnDecryptionFinished

event OnDecryptionFinished ( ByVal Cookie As Long, ByVal DecryptedText As String )

This event is fired in an asynchronous mode when the processing of the decryption is finished. For example see using Async mode.


OnEncryptionFinished

event OnEncryptionFinished ( ByVal Cookie As Long, ByVal EncryptedText As String )

This event is fired in an asynchronous mode when the processing of the decryption is finished. For example see using Async mode.


OnError

event OnError ( ByVal Cookie As Long, ByVal ErrorNumber As Long, ByVal ErrorMsg As String )

This event appears when an error happens both in synchronous and asynchronous modes. A cookie contains anidentificator given to the function which caused the error. Error constant, its numeric value and ErrorMsg have the following values:

ERR_OK | 0 | No error.
ERR_INVSIZE | 101 | Invalid key size.
ERR_RSAGENERR | 102 | Error generating RSA key.
ERR_UNKNRSAGEN | 103 | Uknown error while generating pair.
ERR_BIOERR | 104 | BIO error.
ERR_PUBENCERR | 105 | Public encrypt error.
ERR_CANTOPENFILE | 106 | Cannot open file.
ERR_UNKNLOADKEYERR | 107 | Unknown error while loading key.
ERR_UNKNSAVEKEYERR | 108 | Unknown error while saving key.
ERR_ERRWRITINGTOFILE | 109 | Error writing to file.
ERR_ERRCREATINGFILE | 110 | Error creating file.
ERR_ERRWRITINGPRKEY | 111 | Error writing private key.
ERR_DECRYPTERR | 112 | Decrypt error.
ERR_ERRREADINGFILE | 113 | Error reading file.
ERR_ERRGETFILESIZE | 114 | Error getting file size.
ERR_ERRREADINGKEY | 115 | Error reading key from file.
ERR_UNKNDECRYPTERR | 116 | Unknown error while decrypting text.
ERR_BADPRIVATEKEY | 117 | Bad private key.
ERR_BADPUBLICKEY | 118 | Bad public key.
ERR_BADKEY | 119 | Bad key.
ERR_UNKNGENPUB | 120 | Unknown error generating public key.
ERR_ERRGENPUBKEY | 121 | Error generating public key.
ERR_SWLIMIT | 122 | Shareware limitation.
ERR_UNKNENC | 123 | Unknown error while encryption.
ERR_ERRREADINGKEYSTR | 124 | Error reading key from string.

You can edit messagesby editing resources of activecrypt.dll


OnKeyGenerationFinished

event OnKeyGenerationFinished ( ByVal Cookie As Long, ByVal PrivateKey As Variant, ByVal PublicKey As Variant )

This event is fired in an asynchronous mode when the successful generation of keys started with GenerateCouple is finished. Cookie is an idenficator passed to GenerateCouple. PrivateKey and PublicKey have the valid keys which must be explicitly freed when they are not needed.


Legal notice

Disclaimer

THIS SOFTWARE IS PROVIDED BY ActiveCrypt Software ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.


List of possible error values and thier's meaning

ERR_OK | 0 | No error.
ERR_INVSIZE | 101 | Invalid key size.
ERR_RSAGENERR | 102 | Error generating RSA key.
ERR_UNKNRSAGEN | 103 | Unknown error while generating pair.
ERR_BIOERR | 104 | BIO error.
ERR_PUBENCERR | 105 | Public encrypt error.
ERR_CANTOPENFILE | 106 | Can not open file.
ERR_UNKNLOADKEYERR | 107 | Unknown error while loading key.
ERR_UNKNSAVEKEYERR | 108 | Unknown error while saving key.
ERR_ERRWRITINGTOFILE | 109 | Error writing to file.
ERR_ERRCREATINGFILE | 110 | Error creating file.
ERR_ERRWRITINGPRKEY | 111 | Error writing private key.
ERR_DECRYPTERR | 112 | Decrypt error.
ERR_ERRREADINGFILE | 113 | Error reading file.
ERR_ERRGETFILESIZE | 114 | Error getting file size.
ERR_ERRREADINGKEY | 115 | Error reading key from file.
ERR_UNKNDECRYPTERR | 116 | Unknown error while decrypting text.
ERR_BADPRIVATEKEY | 117 | Bad private key.
ERR_BADPUBLICKEY | 118 | Bad public key.
ERR_BADKEY | 119 | Bad key.
ERR_UNKNGENPUB | 120 | Unknown error generating public key.
ERR_ERRGENPUBKEY | 121 | Error generating public key.
ERR_SWLIMIT | 122 | Shareware limitation.
ERR_UNKNENC | 123 | Unknown error while encryption.
ERR_ERRREADINGKEYSTR | 124 | Error reading key from string.
ERR_SYMMENCERR | 125 | Symmetric encryption error.
ERR_UNKNMETHOD | 126 | Unknown method.
ERR_BADSRC | 127 | Malformed input
ERR_B64DEC | 128 | Base64 decode error
ERR_B64ENC | 129 | Base64 encode error
ERR_KEYTOOSHORT | 130 | Key is too short
ERR_SIGN | 131 | Sign creation error
ERR_VERIFY | 132 | Sign verify error


ActiveCRYPT 2.3 - Online manual.

This page uses frames, but your browser doesn't support them.


Load keys

How to load keys.

Loading of a key is an operation of loading of a file (or from string) with a key into memory. Private keys need a password, public keys do not. Private or public keys can be loaded with LoadKey or LoadKeyFromString function. This operation usually takes place at the beginning of encryption / decryption. At the end of work the key should be explicitly freed with the FreeKey function. To load the private key, you should specify a password, otherwise the function will fail with ERR_ERRREADINGKEY.

Keeping the private key on server does not make a big security risk, since the current technology level makes it impossible to produce a private key within reasonable period of time. Private keys are stored with a password. The longer is the password, the more time it is needed to bruteforce it.


Overview of How to

How to ...

In this "How to section" you can find the samples of all tasks which ActiveCrypt is able to do. The samples are written with Visual Basic, but you are free to choose another language.