Structure of the configuration file

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

Each of the following configuration file types has a prefix:

    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.

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

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

Parameters Configuration file type
Java (JKS, JCEKS, and JCERACFKS) PEM PKCS#11 CMS AMSCRED
keystore        
private        
public        
password        
library        
certificate    
token        
token_pin        
secondary_keystore        
encrypted        
keystore_pass        
provider        
keyfile        
Configuration file parameters are defined as follows:

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

    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.
    For Java operations only; we should protect this field using the Java 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.

    encrypted
    Java configuration only. Status of the password.

    keystore_pass
    Java configuration only. Password for the keystore file.
    For Java operations only; we should protect this field using the Java AMS password protection tool; see Protecting passwords.

    key_pass
    Java configuration only. Password for the user's private key.
    For Java operations only; we should protect this field using the Java AMS password protection tool; see Protecting passwords.

    keyfile
    Java configurations only. 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.

See GSKit: Commands renamed.


Protecting passwords

We 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: 
cms.keystore = c:\Documents and Settings\Alice\AliceKeystore
cms.certificate = AliceCert

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


Related tasks