Using keystores and certificates with AMS

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.

[AIX, Linux, Windows]On AIX®, Linux®, and Windows, 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:
  • [AIX][IBM i][Linux]On IBM i, AIX and Linux: $HOME/.mqs/keystore.conf
  • [Windows]On Windows: %HOMEDRIVE%%HOMEPATH%\.mqs\keystore.conf
If you are using a specified keystore filename and location, you should specify this with the MQS_KEYSTORE_CONF environment variable, as shown in the following example commands:
  • For Java: java -DMQS_KEYSTORE_CONF=path/filename app_name
  • For a C client and server:
    • [AIX][Linux]On AIX and Linux: export MQS_KEYSTORE_CONF=path/filename
    • [Windows]On Windows: set MQS_KEYSTORE_CONF=path\filename
      Note: The path on Windows can, and should, specify the drive letter if more than one drive letter is available.

Protecting sensitive information in the keystore.conf file

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

You should protect the sensitive information contained in the keystore configuration file using the runamscred command provided with AMS. See Setting up AMS password protection for configuration files for details on how to protect configuration files.

When protecting passwords, you 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:

The order of precedence is MQS_AMSCRED_KEYFILE, followed by amscred.keyfile, and then the default key.