CapeSoft CryptoNite

Introduction

CryptoNite provides encryption and decryption in your applications for security, safe data transfer etc. Cryptonite completely removes the complexity of implementing cryptography. Cryptonite aims to make using encryption as simple as possible, and handles all the complexity for you. CryptoNite requires StringTheory.

CryptoNite will easily help you:

• Encrypt and decrypt strings - with one line of code.
• Encrypt and decrypt files - with one line of code.
• Handle a wide variety of encryption types, from Symmetric key cipher such as Blowfish and 3DES to asymmetric public/private key cryptography such as RSA
• Perform encryption or decryption quickly and simply, with no experience with cryptography
• Handles certificates
• Sign and verify signatures using public/private key cryptography
• Base64 encoding and Decoding using StringTheory
• Unicode (UTF-8) to ANSI and ANSI to Unicode using StringTheory.

We strongly recommend starting with the example applications, which are described below in the Example section.

Basic Terminology

Cryptography is a field that has a wide variety of specific terminology, much of which can be confusing without a background in the subject.

Cipher

A cipher is simply a method of encrypting (tranforming or changing) data from one form into another. A simple cipher would be substituting letters with numbers, for example "ABC" would become "123". The different methods for encrypting data are known as ciphers. Ciphers typically preserve the data, so that what is encrypted can then be decrypted at a later stage. Most ciphers use a "key" to lock and unlock (encrypt and decrypt) the data.

Encryption and Decryption

The process of using a cipher to transform plain data into encrypted data and vice versa.

Symmetric and Asymmetric keys

When encrypting and decrypting there are two basic types of keys used:

Symmetric keys use the same key to encrypt and decrypt the data. An example would be providing a password to encrypt a file, and then using the same password to decrypt the file. In order to decrypt the data, you need to know the key (password), and hence the data is only as a secure as your mechanism for transferring the key is.

Asymmetric keys use a two parts of the the key, anything encrypted with one part can only be decrytped with the other. These are know as the Public and Private keys and form the Public/Private key pair. The public key is distributed, allowing anyone to encrypted data using it. The private key is kept securely, allowing the owner to decrypt data that is encrypted with the matching public key.

Assymetric keys tend to be far larger than symmetric keys are, and assymetric encryption is far slower. For this reason it is usually used as a key exchange mechanism. The session key (which is a symmetric key) is used to encrypt the data. The session key is then encrypted using the Public key, which means that only the person with the Private key can decrypt it. This is known as a key transport mechanism.

Hashing and Digest creation

Hashing is a method of creating a unique number from a given set of data. This provides a way to uniquely identify particular data, and to ensure that it has not been changed (if the data is not identical, the hash will change). Hashing is used to ensure the integrity of encrypted data, and to validate that the data has not been altered. Both plain (unencrypted) and cipher (encrypted) data can be hashed. A hash is also known as a digest. Common methods of creating digests are MD5, SHA-1 and SHA-2. SHA-1 is the most commonly used hash, although SHA-2 corrects a potential mathamatical weakness that SHA-1 might possess and is hence technically more secure. MD5 is no longer recommend as a result of demonstrated attacks resulting in collisions (two sets of data with the same hash).

MD5 hashes are 128 bits (16 bytes) long, SHA-1 hashes are 160 bits (20 bytes) long, and SHA-2 (SHA-256 and SHA-512) hashes can be 256 or 512 bits (32 and 64 bytes respectively) long.

Add CryptoNite to your application in a few Easy Steps!

Add the global and local extension

1. Add the Global Extension:
   Global -> Extensions -> Insert -> Activate CapeSoft CryptoNite.
   For Multi-DLL apps - do this in the main exe application.
   
2. Add the Local extension to the procedure that you wish to use CryptoNite in.
   This adds a CryptoNite object to the procedure.
   
   

Using CryptoNite

The code below demonstrates using the CryptoNite class for a variety of common tasks.

Container and Key Import

Get an existing container (which stores the encryption keys), or create one if it doesn't exist. For a new container, load a key from a file on disk into the container.

     if Cipher.GetContainer('MyApp', true) <> Crypto:OK
        Message('Cannot encrypt the file, could not create a Key Container.', 'Encryption Failed')
        return
    end

    ! Check if the key already exists, otherwise import it
    if Cipher.ImportKeyFile(keyFile)                        ! Load the key BLOB
        Message('Failed to load the key file.')
        Cipher.Kill()
        exit
    end

Before any encryption task are done a Cryptographic container  is needed. This container provides key storage and the like. CryptoNite makes using container as simple as calling GetContainer, CreateContainer and DeleteContainer.

Get a Container, Exchange Key and Encyrpt a File

Get and existing container, and then get the Public/Private key pair (the Exchange key) for the Container. Both GetContainer and GetUserKey have a second parameter that when set to True (1) causes the method to create the container or key if it does not already exist.

    if Crypto.GetContainer('MyCrypto', true) = Crypto:OK
        if Crypto.GetUserKey(cs:AT_KEYEXCHANGE, true) = Crypto:OK                              ! Get the key, and create one if needed.
            if Crypto.EncryptFile(plainFile, cipherFile) = Crypto:OK
                Message('File encrypted successfully')
            else
                Message('Encryption failed')
            end

            ! The file can be decrypted using the DecryptFile method
            if Crypto.DecryptFile(cipherFile, plainFile) = Crypto:OK
                Message('File decrypted successfully')
            else
                Message('Decryption failed')
            end
        end
    end				
				
				

Demo

This is the main CryptoNite example application. It demonstrates a variety of common and useful tasks using the CryptoNite class, including:

• Encrypting and decrypting files. This uses a randomly generated session key to encrypt the file, and the session key is then encrypted using the public key of the recipient and embedded with the encrypted data. When the file is decrypted the private key is used to retrieve the session key and decrypt the data.
  
• Asymmetric Encryption. The PPK Ciphers window demonstrates directly encrypting and decrypting a block of data using a public/private key pair, as well as creating an Hash of the data.

The Global Extension template:

The CryptoNite local extension template

Add this extension to populate an instance of the CryptoNite class for you. This can also be done very simply in your code:

Crypt                   CryptoNite
  code
    if Crypto.GetContainer('MyCrypto', true) = Crypto:OK
        Crypto.GetUserKey(cs:AT_KEYEXCHANGE, true) ! Get the key, and create one if needed.
    end
    if Crypto.EncryptFile(plainFile, cipherFile) = Crypto:OK
        Message('File encrypted successfully')
    else
        Message('Encryption failed')
    end