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.

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.

Configuration file types

Table 1. Prefix needed for each configuration file type
File types	Prefix	Purpose	Supported environments
AMSCRED	amscred.	Parameters that relate to the password protection system	Default environment
CMS	cms.	Identify certificates in the Certificate Management System	C clients and MCA interception on distributed platforms (other than IBM i) use the CMS prefix to specify the necessary KeyStore location or certificate for AMS
PKCS#11	pkcs11.	Standard for cryptographic tokens	C clients and MCA interception on distributed platforms (other than IBM i) support the PKCS#11 prefix to provide the KeyStore location and certificates for AMS Java or JMS clients can also use this prefix in environments that require the PKCS#11-compliant hardware or software KeyStores
PEM	pem.	Standard format for storing cryptographic keys and certificates	C clients on IBM i use the PEM prefix to specify the keystore location or certificate
JKS	jks.	Java KeyStore format for storing cryptographic keys and certificates	A Java or JMS client can use the JKS prefix to specify the KeyStore for AMS
JCEKS	jceks.	A more secure Java KeyStore, supporting stronger encryption	A Java or JMS client can use the JCEKS prefix to configure AMS
JCERACFKS	jceracfks.	A keying KeyStore specific to the RACF security system used on z/OS®	A Java or JMS client on z/OS system uses this prefix to specify the RACF KeyStore for 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 
pkcs11.encrypted = no

PEM

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

Java JKS

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

Java JCEKS

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

Java JCERACFKS

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

Java PKCS#11

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

Parameters

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

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.

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

You should protect this field using the native AMS password protection tool; see Protecting passwords

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.

For Java operations only; you should protect this field using the Java AMS password protection tool; see Protecting passwords.

For Native operations only; you should protect this field using the native AMS password protection tool; see Protecting passwords.

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.

For Java environments a JKS keystore is required and you must provide a secondary_keystore_password.

secondary_keystore_password

Java PKCS#11 only.

Password for the JKS keystore provided through the secondary_keystore property. You should protect this field using the Java AMS password protection tool; see Protecting passwords.

encrypted

Java and, from IBM MQ 9.3.0, PKCS#11 and [IBM i]

PEM only.

Status of the password.

keystore_pass

Java configuration only.

Password for the keystore file.

For Java operations only. You should protect this field using the Java AMS password protection tool; see Protecting passwords.

key_pass

Java configuration only.

Password for the private key of the user.

For Java operations only; you should protect this field using the Java AMS password protection tool; see Protecting passwords.

keyfile

Provides the location of the initial key to use when protecting or decrypting passwords contained in this configuration file; see Protecting passwords

provider

Java configuration only.

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

fips

CMS, PKCS#11 and Java configuration only.

Enables and enforces FIPS requirements for cryptographic operations. For more information see FIPS mode in AMS.

forceFipsOff

CMS configuration only.

MCA Interception mode only.

Stops fips mode from automatically upgrading policies to meet FIPS requirements. For more information see FIPS mode in AMS.

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.

Protecting passwords

You should protect the passwords and other sensitive information contained in the keystore.conf file. For more information, see runamscred.

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