Manage X.509 certificates and keys

Overview

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 tree. Certificates and keys are listed on the following tabs in the Certificates
window:

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.

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.

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

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:

Open a command prompt in the API Gatewaybin
directory (for example, apigateway\Win32\bin).

Enter the keystoreadmin
command.

Select option 3) Register an HSM provider.

If prompted, select the appropriate API Gateway group or instance.

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.

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:

Choose from one of the following:1) C:\LunaSA\cryptoki.dllo) Otherq) Quit

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:

Open a command prompt in the API Gatewaybin
directory (for example, apigateway\Win32\bin).

Enter the keystoreadmin
command.

Select option 5) Create a Certificate Realm.

You are prompted to enter a certificate realm name. This certificate realm name is used in when configuring the private key of the corresponding X.509 certificate. The realm name is case sensitive (for example, JMS Keys).

The registered HSMs are listed. For example, select option 1) HSM.

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

You are prompted to input the PIN passphrase for the slot. The passphrase will not echo any output.

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:

The keystore is output to the API Gateway instance directory. For example:

apigateway/groups/group-2/instance-1/conf/certrealms/jms keys.ks

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:

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:

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:

Example hsmpin.bat file on Windows

@echo off
IF [%1]==[] GOTO _END

::Strip out the double quotes around arg
SET REALM=%1
SET REALM=%REALM:"=%

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:

ssh-keygen -t rsa

The following command converts an ssh.com
key to an OpenSSH key:

ssh-keygen -i -f ssh.com.key > open.ssh.key

The following command removes a passphrase (enter the old passphrase, and enter nothing for the new passphrase):

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:

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.