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.
|
|