Use keystores and certificates

To provide transparent cryptographic protection to IBM MQ applications, Advanced Message Security uses the keystore file, where public key certificates and a private key are stored. On z/OS, a SAF key ring is used instead of a keystore file.

In Advanced Message Security, users and applications are represented by public key infrastructure (PKI) identities. This type of identity is used to sign and encrypt messages. The PKI identity is represented by the subject's distinguished name (DN) field in a certificate that is associated with signed and encrypted messages. For a user or application to encrypt their messages they require access to the keystore file where certificates and associated private and public keys are stored.

On Windows and UNIX the location of the keystore is provided in the keystore configuration file, which is keystore.conf by default. Each Advanced Message Security user must have the keystore configuration file that points to a keystore file. Advanced Message Security accepts the following format of keystore files: .kdb, .jceks, .jks.

The default location of the keystore.conf file is:

  • On UNIX and IBM i: $HOME/.mqs/
  • On Windows: %HOMEDRIVE%%HOMEPATH%\.mqs\keystore.conf

If we are using a specified keystore filename and location, we should use the following commands

  • For Java: java -D MQS_KEYSTORE_CONF = path/filename app_name
  • For C Client and Server:

    • On UNIX: export MQS_KEYSTORE_CONF = path /filename
    • On Windows: set MQS_KEYSTORE_CONF = path \filename


Protecting sensitive information in the keystore.conf file

In order to access keystore file sensitive information, such as passwords, we must supply tokens so that IBM MQ Advanced Message Security (AMS) can access the keystore and sign and encrypt messages.

We should protect the sensitive information contained in the keystore configuration file using the runamscred command provided with AMS. See Protecting passwords in Java for details on how to protect configuration files.

When protecting passwords, we should use a custom, strong encryption key. In order to access the passwords during runtime, this encryption key must be supplied to AMS.

There are two methods of supplying the location of the encryption key file, which are, through the:

  • amscred.keyfile configuration property in the keystore.conf file
  • MQS_AMSCRED_KEYFILE environment variable

See Advanced Message Security - Java for more information.


Related concepts