Managing certificates on PKCS #11 hardware

We can manage digital certificates on cryptographic hardware that supports the PKCS #11 interface.

You must create a key database to prepare the IBM MQ environment, even if we do not intend to store certificate authority (CA) certificates in it, but will store all your certificates on your cryptographic hardware. A key database is necessary for the queue manager to reference in its SSLKEYR field, or for the client application to reference in the MQSSLKEYR environment variable. This key database is also required if you are creating a certificate request.

Procedure

To create a key database by using the iKeyman user interface, complete the following steps:
1. On UNIX and Linux systems, log in as the root user. On Windows systems, log in as Administrator or as a member of the MQM group.
2. Start the iKeyman user interface by running the strmqikm command.
3. Click Key Database File > Open.
4. Click Key database type and select PKCS11Direct.
5. In the File Name field, type the name of the module for managing your cryptographic hardware; for example, PKCS11_API.so.
  If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.
6. In the Location field, enter the path:
  - On UNIX and Linux systems, this might be /usr/lib/pksc11, for example.
  - On Windows systems, we can type the library name; for example, cryptoki.
  Click OK. The Open Cryptographic Token window opens.
7. In the Cryptographic Token Password field, type the password that you set when you configured the cryptographic hardware.
8. If your cryptographic hardware has the capacity to hold the signer certificates required to receive or import a personal certificate, clear both secondary key database check boxes and continue from step 12. If you require a secondary CMS key database to hold the signer certificates, select either Open existing secondary key database file or Create new secondary key database file.
9. In the File Name field, type a file name. This field already contains the text key.kdb. If your stem name is key, leave this field unchanged. If you specified a different stem name, replace key with your stem name. You must not change the .kdb suffix.
10. In the Location field, type the path, for example:
  - For a queue manager: /var/mqm/qmgrs/QM1/ssl
  - For an IBM MQ MQI client: /var/mqm/ssl
  Click OK. The Password Prompt window opens.
11. Enter a password.
  - If you selected Open existing secondary key database file in step 8, type a password in the Password field.
  - If you selected Create new secondary key database file in step 8:
    1. Type a password in the Password field, and type it again in the Confirm Password field.
    2. Select Stash the password to a file. Note that if we do not stash the password, attempts to start TLS channels fail because they cannot obtain the password required to access the key database file.
    3. Click OK. A window opens, confirming that the password is in file key.sth (unless you specified a different stem name).
12. Click OK. The Key database content frame displays.
To create a key database by using the command line, use either of the following commands:
- On UNIX, Linux, and Windows systems:
```
runmqckm -keydb -create -db filename -pw password -type cms -stash
```
- Use runmqakm:
```
runmqakm -keydb -create -db filename -pw password -type cms
-stash -fips -strong
```
where: