Data Encryption

Data encryptions is done using four basic concepts: the keystore, master password, encrypted data synchronization, and the keystore console.

KeyStore – the location where the encryption keys used by IdentityIQ are persisted.
Master Password – the entire keystore can be encrypted with an ascii password. This is the keystore or master password. You can change the keystore password using the keystore console command. Only one master password can exist. When the master password changes the entire keystore and master password file are re-encrypted and rewritten.
Encryped Data Synchronization – the process of re-encrypting existing data with the newest key in the keystore.
Keystore Console – the tool (spt keystore) used to manage the keystore and master password.

The keystore and master password are file based and secured by the file system. They are stored in two separate files. The files can be located in the IdentityIQ deployment directory or placed in an alternative directory during configuration. By default the files are stored in the following location:

    keystorePassword = WEB-INF/classes/iiq.cfg
    keystore = WEB-INF/classes/iiq.dat

An alternate keystore file location, password file, or just password in clear text can be specified in the iiq.properties file under these keys:

    keyStore.file
    keyStore.passwordFile

spt KeyStore Console Commands

The iiq keystore command is the interface to update the keystore and keystore password. A master password can to be entered into the console or generated when it is being updated.

The keyStore console supports the following commands:

use KeyStoreFilemasterFile

Note

If you do not call the use command, the changes are positioned in the configured paths.

Specify the keystore and master file to use when interacting with an alternate keystore.

The keyStoreFile argument in position 1 specifies the path to the file to be used when creating/updating the keystore. If this argument is not specified the command uses $SPHOME/WEB-INF/classes/iiq.dat.

The masterFile argument in position 2 specifies the path and filename used to store the master file.

The use command gives you the ability to build the keystores outside your operating running environment and merge them in when scheduled.

addKey [ -q ]

Note

If no argument is included, you are prompted for confirmation before the key is generated.

Generate a new encryption key, the key is securely generated and random.

-q as argument in position 1 generates a new key without prompting for confirmation.

list
List the contents of the keystore.
master [newPasswordnewPasswordConfirmation]

Note

Passwords must be at least 8 characters.

Change the master password and re-encrypt the keystore using the new password.

Note

If no argument is included, you are prompted for confirmation.

If newPassword and newPasswordConfirmation are in argument position 1 and 2, you are not prompted for confirmation.

-g is in argument position 1 a new password is generated without confirmation.

about
Specifies the two files that being modified.

Encrypted Data Synchronization

The Encrypted Data Synchronization task goes over the objects re-encrypting the values using the newest key.

Note

The Encrypted Data Synchronization task is not enabled upon installation, you must create the task from the New Task dropdown menu.

The task encrypts the following attributes / types by default:

Application secret configuration attributes
User passwords
Password history
Users challenge questions
Activity / Target source configurations
Integration configuration password attributes

In cases such as integration configuration and unstructured target sources the task looks for encrypted values with the password in the name. You can also add a configuration attribute, IIQSecretAttributes, to either type names to define which attributes are targeted during a re-synchronization.

    <entry key="IIQSecretAttributes">
    <value>
    <List>
    <String>mySecret1</String>
    <String>mySecret2</String>
    <String>password</String>
    </List>
    </value>
    </entry>

The task enables you do disable the following three categories of objects:

Applications – which enabled application, activity and target source updates
Identity
Integration configuration

Using IdentityIQ KeyStore

Note

Make sure to store copies of the iiq.dat and iiq.cfg files in a safe place. When you upgrade or reinstall IdentityIQ, the files are readily available to be restored.

Note

Make sure that the file permissions are set to allow access only by the application server that runs IdentityIQ.

In a standard installation of IdentityIQ, passwords are all encrypted using the same encryption secret. Encrypted passwords used in one installation can be reused (decrypted) by any other installation of IdentityIQ. The keystore feature enables the use of a site specific key. With the keystore feature enabled, a password used on one site cannot be decrypted on another site without having the site specific encryption keys.

Configuration

The keystore is stored in WEB-INF/classes/iiq.dat with an accompanying configuration file WEB-INF/classes/iiq.cfg.

The iiq.properties file provides two options to specify an alternative location for iiq.dat and iiq.cfg. In the default iiq.properties, these options (keyStore.file and keyStore.passwordFile) are commented out.

    # IIQ Keystore and Master Password properties    
    #  

    # file location of the IIQ keystore  
    # (override of the default $SPHOME/WEB-INF/classes/iiq.dat )  
    #  
    #keyStore.file = /example/path/filename  

    # file location of the IIQ master password file  
    # (override of the default $SPHOME/WEB-INF/classes/iiq.cfg )  
    #  
    #keyStore.passwordFile = /example/path/filename

To put the files in an alternative location, for example /etc/identityiq, enable and change these options as follows.

Note

You may need to modify your application server or Java sandbox security settings to allow access to the key files outside the application server installation directories.

    # IIQ Keystore and Master Password properties    
    #  

    # file location of the IIQ keystore  
    # (override of the default $SPHOME/WEB-INF/classes/iiq.dat )  
    #  
    keyStore.file = /etc/access governance suite/iiq.dat  

    # file location of the IIQ master password file  
    # (override of the default $SPHOME/WEB-INF/classes/iiq.cfg )  
    #  
    keyStore.passwordFile = /etc/access governance suite/iiq.cfg

Key Creation

To create or manage the keystore: navigate to the WEB-INF/bin folder and start the IdentityIQ KeyStore console with the keystore command:

Navigate to the WEB-INF/bin folder and start the IdentityIQ Keystore console with the keystore command.
```
iiq keystore
```
The console displays a prompt similar to the IdentityIQ console. Use the help to list all accepted KeyStore Console commands. For example, use the addKey command to create a new key and the list command to view the contents of the keystore.

    > addKey
    Generate a new encryption key (y/n)?
    y
    Generating a new encryption key for keystore
    [/var/tomcat/webapps/identityiq/WEB-INF/classes/spt.dat].
    New encrpytion key successfully saved to keystore.
    All application servers must be restarted for changes to take effect.
    >

If the keystore file does not exist, it is created and a new, randomly generated key is added.

The list command displays the newly created key:

    > list
    Listing contents for keystore
    [/var/tomcat/webapps/iiq6/WEB-INF/classes/iiq.dat].
    KeyAlias Algorithm Format Object

    2 AES RAW javax.crypto.spec.SecretKeySpec@fffe81cd
    >

Use the exit command to leave the console.

Re-Encrypt Passwords

The new encryption key is used for newly encrypted passwords. However, because existing passwords can also be decrypted using the default method on any system, you must re-encrypt existing passwords. Ro re-encrypt existing password, you must create a new Encrypted Data Synchronization Task in IdentityIQ.

From the Navigation menu bar, select Intelligence > Tasks.
From the New Task dropdown list select Encrypted Data Synchronization Task from the dropdown list.
Enter a name for the new task.
OPTIONAL: If needed, you can exclude types such as applications, identities or integration configurations from processing.
Save and Execute to immediately run the task.

After the task has completed, all selected encrypted data is changed. A password encrypted with the default key is prefixed with 1. Items encrypted with the new encryption key are prefixed with 2 or another number if multiple encryption keys are stored.

For example, when you look up the Administrator's password in the console, the displays is similar to the following:

    > search identity password where name admin
    2:WpTZ2hmNaInTAJzeK9Swcw==

Using the Different Encryption Keys

After a new key is added to the keystore, the key is used as the default encryption key. Everything encrypted inside IdentityIQ then uses the new key. For example:

    $ ./iiq console
    > encrypt test
    2:bt7YJA6iovzF5Uu6RIjueg==
    >

There is one exception. The command iiq encrypt, continues to use the original default encryption key:

    $ ./iiq encrypt test
    1:8zJwAXqvK5/b92JbPXLLKw==
    $

Although the syntax reported by the bare command does not indicates this, the command accepts an extra parameter to select the encryption key to use. For example:

iiq encrypt string [key]

Note

The encrypt command in the iiq console does NOT accept this extra parameter.

The key is the number that displays in the list command and used as prefix for the keys.

To select the newly created key, use 2. If multiple keys are in the keystore, use any available higher number.
To select the original default key use 1 or nothing.

For example:

    $ ./iiq encrypt test 1
    1:8zJwAXqvK5/b92JbPXLLKw==
    $ ./iiq encrypt test 2
    2:bt7YJA6iovzF5Uu6RIjueg==