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:
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]AMSCRED
Parameters that relate to the password protection system.
CMS
Certificate Management System, configuration entries are prefixed with: cms.
PKCS#11
Public Key Cryptography Standard #11, configuration entries are prefixed with: pkcs11.
[IBM i]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.
[IBM MQ Advanced VUE][z/OS]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 
[MQ 9.2.2 Mar 2021]pkcs11.encrypted = no
[IBM i]PEM

pem.private = /dir/keystore_file_private_key
pem.public = /dir/keystore_file_public_keys
pem.password = password 
[MQ 9.2.2 Mar 2021]pem.encrypted = no
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
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
Table 1. Summary of parameters needed for each configuration file type
Parameters Required Configuration file type
Java (PKCS#11, JKS, JCEKS, and JCERACFKS) [IBM i]PEM PKCS#11 CMS AMSCRED
keystore X X     X  
[IBM i]private X   [IBM i]X      
[IBM i]public X   [IBM i]X      
[IBM i]password X   [IBM i]X      
library X X   X    
certificate X X   X X  
token X X   X    
token_pin X X   X    
secondary_keystore X X   X    
secondary_keystore_password X X        
encrypted   X [IBM i][MQ 9.2.2 Mar 2021]X [MQ 9.2.2 Mar 2021]X    
keystore_pass X X        
key_pass   X        
provider   X        
keyfile           XYou

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.
  • [IBM MQ Advanced VUE][z/OS] 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.
[IBM i]private
PEM configuration only.
File name of a file that contains private key and certificate in PEM format.
[IBM i]public
PEM configuration only.
File name of a file that contains trusted public certificates in PEM format.
[IBM i]password
PEM configuration only.
Password that is used to decrypt an encrypted private key.
[MQ 9.2.2 Mar 2021]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.
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]For Java operations only; you should protect this field using the Java AMS password protection tool; see Protecting passwords.
[MQ 9.2.2 Mar 2021]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
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]Java configuration only.
[MQ 9.2.2 Mar 2021]Java, PKCS#11, and [IBM i]PEM configuration only.
Status of the password.
keystore_pass
Java configuration only.
Password for the keystore file.
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]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.
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]For Java operations only; you should protect this field using the Java AMS password protection tool; see Protecting passwords.
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]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.
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.
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]

Protecting passwords

You should protect the passwords and other sensitive information contained in the keystore.conf file. See runamscred for more information.

Example of the keystore.conf file: [MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]

# 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