Oracle® Fusion Middleware
Part 4. Manage API Gateway security

By default, the API Gateway configuration data is stored unencrypted. However, you can encrypt 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 then enter the passphrase when connecting to the API Gateway with the Policy Studio, or when the API Gateway is starting up, so that the encrypted data can be decrypted. You can enter the encryption passphrase at the level of an API Gateway group.

All sensitive information in the API Gateway configuration data is encrypted when you set an encryption passphrase. For example, this sensitive information includes passwords that the API Gateway requires for connecting to external systems (databases, LDAP, and so on), or private keys that are not stored on a Hardware Security Module (HSM). All sensitive information is encrypted using the Password-Based Encryption (PBE) system specified by the Public-Key Cryptography Standard (PKCS#12). For more details, see Appendix B of the PKCS#12 documentation.

This topic describes how to specify the encryption passphrase when connecting to the API Gateway with the Policy Studio, in your API Gateway configuration file, or when the API Gateway is starting up. It also describes how to change the API Gateway group passphrase when it has been set initially.

	Warning
	It is crucial that you remember the passphrase when you change it. Failure to remember the passphrase results in the loss of encrypted data, and may prevent the API Gateway from functioning correctly.

You can use the Policy Studio topology view to set the passphrase used to encrypt the API Gateway group data. This is the table displayed when you connect to the Admin Node Manager. To change the passphrase, right-click the API Gateway group name in the table (for example, QuickStart Group), and select Change Passphrase.

Complete the following fields on the Change Group Passphrase dialog:

Old Passphrase:

Enter the old passphrase that you wish to change in this field. Alternatively, you can leave this field blank if you are setting the passphrase for the first time.

New Passphrase:

Enter the new passphrase.

Confirm New Passphrase:

Re-enter the new passphrase to confirm it.

	Important
	You must also re-encrypt the Key Property Store tables after the passphrase has been changed. You can do this using the kpsadmin tool. For more details, see the Key Property Store User Guide, which is available from Axway Support.

If you have set an encryption passphrase for the API Gateway group configuration data, you must enter this passphrase every time you open a configuration for editing in Policy Studio. You can specify this in the Enter Passphrase dialog, which is displayed before editing an active server configuration.

When you first open a connection to an API Gateway in Policy Studio, you specify a Password. The different roles of the Passphrase and the Password fields are as follows:

For the API Gateway to read (decrypt) encrypted data from its configuration, it must be primed with the passphrase key. You can enter the passphrase directly in a configuration file, prompt for it at startup, or obtain it automatically with a script.

	Note
	Typically, the passphrase is only entered directly in the file if the server must be started as a Windows service or UNIX daemon. In this case, the administrator cannot enter the passphrase manually when the server is starting. To avoid this, you must enter the passphrase in the configuration file.

INSTALL_DIR/system/conf/nodemanager.xml

secret="myPassphrase"

INSTALL_DIR/groups/group-id/conf/group.xml

secret="(prompt)"

Provide the passphrase automatically at startup using a script

Alternatively, you can use a script to automatically provide the passphrase when the API Gateway server starts up. Perform the following steps:

1. Open the following file in your API Gateway installation:

   INSTALL_DIR/system/conf/service.xml

2. Add the following to your service.xml file:

   <SystemSettings tracelevel="INFO"
           passphraseExec="&quot;$VINSTDIR/passwd.bat&quot;"
           serviceID="${serviceID}" groupID="${groupID}"
           serviceName="${serviceName}" groupName="${groupName}"
           domainID="${domainID}" title="API Gateway"/>

   	Note
   	The passphraseExec option is only used if it is present and the secret option (described in the previous sections) is not used.

3. Create the passphrase script in the specified location. For example, on Windows, the contents of the passwd.bat script is as follows:

   @echo off
   echo secret

   For example, on Linux/UNIX, the contents of the passwd.sh script is as follows:

   #!/bin/sh
   echo secret

	Note
	The script must be secured by the operating system file permissions so that it is only accessible by, and can only be invoked by the API Gateway. The command should write the password to standard output.

When you promote and deploy passphrase protected configuration between environments (for example, from testing to production), the passphrase for the target configuration (production) must be the same as the passphrase in the source configuration (testing).

If you are using a different passphrase in each environment, before the deployment takes place, you must make a copy of the configuration (for example, .fed file), load it in Policy Studio, and set it with the correct passphrase for the target configuration. For more details, see the section called “Configure the passphrase in Policy Studio”.

For general details on promoting configuration between environments, see the API Gateway Deployment and Promotion Guide.

For more details on supported security features, see the API Gateway Security Guide.