Using Keystores and Truststores with Integration Server

Keystores and Truststores

Integration Server stores its private keys and SSL certificates in keystore files and the trusted roots for the certificates in truststore files. Keystores and truststores are secure files with industry-standard file formats.

Keystore File

Integration Server uses a special file called a keystore to store SSL certificates and keys.

A keystore file contains one or more pairs of a private key and signed certificate for its corresponding public key. The keystore should be strongly protected with a password, and stored (either on the file system or elsewhere) so that it is accessible only to administrators.

Keystore File Formats

The default, certificate file format for an Integration Server keystore is JKS (Java keystore), the proprietary keystore implementation provided by Oracle. You can also use PKCS12, a commonly used, standardized, certificate file format that provides a high degree of portability. Other keystore types can be made available by:

Loading additional security providers
Setting the watt.security.keyStore.supportedTypes property.

HSM-Based Keystores

Under certain conditions, Integration Server supports the use of keystore files stored on a Hardware Security Module (HSM). Integration Server supports HSM-based keystores for ports, but not for other components. You cannot use HSM-based keystores with remote server aliases, outbound certificates, an internal server port, WS-Security, or Integration Server public services.

Only nCipher hardware card modules are currently supported.

Creating a Keystore

You can create and manage Integration Server keystores at the command line using keytool, the Oracle Java certificate editor.

You can also use other standard tools such as OpenSSL and Portecle.

Note: Software AG does not provide its own set of keystore utilities for creating or managing keystore files.

Truststore File

Integration Server uses a truststore to store its trusted root certificates, which are the public keys for the signing CAs. Although a truststore can contain the trusted roots for entire certificate chains, there is no requirement for the organization of certificates within an Integration Server truststore. It simply functions as a database containing all the public keys for CAs within a specified trusted directory.

Truststore File Formats

The default format for a truststore is Java keystore (JKS). JKS is the proprietary keystore implementation provided by Oracle. You can create and manage JKS truststores at the command line using keytool, the Oracle Java certificate editor.

How Integration Server Uses a Keystore and Truststore

For an Integration Server component to be SSL authenticated, it must have a valid, authorized X.509 certificate installed in a keystore file and the private key and signing certificate for the certificate issuer (CA) installed in a truststore file. The following figure illustrates these requirements and the relationship between the two files.

relationship between truststore file and keystore file — Figure 1. Example Truststore File and Keystore File Showing Relationship

As shown in the above figure, the same truststore file can contain multiple trusted root certificates (public keys for the signing CAs). These trusted roots might be associated with numerous keystore files. A keystore file can contain the key pairs for multiple Integration Server components, and the entire certificate chain required for a component's authentication.

With a certificate chain, it is necessary to validate each subsequent signature in the list until a trusted CA certificate is reached. For Integration Server, you must include the entire chain of certificates in a keystore and truststore. Also, any root CA certificates in use by clients must be in an Integration Server truststore.

Protecting Keystore and Truststore Files

Keystore and truststore files exist within the file system of your operating system, and since these are critically important files, you want to maintain them in a secure directory path. If either of the these files cannot be located, Integration Server authentication will be disabled and no connection with the server can be made. It is recommended that only users serving as My webMethods or Integration Server administrators have access to these certificate files.

Keystore, Truststore, and Key Aliases

To identify a particular keystore or truststore file, or private key within a keystore, Integration Server uses aliases. This use of aliases is the same as that by Java keytool and other certificate management tools. The use of aliases simplifies keystore and truststore management, because you do not need to enter path information when specifying a keystore, truststore, or private key in Integration Server Administrator or when using Integration Server public services.

You can view, create, and edit keystore and truststore aliases from the Security > Keystore panel in Integration Server Administrator.

Note: Keystore and truststore aliases are not case-sensitive.

A key alias is a label for specific key within a keystore. Key aliases are created using your third-party certificate management tool. Although you do not create key aliases in Integration Server Administrator, you will need to identify which keys to use for SSL authentication, signing, and decrypting, by selecting the appropriate key aliases in Integration Server Administrator.

Default Keystore and Truststore Aliases

Integration Server creates default keystore and truststore aliases the first time Integration Server starts.

Important: Use these aliases only in development environments where testing and debugging is performed. Do not use these aliases in a production environment.

The following table lists the predefined keystore and truststore aliases for Integration Server.

Default Alias	Description
DEFAULT_IS_ KEYSTORE	The name of the default keystore alias for Integration Server. The DEFAULT_IS_KEYSTORE points to the `Software AG_directory` /common/conf/keystore.jks file.and the default password is “manage” for all the entries.
DEFAULT_IS_ TRUSTSTORE	The name of the default truststore alias for Integration Server. The DEFAULT_IS_TRUSTSTORE points to `Software AG_directory` /common/conf/platform_truststore.jks file and the default password is “manage” for all the entries.

You can edit and delete the default aliases. The certificate file format of the default keystore and truststore is Java keystore (JKS). The provider for the default keystore and truststore alias is the one shipped with the JVM.

Creating Keystore Aliases

About this task

The following procedures shows how to assign aliases to keystore files that you have created with the Oracle Java keytool or with another third-party certificate tool.

To create an alias for a keystore file

Procedure

Open the Integration Server Administrator if it is not already open.
In the Security menu of the Navigation panel, click Keystore.
Click Create Keystore Alias.

Enter the Keystore Properties settings as follows:

For this setting	Specify
Alias	A text identifier for the keystore file. The keystore contains the private keys and certificates (including the associated public keys) for an Integration Server, partner application, or Integration Server component.
Description	Optional. A text description for the keystore alias.
Type	The certificate file format of the keystore file, which by default is JKS for keystores. You can also use PKCS12 format for a keystore. Other keystore types can be made available by: Loading additional security providers. Setting the watt.security.keyStore.supportedTypes server configuration parameter.
Provider	The provider that is used for the keystore or truststore type. The default provider is the one shipped with the JVM, which can be Oracle, IBM, or others. Generally, you should specify a provider only if your HSM device is not supported by the default provider. You can configure a different provider to support keystore types other than the default. Integration Server supports both PKCS12 and JKS for keystores, but only supports JKS for truststores.
Location	Path location of the keystore file on the server. You can specify the full-path name, or a relative path in relation to the Integration Server.
Password / Re-type Password	Password for the saved keystore file associated with this alias. If the keystore requires a password, the password must have been defined at keystore creation time using a keystore utility. Once you create the keystore alias, the keystore password is automatically saved as an Integration Server outbound password. Make sure you have the keystore password available when managing its corresponding keystore alias. If the keystore does not require a password, leave the fields empty.
HSM-based Keystore	Indicates whether the keystore file is stored on a Hardware Security Module (HSM) device. Only nCipher hardware card modules are currently supported. If you select this option, no path is specified in the Location field.

Click Submit.

Enter the Key Aliases settings as follows:

For this setting	Specify
Password / Re-type Password	Password for each alias found in the keystore. Most aliases require a password. If Integration Server needs to use this alias for any reason, you must provide its password.
Null	Indicates that no password is required for the alias. Select this for an alias in the keystore that is not secured with a password.

For this setting

Specify

Password / Re-type Password

Password for each alias found in the keystore.

Most aliases require a password. If Integration Server needs to use this alias for any reason, you must provide its password.

Null

Indicates that no password is required for the alias.

Select this for an alias in the keystore that is not secured with a password.

Click Save Changes.

Creating Truststore Aliases

About this task

The following procedures shows how to assign aliases to truststore files.

To create an alias for a truststore file

Procedure

Open the Integration Server Administrator if it is not already open.
In the Security menu of the Navigation panel, click Keystore.
Click Create Truststore Alias.

Enter the Truststore Properties settings as follows:

For this setting	Specify
Alias	A text identifier for the truststore file. The truststore contains the trusted CA certificates for an Integration Server, partner application, or Integration Server component.
Description	Optional. A text description for the truststore alias.
Type	The certificate file format of the truststore, which by default is JKS. Other truststore types can be made available by: Loading additional security providers. Setting the watt.security.trustStore.supportedTypes server configuration property.
Provider	The provider that is used for the truststore type. The default provider is the one shipped with the JVM, which can be Oracle, IBM, or others. Specify a provider only if your HSM device is not supported by the default provider. You can configure a different provider to support keystore types other than the default (JKS); however, Software AG does not provide support for their use.
Location	Path location of the truststore file on the server. You can specify the full-path name, or a relative path in relation to the Integration Server.
Password / Re-type Password	Supplied password that is used to protect the contents of the truststore. This password must have been defined at truststore creation time using a keystore utility. Once you create the truststore alias, its password is automatically saved as an Integration Server outbound password. Make sure you have the truststore password available when managing its corresponding truststore alias.

Click Save Changes.