Manage certificates on PKCS #11 hardware

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


We 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 we are creating a certificate request.


Procedure

  • To create a key database by using the strmqikm (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. Open the Java security properties file, java.security.

      • On UNIX and Linux systems, the Java security properties file is located in the java/jre64/jre/lib/security subdirectory of the IBM MQ installation directory.
      • On Windows systems, the Java security properties file is located in the java\jre\lib\security subdirectory of the IBM MQ installation directory.

      If it's not already present in the file, add the IBMPKCS11Impl security provider. For example, by adding the following line:

      security.provider.12=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
    3. Start the user interface by running the strmqikm command.
    4. Click Key Database File > Open.
    5. Click Key database type and select PKCS11Direct.
    6. In the File Name field, type the name of the module for managing your cryptographic hardware; for example, PKCS11_API.so.

      If we are using certificates or keys stored on PKCS #11 cryptographic hardware, note that runmqckm and strmqikm 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 strmqikm and runmqckm programs are 32-bit on those platforms.

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

    8. Select the cryptographic device token label that we want to use to store the certificates.
    9. In the Cryptographic Token Password field, type the password that you set when you configured the cryptographic hardware.
    10. 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 14. 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.
    11. 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. We must not change the .kdb suffix.
    12. In the Location field, type the path, for example:

      Click OK. The Password Prompt window opens.

    13. Enter a password.

      • If you selected Open existing secondary key database file in step 10, type a password in the Password field.
      • If you selected Create new secondary key database file in step 10:
        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).

    14. Click OK. The Key database content frame displays.

  • To create a key database by using the command line, use either of the following commands:

    • Use runmqckm:
      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:

      -db filename
      Specifies the fully qualified file name of a CMS key database, and must have a file extension of .kdb.

      -pw password
      Specifies the password for the CMS key database.

      -type cms
      Specifies the type of database. (For IBM MQ, it must be cms.)

      -stash
      Saves the key database password to a file.

      -fips
      Specifies that the command is run in FIPS mode. When in FIPS mode, the ICC component uses algorithms that are FIPS 140-2 validated. If the ICC component does not initialize in FIPS mode, the runmqakm command fails.

      -strong
      Checks that the password entered satisfies the minimum requirements for password strength. The minimum requirements for a password are as follows:

      • The password must be a minimum length of 14 characters.
      • The password must contain a minimum of one lowercase character, one uppercase character, and one digit or special character. Special characters include the asterisk (*), the dollar sign ($), the number sign (#), and the percent sign (%). A space is classified as a special character.
      • Each character can occur a maximum of three times in a password.
      • A maximum of two consecutive characters in the password can be identical.
      • All characters are in the standard ASCII printable character set, within the range 0x20 - 0x7E.

Parent topic: Configure for cryptographic hardware on UNIX, Linux, and Windows