# Setting the Encryption Passphrase

## Contents
Encryption Passphrase Overview Setting the Passphrase for the First Time Connecting to the Enterprise Gateway with Policy Studio Connecting to Enterprise Gateway Configuration Data Changing the Passphrase

## Encryption Passphrase Overview
By default, Enterprise 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), you must enter the passphrase when connecting to the Enterprise Gateway with the Policy Studio, or when the Enterprise Gateway is starting up, so that the encrypted data can be decrypted. 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 topic describes how to set the passphrase for the first time, and then how to specify this passphrase when connecting to the Enterprise Gateway with the Policy Studio, in your Enterprise Gateway configuration file, or when the Enterprise Gateway is starting up. It also describes how to change the passphrase when 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: Start the Policy Studio using the `policystudio` command from your Policy Studio installation directory. In the Policy Studio, click the Open File button in the toolbar on the Home tab. Alternatively, in the main menu, select File -> Open File. Browse to the Enterprise Gateway `install_dir/conf/fed/configs.xml` file, and click Finish. Leave the Passphrase Key field blank when setting the passphrase for the first time. Important Note: If the Enterprise Gateway server is on a remote machine, you must copy its `install_dir/conf/fed` directory to the local machine that the Policy Studio is running on, before connecting to the `configs.xml` file. You can then set the passphrase, and copy the `/fed` directory back to the `install_dir/conf` directory on the machine where the Enterprise Gateway is running. When the configuration file is loaded, in the Policy Studio main menu, select Settings -> Settings -> Change Passphrase. Alternatively, click the Settings button in the toolbar, and select Change Passphrase. In the Change Encryption Passphrase dialog, enter the passphrase that you want to encrypt sensitive data with in the New Passphrase field. Make sure to leave the Old Passphrase field blank when setting the passphrase for the first time. Click OK. You must now specify the new passphrase when connecting to the Enterprise Gateway configuration with the Policy Studio and when the Enterprise Gateway starts up. The following sections describe how to do this for both components.
## Connecting to the Enterprise Gateway with Policy Studio
When you have set the encryption passphrase for the Enterprise Gateway configuration data, you must specify this passphrase every time you connect to the Enterprise Gateway with the Policy Studio using the Enterprise Gateway's management interface. You can enter it in the Passphrase Key field of the Connection Details dialog, which is displayed when the Policy Studio is starting up. It is important to note the different roles of the Passphrase Key and Password values that are specified on this screen:
Passphrase Key | Used to decrypt sensitive data (for example, private keys) that have already been encrypted. Not required by default, and only needed if the steps outlined above have been performed.
Password | Used to authenticate to the Enterprise Gateway's management interface using HTTP basic authentication. Required by default.
## Connecting to Enterprise Gateway Configuration Data
For the Enterprise Gateway to read (decrypt) encrypted data from its configuration, it must be primed with the passphrase key. You can do this either by specifying the passphrase directly in the Enterprise Gateway configuration file, or by prompting for it when the Enterprise Gateway is starting up: Specifying the Passphrase in the Configuration File You can specify the passphrase directly in the Enterprise Gateway's configuration file. To do this, open the `userconfig.dtd` file 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 Enterprise Gateway, and also (if required) the passphrase key to use to decrypt encrypted Enterprise Gateway configuration data. Typically, the passphrase is only entered directly in the file if the Enterprise Gateway must be started as a Windows Service or UNIX daemon. In this case, it is not possible for an administrator to enter a password manually when the Enterprise 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 do not wish to specify the passphrase in the configuration file, and do not need to start the Enterprise Gateway as a Windows Service or UNIX daemon, you can configure the Enterprise 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)">
Important Note: If you use this option, you must take care to remember the encryption passphrase. Failure to use the correct passphrase results in loss of private key data, and may prevent the Enterprise Gateway from functioning correctly.
## Changing the Passphrase
If you have already specified a passphrase to use to encrypt the data, you can change this passphrase by clicking the Settings button in the toolbar, and selecting Change Passphrase. Complete the following 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.