4.2.1 Symmetric Encryption Provider with Key File

The Symmetric Encryption Provider uses symmetric encryption algorithms such as AES or DES. In symmetric encryption, a single key is used to encrypt and decrypt data. The key may be stored in a file or in a keystore. This section describes how to configure the Symmetric Encryption Provider to use a secret key stored in a file. The next section describes how to configure it to use a secret key stored in a keystore file.

Configuring a File-Based Secret Key

To configure the Symmetric encryption provider to use a file-based secret, set the following properties in the crypto.properties file.

Property Name	Value
crypto.provider	com.kana.connect.common.lib.crypto.SymmetricCryptoProvider
Class name of the Symmetric Encryption Provider.

crypto.provider.jce.provider	SunJCE
internal name of the JCE provider (“SunJCE” is the standard encryption engine that is bundled with the Java Runtime Environment)

crypto.provider.jce.provider.classname	com.sun.crypto.provider.SunJCE
the JCE provider which implements the Provider interface and that can be instantiated and installed as a dynamic JCE provider in Java

crypto.provider.jce.provider.position	1
position in which the JCE provider defined by crypto.provider.jce.provider.classname is going to be inserted in the chain of existing JCE providers if not already present

crypto.provider.jce.algorithm_mode_padd	AES
specify the encryption algorithm, mode and padding (encryption transformation – for example “AES” or "DES"). See Appendix A in the Java Cryptography Architecture Reference Guide for more information about standard transformation names

crypto.provider.key.size	128 or 256
Specifies the size of the encryption/decryption key in bits. Key sizes greater than 128 bits require the unlimited strength policy files (see below).

crypto.provider.key.location.type	file
specifies the type of the encryption/decryption key: can be “file” or “keystore”

crypto.provider.secret.key	/opt/connect/kc/import/crypto.key
specifies the location of the key file. IMPORTANT: The key file should be stored in the import directory so that it is copied to all nodes during the deployment process. This property should be an absolute pathname.

An example crypto.properties file is shown below.

# class name which implements connect CryptoProvider
crypto.provider=com.kana.connect.common.lib.crypto.SymmetricCryptoProvider

crypto.provider.jce.provider=SunJCE
crypto.provider.jce.provider.classname=com.sun.crypto.provider.SunJCE
crypto.provider.jce.provider.position=1
crypto.provider.jce.algorithm_mode_padd=AES
crypto.provider.key.size=128

# configure file-based secret
crypto.provider.key.location.type=file
crypto.provider.secret.key=/opt/connect/kc/import/crypto.key

Creating the Secret Key File

Once the cypto.properties file has been configured, the cryptoutil program may be used to create a secret key file. To create a secret key, run the following program:

$ sh install/cryptoutil.sh -ks

It will create a key file in the current directory based on the parameters in crypto.properties. In this example, the program will create a file named secret_AES_RAW#128.key. Move this key to the import directory and change its name to match the key file name in crypto.properties:

$ mv secret_AES_RAW#128.key import/crypto.key

Testing the Crypto Provider Configuration

Test your crypto provider configuration by encrypting the database connection string in database.properties:

$ sh install/encryptdbinfo.sh

This program should add a new database.connect.encrypted property to the database.properties file:

database.connect.encrypted=DdgCgX/Gyp+9n2j5gyRwDAedoK4Yi3OcQKoa812ZR6AmN7cA/ZJsrdhg89CELx8d

Note: If you receive an exception similar to the one shown below, you are most likely using key sizes that are larger than currently permitted by the Java Cryptography Libraries. To enable larger key sizes, install the unlimited-strength crypto policy files from this link: http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html.

com.kana.connect.common.lib.crypto.CryptoException: java.security.InvalidKeyException: Illegal key size or default parameters