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:
- 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:
CMScms.keystore = /dir/keystore_file cms.certificate = certificate_labelPKCS#11
pkcs11.library = dir\cryptoki.dll pkcs11.certificate = certificatelabel pkcs11.token = tokenlabel pkcs11.token_pin = tokenpin pkcs11.secondary_keystore = dir\signersPEM
pem.private = /dir/keystore_file_private_key pem.public = /dir/keystore_file_public_keys pem.password = passwordJava JKS
jks.keystore = dir/Keystore jks.certificate = certificate_label jks.encrypted = no jks.keystore_pass = password jks.key_pass = password jks.provider = IBMJCEJava 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 | |
keystore | ||||
private | ||||
public | ||||
password | ||||
library | ||||
certificate | ||||
token | ||||
token_pin | ||||
secondary_keystore | ||||
encrypted | ||||
keystore_pass | ||||
provider |
- 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.
- 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.
- key_pass
- Java configuration only. Password for the user's private key. Important: Storing passwords in plain text form is a security risk.
- provider
- Java configuration only. The Java security provider that implements cryptographic algorithms required by the keystore certificate. Note: Currently, IBMJCE is the only provider that is supported by Advanced Message Security.
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.
For more information about managing the keystore by using GSKit commands, see GSKit: Commands renamed.
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