10 Setting Up Encryption

Encryption is used to protect data within Oracle Adaptive Access Manager from unauthorized access. The process uses methods and a key or keys to encode plain text into a non-readable form. A key is required to decrypt the encrypted information and make it readable again. Authorized persons who possess the key can decrypt information that is encrypted with the same key.

Because encryption is critical to successful implementation of Oracle Adaptive Access Manager, setup of the encryption environment cannot be delayed until a later time. If encryption is skipped entirely, the software may break and all data will be stored as clear text, easily readable by anyone.

In Oracle Adaptive Access Manager 10.1.4.5 and above, external files (called keystores) are used for the secure storage and management of the encryption keys. This chapter helps guide you through the creation of the keystores.

This chapter provides information for configuring Oracle Adaptive Access Manager for

• Configuration Encryption

  Adaptive Risk Manager encryption APIs are use to encrypt sensitive configuration data. By default, DESede algorithm is used with the encryption key provided during installation.

• Database Encryption

  Adaptive Risk Manager encrypts sensitive data in certain database fields. By default, DESede algorithm is used to encrypt with the encryption key provided during installation.

Note:

Adaptive Risk Manager uses the DESede encryption algorithm to encrypt database and configuration properties. However, Adaptive Risk Manager provides the option to change the algorithm to another one of your choice. By default, algorithm support is provided for AES, DES, and DESede.

For Adaptive Risk Manager and Adaptive Risk Manager encryption APIs to work properly, you will need to create and set up the following keystores:

• system_config.keystore

  The key used for configuration encryption is stored in this keystore.

• system_db.keystore

  The key used for database encryption is stored in this keystore.

Note:

Ensure you keep a backup of the keystore and bharosa_server.properties and bharosa_client.properties files in case you should need to restore any customer specific customizations or upgrade to Adaptive Risk Manager software at a later date.

10.1 Creating a Keystore for Encrypting Configuration Values

To create a keystore for encrypting configuration values using 3DES algorithm,

1. Unzip the oaam_keystore_util.zip in the oaam_utils directory.

   The oaam__keystore_util.zip file is available from oaam_bin.zip.

2. In the keystore_util directory, create a file, for example, config_3des_key.file, and enter your encryption key (password).

   This is your key to the encryption algorithm.

   Please note that 3DES accepts any key, but it needs to be a minimum of 24 characters.

3. Copy sample.config_3des_input.properties to config_3des_input.properties.

4. Update config_3des_input.properties with the keystore password, alias password, and keyFile.

   A keystore is like a master vault that stores entries. To open the keystore, a "keystore password" is required. Each entry in the keystore is identified by an "alias." There can be multiple aliases in a keystore, each with its own password. This password is called the "alias password" and used to access/read the value that is identified with an alias.

5. Generate the keystore.

   • For Unix/Linux, run

     genkeystore.sh config_3des_input.properties
     

   • For Windows, run

     genkeystore.cmd config_3des_input.properties
     

   If the KeyStore command was successful, you will see output similar to the following:

   updateOrCreateKeyStore done!
   Keystore file:system_config.keystore,algorithm=DESede
   KeyStore Password=ZG92ZTEyMzQ=
   Alias Password=ZG92ZTEyMw==
   

   If the KeyStore command was not successful, you might see the following error:

   xception in thread "main" java.lang.NoClassDefFoundError: while resolving
   class: com.bharosa.vcrypt.common.util.KeyStoreUtil at
   java.lang.VMClassLoader.resolveClass(java.lang.Class)
   (/usr/lib/libgcj.so.5.0.0) at java.lang.Class.initializeClass()
   (/usr/lib/libgcj.so.5.0.0) at java.lang.Class.forName(java.lang.String,
   boolean, java.lang.ClassLoader) (/usr/lib/libgcj.so.5.0.0) at
   java.lang.Class.forName(java.lang.String) (/usr/lib/libgcj.so.5.0.0)
   

   Ensure that you are using the Sun JDK and not another packaged Java version. Install the Sun JDK.

6. Note down the Keystore password and Alias Password printed on the screen. You will need to add these to the bharosa_server.properties and bharosa_client.properties.

7. Save the system_config.keystore file in your source code control system. Please take adequate security precaution while handling this file. The file contains critical password information. Make sure that only authorized personnel have read access to this file. If you lose it, Oracle Adaptive Access Manager will not be able to recover data encrypted. Also, you will need this file after installing Adaptive Strong Authenticator.

8. Copy system_config.keystore to Adaptive Risk Manager's classpath (for example, oarm/WEB-INF/classes). If Adaptive Strong Authenticator is being installed, copy system_config.keystore to Adaptive Strong Authenticator's classpath (for example, oasa/WEB-INF/classes).

   Note:

   Using the key generator utility, you can create two separate keystores for Adaptive Risk Manager and Adaptive Strong Authenticator.

9. Delete both the config_3des_key.file and config_3des_input.properties files.

10. Later when you update properties in oarm/WEB-INF/classes/bharosa_server.properties and oasa/WEB-INF/classes/bharosa_client.properties, you will update the following properties with the encoded passwords (from Step 6).

    bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=<base64 encoded keystore password>
    bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=<based64 encoded password to the alias>
    

    For updating the bharosa_server.properties file, refer to Chapter 6, "Installing Adaptive Risk Manager" for information about when to edit the file during the installation process and to Chapter 12, "Configuring Server Properties"for instructions on editing the file.

    For updating the bharosa_client.properties file, refer to Chapter 7, "Installing the Adaptive Strong Authenticator" for information about when to edit the file during the installation process and to Chapter 15, "Configuring Client Properties"for instructions on editing the file.

10.2 Creating a Keystore for Encrypting Database Data

To create a keystore for encrypting database data using 3DES algorithm,

1. In the oaam_utils/keystore_util directory, create a file, for example, db_3des_key.file, and enter your encryption key (password).

   This is your key to the encryption algorithm.

   Please note that 3DES accepts any key, but it needs to be a minimum of 24 characters.

2. Copy sample.db_3des_input.properties to db_3des_input.properties.

3. Update db_3des_input.properties with the keystore password, alias password, and keyFile.

4. Generate the keystore.

   • For Unix/Linux, run

     genkeystore.sh db_3des_input.properties
     

   • For Windows, run

     genkeystore.cmd db_3des_input.properties
     

   If the KeyStore command was successful, you will see output similar to the following:

   updateOrCreateKeyStore done!
   Keystore file:system_db.keystore,algorithm=DESede
   KeyStore Password=ZG92ZTEyMzQ=
   Alias Password=ZG92ZTEyMw==
   

5. Note down the Keystore password and Alias Password print on the screen. You will need to add these to the bharosa_server.properties.

6. Save the system_db.keystore file in your source code control system. Please take adequate security precaution while handling this file. The file contains critical password information. Make sure that only authorized personnel have read access to this file. If you lose it, Oracle Adaptive Access Manager will not be able to recover data encrypted.

7. Copy system_db.keystore to Adaptive Risk Manager's classpath. For example: oarm/WEB-INF/classes.

8. Delete both the db_3des_key.file and db_3des_input.properties files.

9. Later when you update oarm/WEB-INF/classes/bharosa_server.properties, you will add/update the following properties with the encoded passwords (from Step 5).

   bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=<base64 encoded keystore password>
   bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=<based64 encoded password to the alias>
   

   For updating the bharosa_server.properties file, refer to Chapter 6, "Installing Adaptive Risk Manager" for information about when to edit the file during the installation process and to Chapter 12, "Configuring Server Properties"for instructions on editing the file.

10.3 Other Procedures

For more information on defining and adding encryption schemes and creating keystores, refer to Appendix C, "Upgrading from 3.5 to 10.1.4.3."