Encryption Passphrase Overview

By default, Gateway configuration data is stored unencrypted. However, you can encrypt certain sensitive
information, such as passwords and private keys, using a passphrase. When the passphrase has
been set (and the data has been encrypted with it), it must be entered when connecting to the Gateway
with both the Policy Studio and the Gateway so that these components can decrypt the encrypted
data.

Important Note:

It is crucial that you remember the passphrase when you change it. Failure to remember the passphrase
results in the loss of private key data.

This help page describes how to set the passphrase for the first time and then how to specify this passphrase
when connecting to the Gateway with both the Policy Studio and the Gateway. We also describe
how to change the passphrase once it has been set initially.



Setting the Passphrase for the First Time

Complete the following steps to set the encryption passphrase for the first time:

1. Start the Policy Studio from the INSTALL_DIR/ directory of your Policy Studio installation,
where "INSTALL_DIR" points to the root of your Policy Studio installation.

2. In the Policy Studio main window click on the "Open File" button underneath the "Home" tab. Alternatively,
click on "File" on the top menu and select "Open File".

3. Browse to the vordelgateway_install_dir/conf/fed/configs.xml file and click on "Finish". NOTE: If the server is on a remote machine i.e. appliance, you will have to copy the vordegateway_install_dir/conf/fed directory to the local machine that Policy Studio is running on, before connecting to the /fed/configs.xml file. Make the change and copy the /fed directory back to vordelgateway_install_dir/conf diretory on the machine where the Gateway is running.

4. Once the configuration file has loaded, click on "Settings" on the top menu, followed by "Settings" again then choose "Change Passphrase".

5. Enter the passphrase that you want to use to encrypt sensitive data in the New Passphrase field.
Make sure to leave the "Old Passphrase" field blank if you are setting the passphrase for the first
time then click on "OK" once finished.


6. The new passphrase must now be specified when connecting to the Gateway with the Policy Studio
and also with the Gateway. The following instructions describe how to do this for both components.


Connecting to the Gateway with the Policy Studio:

Having set the encryption passphrase for the Gateway configuration data, this passphrase must now be
specified every time you connect to the Gateway with the Policy Studio using the Gateway's management
interface.

The passphrase can be entered in the Passphrase Key field of the Connection Details dialog, which
is displayed when connecting to the selected Gateway process.

It is important to note the different roles of the Passphrase Key and Password values that are specified
on this screen:

Passphrase Key:
The Passphrase Key entered here is used to decrypt sensitive data (for example, private keys) that
have already been encrypted. It is not required by default and is only needed if the steps outlined
above have been carried out.

Password:
On the other hand, the Password specified here is used to authenticate to the Gateway's management
interface using HTTP basic authentication. It is required by default.

Connecting to Gateway Configuration Data with the Gateway:
For the Gateway to read (i.e. decrypt) encrypted data from its configuration, it must be primed with the
passphrase key. This can be done either by specifying the passphrase directly in the Gateway configuration
file, or by prompting for it when the Gateway is starting up:

Specifying the Passphrase in the Configuration File:
It is possible to specify the password directly in the Gateway's configuration file. To do this, open the
userconfig.dtd file, which can be found in the /conf directory of your product installation. This DTD
file contains values for general system settings, including the username and password to use to authenticate
to the management interface exposed by the Gateway and also (if required) the passphrase
key to use to decrypt encrypted Gateway configuration data.

Typically the password is only entered directly in the file if the Gateway must be started as an NT Service
or UNIX daemon. In this case, it is not possible for an administrator to enter a password manually
when the Gateway is starting. To avoid this problem, the password must be entered in the configuration
file. To do this, specify the passphrase as the value for the server.entitystore.secret entity as
follows, where "myPassphrase" is the encryption passphrase:

<!ENTITY server.entitystore.secret "myPassphrase">

Prompting for the Passphrase on Server Startup:
If you would rather not specify the passphrase in the configuration file and do not need to start the
Gateway as an NT Service or UNIX daemon, you can configure the Gateway to prompt the administrator
for the passphrase when starting up. To do this, enter the special value "(prompt)" as the value of
the server.entitystore.secret entity as follows:

<!ENTITY server.entitystore.secret "(prompt)">

It is important to note that if you use this option, you must take care to remember the encryption
passphrase. Failure to use the correct passphrase will result in loss of private key data and may prevent
the Gateway from functioning correctly.


Changing the Passphrase:

If you have already specified a passphrase to use to encrypt the data previoulsy, you can change this passphrase by repeating the steps above, making sure to insert the current passphrase in the "Old Passphrase" field followed by the new desired passphrase.

Fields on the Change Encryption Passphrase dialog:


Old Passphrase:
Enter the old passphrase that you wish to change in this field.

New Passphrase:
Enter the new passphrase here.

Old Passphrase:
Confirm the new passphrase in this field.