Structure of the keystore configuration file (keystore.conf) for AMS

The keystore configuration file (keystore.conf) points Advanced Message Security to the location of the appropriate keystore.

Each of the following configuration file types has a prefix:

CMS: Certificate Management System, configuration entries are prefixed with: cms.
PKCS#11: Public Key Cryptography Standard #11, configuration entries are prefixed with: pkcs11.
PEM: Privacy Enhanced Mail format, configuration entries are prefixed with: pem.
JKS: Java KeyStore, configuration entries are prefixed with: jks.
JCEKS: Java Cryptographic Encryption KeyStore, configuration entries are prefixed with: jceks.

JCERACFKS: Java Cryptographic Encryption RACF keyring KeyStore, configuration entries are prefixed with: jceracfks.

Important: From IBM® MQ 9.0 the JCEKS.provider and JKS.provider values are ignored. The Bouncy Castle provider is used, in conjunction with whichever JCE/JCE provision is supplied by the JRE in use. For more information, see Support for non-IBM JREs with AMS.

Example structures for keystores:

CMS


cms.keystore = /dir/keystore_file
cms.certificate = certificate_label

PKCS#11


pkcs11.library = dir\cryptoki.dll
pkcs11.certificate = certificatelabel
pkcs11.token = tokenlabel
pkcs11.token_pin = tokenpin
pkcs11.secondary_keystore = dir\signers

PEM


pem.private = /dir/keystore_file_private_key
pem.public = /dir/keystore_file_public_keys
pem.password = password

Java JKS


jks.keystore = dir/Keystore
jks.certificate = certificate_label
jks.encrypted = no
jks.keystore_pass = password
jks.key_pass = password
jks.provider = IBMJCE

Java JCEKS


jceks.keystore = dir/Keystore
jceks.certificate = certificate_label
jceks.encrypted = no
jceks.keystore_pass = password
jceks.key_pass = password
jceks.provider = IBMJCE

Java JCERACFKS


jceracfks.keystore = safkeyring://user/keyring
jceracfks.certificate = certificate_label

Table 1. Summary of parameters needed for each configuration file type
Parameters	Required	Configuration file type
Parameters	Required	Java (JKS, JCEKS, and JCERACFKS)	PEM	PKCS#11	CMS
`keystore`
`private`
`public`
`password`
`library`
`certificate`
`token`
`token_pin`
`secondary_keystore`
`encrypted`
`keystore_pass`
key_pass
`provider`

Note that you can add comments using the # symbol.

Configuration file parameters are defined as follows:

keystore

CMS and Java configuration only. Path to the keystore file for CMS, JKS, and JCEKS configuration.

[V9.0.5 Mar 2018] [IBM MQ Advanced VUE] [z/OS] URI to the RACF keyring for JCERACFKS configuration.

Important:

The path to the keystore file must not include the file extension.
The URI to the RACF keyring must be in the form:
```
safkeyring://user/keyring
```
where:
- user is the user id that owns the keyring
- keyring is the keyring name.

private

PEM configuration only. File name of a file that contains private key and certificate in PEM format.

public

PEM configuration only. File name of a file that contains trusted public certificates in PEM format.

password

PEM configuration only. Password that is used to decrypt an encrypted private key.

library

PKCS#11 only. Path name of the PKCS#11 library.

certificate

CMS, PKCS#11 and Java configuration only. Certificate label.

token

PKCS#11 only. Token label.

token_pin

PKCS#11 only. PIN to unlock the token.

secondary_keystore

PKCS#11 only. Path name of the CMS keystore, provided without the .kdb extension, that contains anchor certificates (root certificates) required by certificates stored on the PKCS #11 token. The secondary keystore can also contain certificates that are intermediate in the trust chain, as well as recipient certificates that are defined in the privacy security policy. This CMS keystore must be accompanied by a stash file which must be located in the same directory as the secondary keystore.

encrypted

Java configuration only. Status of the password.

keystore_pass

Java configuration only. Password for the keystore file.

Note:

For the CMS keystore, AMS relies on the stash files (.sth), whereas JKS and JCEKS might require a password for both the certificate and the user's private key.
Important: Storing passwords in plain text form is a security risk.

Note: Ignored for jceracfks as access is not controlled by a password.

key_pass

Java configuration only. Password for the user's private key.

Important: Storing passwords in plain text form is a security risk.

Note: Ignored for jceracfks as access is not controlled by a password.

provider

Java configuration only. The Java security provider that implements cryptographic algorithms required by the keystore certificate.

Important: Information that is stored in the keystore is crucial for the secure flow of data that is sent by using IBM MQ. Security administrators must pay particular attention when they are assigning file permissions to these files.

Example of the keystore.conf file:


# Native AMS application configuration
cms.keystore = c:\Documents and Settings\Alice\AliceKeystore
cms.certificate = AliceCert

# Java AMS application configuration
jceks.keystore = c:/Documents and Settings/Alice/AliceKeystore
jceks.certificate = AliceCert
jceks.encrypted = no
jceks.keystore_pass = passw0rd
jceks.key_pass = passw0rd
jceks.provider = IBMJCE