1. Download the demonstration 24-bit DLL.
2. Copy the DLL file into a directory that is outside any web root. This is so it cannot be easily overwritten or tampered with by any hacker.
   C:\WINNT\SYSTEM32 is a good choice for Windows NT machines.
3. Run the command:
   regsvr32 kivco.dll
   from the directory where you have copied the DLL.
4. Generate a pair of private and public keys.
5. Encode using the public key and decode using the private key.
6. Visit http://www.kivco.com/securitydoc.html for documentation and ASP examples for the kivco.dll COM module.

GenKeys

VBScript Prototype:
Function GenKeys(ByVal len As Long, ByVal random as String) As String

Purpose:
Generate a public/private key pair for use with public-key encryption.

Description:
len is the number of bits for the key, demo version requires 24 bits exactly.
random is a random string to help to randomize the key generating process.
The function returns three variables in URL format. You can parse the return string, or use the property get functions, Public, Private, N (which is recommended.)

Example Usage:
Str = someVar.GenKeys( 24, "This is a random string to randomize the generator." )

Example Return Value:
public=65537& private=95884630368273& n=135369597837451

Encrypt

VBScript Prototype:
Function Encrypt(ByVal msg As String, ByVal random As String, ByVal key as String, byVal n As String) As String

Purpose:
Encodes a message using either the public or private key from the pair.

Description:
msg is the input string that will be encoded.
random is any string that helps perturb the encryption.
key is the private or public key generated by GenKeys.
n is the modulo generated by GenKeys (the variable N.)
The return value is a string of cipher text which can only be recovered with Decrypt.

Example Usage:
Str = someVar.Encrypt( "This is my message.", "random stuff", "65537", "135369597837451" )

Example Return Value:
157e7d228ea59494b7d83578e509 9026b4029581626054cf3 15be4af0be511ad330aebbbc

Decrypt

VBScript Prototype:
Function Decrypt(ByVal cipher As String, ByVal key as String, byVal n As String) As String

Purpose:
Decodes a cipher text string generated by Encrypt using the complimenting private or public key from the pair.

Description:
cipher is the input cipher text string obtained from a call to Encrypt that will be decoded.
key is the complementing private or public key generated by GenKeys. If you encoded using the private key, you decode with the public key and if you encoded using the public key, you decode with the private key.
n is the modulo generated by GenKeys (the variable N.)
The return value is the original string prior to encoding with Encrypt.

Example Usage:
Str = someVar.Decrypt( "157e7d228ea59494b7d83578e509 9026b4029581626054cf3 15be4af0be511ad330aebbbc", "95884630368273", "135369597837451" )

Example Return Value:
This is my message.

PublicKey

Purpose:
Returns the public key generated by the last call to GenKeys or EasyKeys, incidentally the public key is always 65537.

Description:
The return value is the last generated public key from GenKeys or EasyKeys.

Example Usage:
Str = someVar.PublicKey

Example Return Value:
65537

PrivateKey

Purpose:
Returns the private key generated by the last call to GenKeys or EasyKeys. When calling GenKeys, the private key is returned as a number in a string variable. When calling EasyKeys, the private key is returned encrypted in a string variable.

Description:
The return value is the last generated private key from GenKeys or encrypted private key from EasyKeys.

Example Usage:
Str = someVar.PrivateKey

Example Return Value From GenKeys:
95884630368273

Example Return Value From EasyKeys:
76ce4c03f6c5d859x26ef747d3b4142e2x79fc5066b2290d2c

N

Purpose:
Returns the N modulus generated by the last call to GenKeys or EasyKeys. The N modulus is a number that is related to the public and private keys and does not need to be kept private.

Description:
The return value is the last generated N modulus from GenKeys or EasyKeys.

Example Usage:
Str = someVar.N

Example Return Value:
135369597837451

Mask

VBScript Prototype:
Function Mask(ByVal msg as String, ByVal password as String, ByVal random as String) As String

Purpose:
Return an encrypted string using the same password to encode (Mask) and decode (UnMask).

Description:
msg is the message you wish to encode.
password is the password that will be needed to decode the resulting encoded string.
random is any string that helps perturb the encryption.
The return value is the encoded string, the same password is required to decode the string.

Example Usage:
Str = someVar.Mask("hi there", "This is my password", "this is a random string.")

Example Return Value:
91f0c5e08308dd86x96a390163f8061a0

UnMask

VBScript Prototype:
Function Mask(ByVal mask as String, ByVal password as String) As String

Purpose:
Recovers the original message from an encrypted string using the same password used to encode (Mask) the original string.

Description:
mask is the message you wish to decode.
password is the password that was used to encode the original message.
The return value is the original string provided to Mask, the same password is required from when the string was encoded (Mask'ed).

Example Usage:
Str = someVar.UnMask("91f0c5e08308dd86x96a390163f8061a0", "This is my password")

Example Return Value:
hi there

EasyKeys

VBScript Prototype:
Function EasyKeys(ByVal password as String, ByVal random as String) As String

Purpose:
Part of the simplified interface for encrypting information (EasyKeys, EasyEncrypt, EasyDecrypt). Generates a public and private key pair. The private key is automatically encoded using the supplied password. Use the property PrivateKey, PublicKey, and N functions to get the resultant keys and N modulo numbers.

Description:
password is the password that is used to encode the private key.
random is used to randomize the key generator and to perturb the encoding of the private key.
The function returns nothing. Use the property PrivateKey, PublicKey, and N functions to get the resultant keys and N modulo numbers.

Example Usage:
someVar.EasyKeys "This is my password", "This is a random string to randomize the generator."
Pub = someVar.PublicKey
Priv = someVar.PrivateKey
N = someVar.N

Example Return Values:
Pub = "65537"
Priv = "ddecd61ad2b68140x e29a3645fd043649x 9102a90421e0fd3ax 92df407e"
N = "208252260534817"

EasyEncrypt

VBScript Prototype:
Function EasyEncrypt(ByVal msg as String, ByVal random as String, ByVal key as String, ByVal n as String) As String

Purpose:
Part of the simplified interface for encrypting information (EasyKeys, EasyEncrypt, EasyDecrypt). This function actually behaves exactly like Encrypt, except that you can only use the public key -- you cannot use the private key, since it is encrypted.

EasyDecrypt

VBScript Prototype:
Function EasyDecrypt(ByVal cipher as String, ByVal password as String, ByVal key as String, ByVal n as String) As String

Purpose:
Part of the simplified interface for encrypting information (EasyKeys, EasyEncrypt, EasyDecrypt). This function decrypts a string generated by EasyEncrypt.

Description:
cipher is the encoded text returned by EasyEncrypt.
password is the password that was used when generating the public and private keys with EasyKeys.
cipher is the encoded text returned by EasyEncrypt.
key is the encoded private key generated by EasyKeys.
n is the modulo generated by EasyKeys (the variable N.)

Example Usage:
Str = someVar.EasyDecrypt("1b2b4d1db3baf9733e9ea0ce55d925c413618", "This is my password", "ddecd61ad2b68140x e29a3645fd043649x 9102a90421e0fd3ax 92df407e", "208252260534817")

Example Return Values:
hi there

EasyLongEncrypt

VBScript Prototype:
Function EasyLongEncrypt(ByVal msg as String, ByVal random as String, ByVal key as String, ByVal n as String) As String

Purpose:
Part of the simplified interface for encrypting information (EasyKeys, EasyEncrypt, EasyDecrypt). This function is an extension of EasyEncrypt to accomodate longer strings. This function actually generates a random password and encodes it using the supplied public key, then the message is encrypted using that random password. Both the encrypted random password and encrypted message are returned as a single string. This function operates faster because it is mainly secured by the Mask function.

Description:
msg is a message to be encoded.
random is a random string used to perturb the resultant cipher text.
key is the public key generated by EasyKeys.
n is the modulo generated by EasyKeys (the variable N.)
The return value is an encrypted string which can only be recovered with EasyLongDecrypt.

Example Usage:
Str = someVar.EasyLongEncrypt("this can be a long message.", "This is a random string", "65537", "208252260534817")

Example Return Values:
14708ecaed0003f709bef3bb0_ 5b0c5a31a31d1f4x 188b5e2fc0d7ea97x f53662adebed1a1ex ccc906c9b59707e5x fe4cd0843605ffa1x b4088b70d7b2dbf6

EasyLongDecrypt

VBScript Prototype:
Function EasyLongDecrypt(ByVal long_cipher as String, ByVal password as String, ByVal key as String, ByVal n as String) As String

Purpose:
Part of the simplified interface for encrypting information (EasyKeys, EasyEncrypt, EasyDecrypt). This function is an extension of EasyDecrypt to accomodate longer strings. This function is capable of recovering the original message of an encoded string encrypted by EasyLongEncrypt. For a description of the mechanism, refer to EasyLongEncrypt, above.

Description:
long_cipher is the encoded text returned by EasyLongEncrypt.
password is the password supplied when originally generating the public and private keys with EasyKeys.
key is the encoded private key generated by EasyKeys.
n is the modulo generated by EasyKeys (the variable N.)
The return value is the original message prior to encoding with EasyLongEncrypt.

Example Usage:
Str = someVar.EasyLongDecrypt("14708ecaed0003f709bef3bb0_ 5b0c5a31a31d1f4x 188b5e2fc0d7ea97x f53662adebed1a1ex ccc906c9b59707e5x fe4cd0843605ffa1x b4088b70d7b2dbf6", "This is my password", "ddecd61ad2b68140x e29a3645fd043649x 9102a90421e0fd3ax 92df407e", "208252260534817")

Example Return Values:
this can be a long message.

RandomNumber

VBScript Prototype:
Function RandomNumber(ByVal len As Long, ByVal stream as Long, ByVal random_str as String) As String

Purpose:
Generates a random number using len bits. The random number always has exactly one extra bit -- the greatest value bit -- which is always set. Thus if len is 3, the binary numbers 1000 (8) through 1111 (15) may be generated. If this was not done, it would be impossible to determine the number of generated bits in the number 0, for example.

Description:
len is the number of random bits to generate.
stream the randomizer seed. Choosing a value of 0 will seed the generator according to the system clock in microseconds. Using any other positive integer creates a reproducible random number.
random_str is a random string used to perturb the generated bit pattern. It also affects the stream selection algorithm.
The return value is a hexadecimal number that requires len + 1 bits to describe. Because the number is hexadecimal, and therefore each character represents exactly 4 bits, the bits can be extracted easily.

Example Usage:
Str = someVar.RandomNumber(100, 0, "This is a random string")

Example Return Values:
e0f904c3b306f23fdbee0353c

Walk-Through

Before You Start:

Did you remember to read the install instructions?


How To Use Regular Password Capabilities:

<%
  '
  ' Create a new KivcoRSA Object
  '
  Dim RSA
  Set RSA = Server.CreateObject("Kivco.RSA")

  '
  ' Create a message to encrypt
  '
  Dim message
  message = "This is a secret message"

  '
  ' Our password is secret-password, you can use
  ' variables passed in from a form, for example.
  '
  Dim password
  password = "secret-password"

  '
  ' The random string uses the remote IP and the current
  ' time.  Providing this will make the encryption harder
  ' to break.  Any hard to predict value is useful.
  '
  Dim random_string
  random_string = Request.ServerVariables("REMOTE_ADDR") & Now()

  '
  ' Encrypt our message.
  '
  Dim encryption
  encryption = RSA.Mask(message, password, random_string)

  '
  ' Write the encrypted message to the web page.  You can
  ' do whatever you want with the encrypted message, since
  ' it is just a regular string.
  '
  response.write encryption

  '
  ' Write a new line.
  '
  response.write "<BR>"

  '
  ' Decrypt our message.
  '
  Dim decryption
  decryption = RSA.UnMask(encryption, password)

  '
  ' Write the decrypted message to the web page.  This is
  ' our original message!
  '
  response.write decryption

%>

How To Use The Easy Public-Key Encryption Capabilities:

1. Generate Some Keys:

   You need to generate a set of keys only once. You can then use this set of keys to encrypt and decrypt as many times as desired. It is suggested to generate the keys offline and store the results into a database for easy retrieval.

   Of course, you may generate new keys at any time, but the new keys will not work with any other set of keys previously generated, even if you supply the same password. That is, the key used for decryption must belong to the same set as the key used for encryption.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' Our password is secret-password, you can use
     ' variables passed in from a form, for example.
     '
     Dim password
     password = "secret-password"
   
     '
     ' The random string uses the remote IP and the current
     ' time.  Providing this will make the encryption harder
     ' to break.  Any hard to predict value is useful.
     '
     Dim random_string
     random_string = Request.ServerVariables("REMOTE_ADDR") & Now()
   
     '
     ' Generate Public And Private Keys using the Easy
     ' method.  This password-protects the private key.
     ' When using EasyKeys, you can freely distribute
     ' the private key provided you do not ever distribute
     ' the password.  It is, of course, safer not to
     ' distribute the private key, since there is no need
     ' to do it, and it reduces exposure to risk.
     '
     RSA.EasyKeys password, random_string
     
     '
     ' Get the Public-Key, Private-Key, and the N modulus
     ' We need all this information to encrypt and decrypt
     ' messages.
     '
     Dim PublicKey
     Dim PrivateKey
     Dim N
     PublicKey = RSA.PublicKey
     PrivateKey = RSA.PrivateKey
     N = RSA.N
   
     '
     ' Because we used EasyKeys, the private key is 
     ' password-protected.  It cannot be used without the
     ' same password supplied to EasyKeys used above.  Public
     ' access to the protected-private-key is not high risk, 
     ' but it is suggested to avoid such access.
     '
     ' The public key does not need a password for it to be 
     ' used, it can be freely distributed since it is always
     ' the string "65537".
     '
     ' The N modulus is needed for both encryption and 
     ' decryption.  Public access to the N modulus is not
     ' high risk, but it is suggested to avoid such access,
     ' if appropriate for the application.  It should be noted
     ' that the N modulus is normally distributed in RSA
     ' implementations.
     '
     
     '
     ' Write the Public-Key, Private-Key, and the N modulus to
     ' the web page.  In reality, you will probably store these
     ' keys in a database for easy retrieval when you want to
     ' encrypt and decrypt information.
     '
     Response.Write "pub = " & PublicKey & "<BR>"
     Response.Write "priv = " & PrivateKey & "<BR>"
     Response.Write "N = " & N & "<BR>"
   %>
   

2. Encrypt Something Using The Public Key:

   A typical encryption scenario is the encryption of credit card numbers supplied by a customer. In this case, like virtually all cases, the encryption happens in one web page, and the decryption in a separate web page -- like in an administration page. We use the public key and N modulus that we generated offline in step 1.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' The random string uses the remote IP and the current
     ' time.  Providing this will make the encryption harder
     ' to break.  Any hard to predict value is useful
     '
     Dim random_string
     random_string = Request.ServerVariables("REMOTE_ADDR") & Now()
   
     '
     ' The user has supplied a credit card number from some
     ' previous form.
     '
     Dim creditCardNumber
     creditCardNumber = Request.Form("creditCardNumber")
     
     '
     ' Get the public key and N modulus from some database,
     ' (or wherever)
     '
     Dim cn
     Dim rs
     cn = Server.CreateObject("ADODB.Connection")
     rs = Server.CreateObject("ADODB.RecordSet")
     ...
     Dim PublicKey
     Dim N
     PublicKey = rs("publickey") ' always "65537"
     N = rs("N")
     
     '
     ' Encrypt our message.
     '
     Dim encryption
     encryption = RSA.EasyEncrypt( _
                    creditCardNumber, _
                    random_string, _
                    PublicKey, _
                    N _
                  )
                  
     '
     ' Write the encrypted credit card number to the web page.
     ' In reality, you would store the encrypted credit card
     ' number in a database somewhere.
     '
     response.write encryption
   %>
   

3. Decrypt Something Using The Private Key:

   The administrator or webmaster will eventually want to decrypt the encrypted credit card numbers genererated in step 2. We also use the private key and N modulus that we generated offline in step 1. This decryption would be in a separate web page -- like in an administration page.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' Our password is secret-password, you can use
     ' variables passed in from a form, for example.
     '
     Dim password
     password = "secret-password"
   
     '
     ' Load the encrypted credit card number from some database
     ' somewhere.
     '
     Dim cn
     Dim rs
     cn = Server.CreateObject("ADODB.Connection")
     rs = Server.CreateObject("ADODB.RecordSet")
     ...
     Dim EncryptedCreditCardNumber
     EncryptedCreditCardNumber = rs("encryptedCreditCardNumber")
     
     '
     ' Get the private key and N modulus from some database,
     ' (or wherever)
     '
     ...
     Dim PrivateKey
     Dim N
     PrivateKey = rs("privatekey") ' encrypted private key
     N = rs("N")
     
     '
     ' Decrypt our message.
     '
     Dim message
     message = RSA.EasyDecrypt( _
                    EncryptedcreditCardNumber, _
                    password, _
                    PrivateKey, _
                    N _
                  )
                  
     '
     ' Write the decrypted credit card number to the web page.
     ' The administrator or webmaster can complete the purchase 
     ' now.  The unencrypted credit card number only exists
     ' when it is retrieved, otherwise it is always encrypted.
     '
     response.write message
     
   %>
   

1. Generate Some Keys:

   You need to generate a set of keys only once. You can then use this set of keys to encrypt and decrypt as many times as desired. It is suggested to generate the keys offline and store the results into a database for easy retrieval.

   Of course, you may generate new keys at any time, but the new keys will not work with any other set of keys previously generated. That is, the key used for decryption must belong to the same set as the key used for encryption.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' The random string uses the remote IP and the current
     ' time.  Providing this will make the encryption harder
     ' to break.  Any hard to predict value is useful.
     '
     Dim random_string
     random_string = Request.ServerVariables("REMOTE_ADDR") & Now()
   
     '
     ' Generate Public And Private Keys using the Generic
     ' method.  The keys are not password protected.
     ' When using the GenKeys, you must guard the
     ' the private key from the public.  Do not ever distribute
     ' the private key.  It is, of course, safer not to
     ' store the private key on a server that has direct access
     ' to the internet, since it is always possible that it can
     ' then be stolen.
     '
     RSA.GenKeys 24, random_string ' 24 bits in the demo version
     
     '
     ' Get the Public-Key, Private-Key, and the N modulus
     ' We need all this information to encrypt and decrypt
     ' messages.
     '
     Dim PublicKey
     Dim PrivateKey
     Dim N
     PublicKey = RSA.PublicKey
     PrivateKey = RSA.PrivateKey
     N = RSA.N
   
     '
     ' Because we used GenKeys, the private key is 
     ' unencrypted.  If stolen, it can be used to decrypt any
     ' messages encrypted with the public key generated above.
     '
     ' The public key does not need a password for it to be 
     ' used, it can be freely distributed since it is always
     ' the string "65537".
     '
     ' The N modulus is needed for both encryption and 
     ' decryption.  Public access to the N modulus is not
     ' high risk, but it is suggested to avoid such access,
     ' if appropriate for the application.  It should be noted
     ' that the N modulus is normally distributed in RSA
     ' implementations.
     '
     
     '
     ' Write the Public-Key and the N modulus to
     ' the web page.  In reality, you will probably store these
     ' keys in a database for easy retrieval when you want to
     ' encrypt information.
     '
     Response.Write "pub = " & PublicKey & "<BR>"
     Response.Write "N = " & N & "<BR>"
   
     '
     ' Write the private key down or copy to a secured file.  If
     ' it is stolen, your information can be decoded.
     '
     Response.Write "priv = " & PrivateKey & "<BR>"
   %>
   

2. Encrypt Something Using The Public Key:

   A typical encryption scenario is the encryption of credit card numbers supplied by a customer. In this case, like virtually all cases, the encryption happens in one web page, and the decryption in a separate web page -- like in an administration page. We use the public key and N modulus that we generated offline in step 1.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' The random string uses the remote IP and the current
     ' time.  Providing this will make the encryption harder
     ' to break.  Any hard to predict value is useful.
     '
     Dim random_string
     random_string = Request.ServerVariables("REMOTE_ADDR") & Now()
   
     '
     ' The user has supplied a credit card number from some
     ' previous form.
     '
     Dim creditCardNumber
     creditCardNumber = Request.Form("creditCardNumber")
     
     '
     ' Get the public key and N modulus from some database,
     ' (or wherever)
     '
     Dim cn
     Dim rs
     cn = Server.CreateObject("ADODB.Connection")
     rs = Server.CreateObject("ADODB.RecordSet")
     ...
     Dim PublicKey
     Dim N
     PublicKey = rs("publickey") ' always "65537"
     N = rs("N")
     
     '
     ' Encrypt our message.
     '
     Dim encryption
     encryption = RSA.Encrypt( _
                    creditCardNumber, _
                    random_string, _
                    PublicKey, _
                    N _
                  )
                  
     '
     ' Write the encrypted credit card number to the web page.
     ' In reality, you would store the encrypted credit card
     ' number in a database somewhere.
     '
     response.write encryption
   %>
   

3. Decrypt Something Using The Private Key:

   The administrator or webmaster will eventually want to decrypt the encrypted credit card numbers genererated in step 2. We also use the private key and N modulus that we generated offline in step 1. This decryption would be in a separate web page -- like in an administration page.

   <%
     '
     ' Create a new KivcoRSA Object
     '
     Dim RSA
     Set RSA = Server.CreateObject("Kivco.RSA")
   
     '
     ' Load the encrypted credit card number from some database
     ' somewhere.
     '
     Dim cn
     Dim rs
     cn = Server.CreateObject("ADODB.Connection")
     rs = Server.CreateObject("ADODB.RecordSet")
     ...
     Dim EncryptedCreditCardNumber
     EncryptedCreditCardNumber = rs("encryptedCreditCardNumber")
     
     '
     ' Get the N modulus from some database,
     ' (or wherever)
     '
     ...
     Dim N
     N = rs("N")
     
     '
     ' Get the private key from a form submission from the
     ' administrator, (or wherever)
     '
     ' You can have the private key on some other computer,
     ' and use it by cutting and pasting it from a
     ' web form for example.  If you are not using a computer
     ' on the same network (or VPN) as the web server, you
     ' would want to use SSL.
     '
     ' If you really trust the security of your web server,
     ' you can simply hard-code the private key right into
     ' the web page and place NT access restrictions on the
     ' web page.  However, if the page is somehow stolen, then
     ' your private key can also be stolen.
     '
     ' The best option is to copy the encrypted information off
     ' any server that is connected to the internet and then to
     ' decrypt it on a separate server that is not connected to
     ' the internet.  This makes it next to impossible to decrypt
     ' and steal any useful information.
     '
     Dim PrivateKey
     PrivateKey = Request.Form("privatekey") ' private key from
                                             ' a form submission.
     
     '
     ' Decrypt our message.
     '
     Dim message
     message = RSA.Decrypt( _
                    EncryptedcreditCardNumber, _
                    PrivateKey, _
                    N _
                  )
                  
     '
     ' Write the decrypted credit card number to the web page.
     ' The administrator or webmaster can complete the purchase 
     ' now.  The unencrypted credit card number only exists
     ' when it is retrieved, otherwise it is always encrypted.
     '
     response.write message
     
   %>
   

Kivco Consulting Inc.
241 Humberland Drive
Richmond Hill
Ontario  L4E 3T4

sales@kivco.com