Manage X.509 certificates and keys

Overview

The Environment Configuration > Certificates and Keys node in the Configuration Studio tree enables you to manage the X.509 certificates and keys trusted by API Gateway. These settings are environment-specific, and typically need to be configured during promotion to an upstream environment.

For API Gateway to trust X.509 certificates issued by a specific Certificate Authority (CA), you must import that CA's certificate into the API Gateway's trusted certificate store. For example, if API Gateway is to trust secure communications (SSL connections or XML Signature) from an external SAML Policy Decision Point (PDP), you must import the PDP certificate, or the issuing CA certificate into the API Gateway certificate store.

In addition to importing CA certificates, you can import and create server certificates and private keys in the certificate store. These can be stored locally or on an external Hardware Security Module (HSM). You can also import and create public-private key pairs. For example, these can be used with the Secure Shell (SSH) File Transfer Protocol (SFTP) or with Pretty Good Privacy (PGP).

View certificates and keys

To view the certificates and keys stored in the certificate store, select Environment Configuration > Certificates and Keys > Certificates in the Configuration Studio tree. Certificates and keys are listed on the following tabs in the Certificates window:

  • Certificates with Keys: Server certificates with associated private keys
  • Certificates: Server certificates without any associated private keys
  • CA: Certificate Authority certificates with associated public keys

You can search for a specific certificate or key by entering a search string in the text box at the top of each tab, which automatically filters the tree.

Certificates tab

Certificate management options

The following options are available at the bottom right of the window:

  • Create/Import: Click to create or import a new certificate and private key. For details, see Configure an X.509 certificate.
  • Edit: Select a certificate, and click to edit its existing settings.
  • View: Select a certificate, and click to view more detailed information.
  • Remove: Select a certificate, and click to remove the certificate from the certificate store.
  • Keystore: Click this to export or import certificates to or from a Java keystore. For details, see Manage certificates in Java keystores.

Configure an X.509 certificate

To create a certificate and private key, click Create/Import. The Configure Certificate and Private Key dialog is displayed. This section explains how to use the X.509 Certificate tab on this dialog.

Edit a certificate

Create a certificate

Configure the following settings to create a certificate:

  • Subject:
    Click Edit to configure the Distinguished Name (DName) of the subject.
  • Alias Name:
    This mandatory field enables you to specify a friendly name (or alias) for the certificate. Alternatively, you can click Use Subject to add the DName of the certificate in the text box instead of a certificate alias.
  • Public Key:
    Click Import to import the subject's public key (usually from a PEM or DER-encoded file).
  • Version:
    This read-only field displays the X.509 version of the certificate.
  • Issuer:
    This read-only field displays the distinguished name of the CA that issued the certificate.
  • Choose Issuer Certificate:
    Select to explicitly specify an issuer certificate for this certificate (for example, to avoid a potential clash or expiry issue with another certificate using the same intermediary certificate). You can then click the browse button on the right to select an issuer certificate. This setting is not selected by default.
  • Not valid before:
    Select a date to define the start of the validity period of the certificate.
  • Not valid after:
    Select a date to define the end of the validity period of the certificate.
  • Sign Certificate:
    You must click this button to sign the certificate. The certificate can be self-signed, or signed by the private key belonging to a trusted CA whose key pair is stored in the certificate store.

Import certificates

You can use the following buttons to import or export certificates into the certificate store:

  • Import Certificate:
    Click to import a certificate (for example, from a .pem or .der file).
  • Export Certificate:
    Click to export the certificate (for example, to a .pem or .der file).

Configure a private key

Use the Private Key tab to configure details of the private key. By default, private keys are stored locally (for example, in the API Gateway certificate store). They can also be provided by an OpenSSL engine, or stored on a Hardware Security Module (HSM) if required.

API Gateway supports PKCS#11-compatible HSM devices. For example, this includes Thales nShield Solo (provided locally with the API Gateway API Gateway Appliance), SafeNet Luna SA, and so on.

Edit a Private key

Private key stored locally

If the private key is stored in the API Gateway certificate store, or on the Thales nShield Solo HSM provided locally with the appliance, select Private key stored locally. The following options are available for keys stored locally:

  • Private key stored locally:
    This read-only field displays details of the private key.
  • Import Private Key:
    Click to import the subject's private key (usually from a PEM or DER-encoded file).
  • Export Private Key:
    Click to export the subject's private key to a PEM or DER-encoded file.
Note   When using the Thales nShield Solo HSM provided locally with the API Gateway API Gateway Appliance, select Private key stored locally. For more details, see the API Gateway Appliance Installation and Administration Guide.

Private key provided by OpenSSL engine

If the private key that corresponds to the public key in the certificate is provided by an OpenSSL engine, select Private key provided by OpenSSL Engine.

Configure the following fields to associate a key provided by the OpenSSL engine with the current certificate:

  • Engine name:
    Enter the name of the OpenSSL engine to use to interface to an HSM. All vendor implementations of the OpenSSL Engine API are identified by a unique name. See your vendor's OpenSSL engine implementation or HSM documentation to find out the name of the engine.
  • Key Id:
    Enter the key ID used to uniquely identify a specific private key from all others stored on an HSM. When you complete this dialog, the private key is associated with the certificate that you are currently editing. Private keys are identified by their key ID by default.

Private key stored on external HSM

If the private key that corresponds to the public key stored in the certificate resides on an external HSM, select Private key stored on Hardware Security Module (HSM) , and enter the name of the Certificate Realm.

Note   To use the API Gateway's PKCS#11 engine to access objects in an external HSM, the corresponding HSM provider and certificate realms must also be configured. For more details, see Configure HSMs and certificate realms.

Configure HSMs and certificate realms

Certificate realms are abstractions of private keys and public key certificates, which mean that policy developers do not need to enter HSM-specific configuration such as slots and key labels. Instead, if a private key exists on an HSM, the developer can configure the certificate to show that its private key uses a specific certificate realm, which is simply an alias for a private key (for example, JMS Keys ).

For example, on the host machine, an administrator could configure the JMS Keys certificate realm, and create a keystore for the realm, which requires specific knowledge about the HSM (for example, PIN, slot, and private key label). The certificate realm is the alias name, while the keystore is the actual private keystore for the realm.

Note   This section does not apply when using the Thales nShield Solo HSM provided locally with the API Gateway Appliance. Instead select Private key stored locally, and see the API Gateway Appliance Installation and Administration Guide.

Manage HSMs with keystoreadmin

The keystoreadmin script enables you to perform the following tasks:

  • Register an HSM provider
  • List registered HSM providers
  • Create a certificate realm
  • List certificate realms

For example, if a policy developer is using JMS, and wants to indicate that private keys exist on an HSM, they could indicate that the certificate is using the JMS Keys certificate realm. On each instance using the configuration, it is the responsibility of the administrator to create the JMS Keys certificate realm.

For more details, enter keystoreadmin in the following directory, and perform the instructions at the command prompt:

Windows INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux INSTALL_DIR/apigateway/posix/bin

Use keystoreadmin in interactive mode

When you enter keystoreadmin without arguments, this displays an interactive menu with the following options:

Option Description When to use
1 Change group or instance When registering HSMs or configuring certificate realms, you must choose the local group and instance to configure.
2 List registered HSM providers Display the HSMs that are currently registered.
3 Register an HSM provider Before creating certificate realms, you must first register the HSM. This option guides you through the steps. The HSM must be installed, configured, and active, and you must know the full path to the HSM device driver (PKCS#11). You give the HSM an alias (for example, LunaSA), which you use later when registering certificate realms.
4 List Certificate Realms List configured certificate realms and associated keystores.
5 Create a Certificate Realm Create a keystore and assign it to a certificate realm.

Step 1—Register an HSM provider

You must first register an HSM provider as follows:

  1. Open a command prompt in the API Gateway bin directory (for example, apigateway\Win32\bin).
  2. Enter the keystoreadmin command.
  3. Select option 3) Register an HSM provider.
  4. If prompted, select the appropriate API Gateway group or instance.
  5. You are prompted for a provider alias name. The alias is local only. For example, if registering a LunaSA HSM, you might enter the LunaSA alias.
  6. For convenience, keystoreadmin searches for supported HSM drivers. If found, it shows the list of supported drivers. If none are found, this does not mean the driver does not exist. You must see your HSM documentation for the location of the drivers. For example:
  7. If successful, keystoreadmin loads the driver and displays its details. For example:

Step 2—Create a certificate realm and associated keystore

To create a certificate realm and associated keystore, perform the following steps:

  1. Open a command prompt in the API Gateway bin directory (for example, apigateway\Win32\bin).
  2. Enter the keystoreadmin command.
  3. Select option 5) Create a Certificate Realm.
  4. You are prompted to enter a certificate realm name. This certificate realm name is used in Configuration Studio when configuring the private key of the corresponding X.509 certificate. The realm name is case sensitive (for example, JMS Keys).
  5. The registered HSMs are listed. For example, select option 1) HSM.
  6. The command connects to the selected HSM, and a list of available slots is displayed. Select the slot containing the private key to use for the certificate realm (for example, select slot 1).
  7. You are prompted to input the PIN passphrase for the slot. The passphrase will not echo any output.
  8. When you enter the correct PIN passphrase for the slot, this displays a list of private keys. Choose the key to use for the certificate realm. For example:
  9. You are prompted for a file name for the keystore. For example:
  10. The keystore is output to the API Gateway instance directory. For example:
Note   Each API Gateway instance must have its certificate realm configured. When finished creating certificate realms, you must restart the API Gateway instance for the changes to take effect.

Step 3—Start the API Gateway when using an HSM

When the API Gateway is configured to use certificate realms, these realms are initialized on startup, and a connection to the corresponding HSM is established. This requires the PIN passphrase for the specific HSM slots. At startup, you can manually enter the required HSM slot PIN passphrase, or you can automate this instead.

Start API Gateway with manually entered PIN passphrase

When the API Gateway is configured to use an HSM, the API Gateway stops all processing, prompts for the HSM slot PIN passphrase, and waits indefinitely for input. For example:

The API Gateway does not reprompt if the PIN passphrase is incorrect. It logs the error and continues, while any services that use the certificate realm cannot use the HSM.

Start API Gateway with automatic PIN passphrase

You can configure the API Gateway to start and initialize the HSM by invoking a command script on the operating system to obtain the HSM slot PIN passphrase. This enables the API Gateway for automatic startup without manually entering the PIN passphrase.

To configure an automatic PIN passphrase, perform the following steps:

  1. Edit the API Gateway instance’s vpkcs11.xml configuration file. For example:
  2. Add a PASSPHRASE_EXEC command that contains the full path to the script that executes and obtains the passphrase. The script should write the passphrase to stdout, and should have the necessary operating system file and execute protection settings to prevent unauthorized access to the PIN passphrase. The following example shows a vpkcs11.xml file that invokes the hsmpin.sh to echo the passphrase:
  3. The API Gateway provides the certificate realm as an argument to the script, so you can use the same script to initialize multiple realms. The following examples show scripts that write a PIN of 1234 to stdout when initializing the JMS Keys certificate realm:
  4. Example hsmpin.bat file on Windows
  5. Example hsmpin.sh file on Linux/UNIX

Configure SSH key pairs

To configure public-private key pairs in the certificate store, select Environment Configuration > Certificates and Keys >Key Pairs . The Key Pairs window enables you to add, edit, or delete OpenSSH public-private key pairs, which are required for the Secure Shell (SSH) File Transfer Protocol (SFTP).

Add a key pair

To add a public-private key pair, click Add on the right, and configure the following settings in the dialog:

  • Alias:
    Enter a unique name for the key pair.
  • Algorithm:
    Enter the algorithm used to generate the key pair. Defaults to RSA .
  • Load:
    Click to select the public key or private key files to use. The Fingerprint field is auto-populated when you load a public key.
Note   The keys must be OpenSSH keys. RSA keys are supported, but DSA keys are not supported. The keys must not be passphrase protected.

Edit a key pair

To edit a public-private key pair, select a key pair alias in the table, and click Edit on the right. For example, you can load a different public key and private key. Alternatively, double-click a key pair alias in the table to edit it.

You can delete a selected key pair from the certificate store by clicking Remove on the right. Alternatively, click Remove All.

Manage OpenSSH keys

You can use the ssh-keygen command provided on UNIX to manage OpenSSH keys. For example:

  • The following command creates an OpenSSH key:
  • The following command converts an ssh.com key to an OpenSSH key:
  • The following command removes a passphrase (enter the old passphrase, and enter nothing for the new passphrase):
  • The following command outputs the key fingerprint:

Configure PGP key pairs

To configure Pretty Good Privacy (PGP) key pairs in the certificate store, select Environment Configuration > Certificates and Keys > PGP Key Pairs. The PGP Key Pairs window enables you to add, edit, or delete PGP public-private key pairs.

Add a PGP key pair

To add a PGP public-private key pair, click the Add on the right, and configure the following settings in the dialog:

  • Alias:
    Enter a unique name for the PGP key pair.
  • Load:
    Click Load to select the public key and private key files to use.
Note   The PGP keys added must not be passphrase protected.

Edit a PGP key pair

To edit a PGP key pair, select a key pair alias in the table, and click Edit on the right. For example, you can load a different public key and private key. Alternatively, double-click a key pair alias in the table to edit it.

You can delete a selected PGP key pair from the certificate store by clicking Remove on the right. Alternatively, click Remove All.

Manage PGP keys

You can use the freely available GNU Privacy Guard (GnuPG) tool to manage PGP key files (available from http://www.gnupg.org/). For example:

  • The following command creates a PGP key:
  • For more details, see http://www.seas.upenn.edu/cets/answers/pgp_keys.html
  • The following command enables you to view the PGP key:
  • The following command exports a public key to a file:
  • The following command exports a private key to a file:
  • The following command lists the private keys:

Global import and export options

This section describes global import and export options available when managing certificates and keys.

Import and export certificates and keys

The following global configuration options apply to both the X.509 Certificate and Private Key tabs:

  • Import Certificate + Key:
    Use this option to import a certificate and a key (for example, from a .p12 file).
  • Export Certificate + Key:
    Use this option to export a certificate and a key (for example, to a .p12 file).

Click OK when you have finished configuring the certificate and private key.

Manage certificates in Java keystores

You can also export a certificate to a Java keystore. You can do this by clicking Keystore on the main Certificates window. Click the browse button at beside the Keystore field at the top right to open an existing keystore, or click New Keystore to create a new keystore. Choose the name and location of the keystore file, and enter a passphrase for this keystore when prompted. Click Export to Keystore , and select a certificate to export.

Similarly, you can import certificates and keys from a Java keystore into the certificate store. To do this, click Keystore on the main Certificates window. On the Keystore window, browse to the location of the keystore by clicking the browse button beside the Keystore field. The certificates/keys in the keystore are listed in the table.

To import any of these keys to the certificate store, select the box next to the certificate or key to import, and click Import to Trusted certificate store. If the key is protected by a password, you are prompted for this password.

You can also use the Keystore window to view and remove existing entries in the keystore. You can also add keys to the keystore and to create a new keystore. Use the appropriate button to perform any of these tasks.

Further information

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

Related Links