Managing certificates on PKCS #11 hardware

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

Create a key database by using the command line.

1. Run either of the following commands:
   • Using runmqckm:

     
     runmqckm -keydb -create -db filename -pw password -type cms -stash
     

   • Using 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 IBM Crypto for C (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.

Alternatively, create a key database by using the strmqikm (iKeyman) user interface.

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

4. Start the user interface by running the strmqikm command.
5. Click Key Database File > Open.
6. Click Key database type and select PKCS11Direct.
7. 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.

8. In the Location field, enter the path:
   • On UNIX and Linux systems, this might be /usr/lib/pksc11, for example.
   • On Windows systems, you can type the library name; for example, cryptoki.
   Click OK. The Open Cryptographic Token window opens.
9. Select the cryptographic device token label that you want to use to store the certificates.
10. In the Cryptographic Token Password field, type the password that you set when you configured the cryptographic hardware.
11. 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 15.
    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.
12. 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.
13. 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.
14. Enter a password.

    If you selected Open existing secondary key database file in step 11, type a password in the Password field.

    If you selected Create new secondary key database file in step 11, complete the following sub steps:

    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 you 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).
15. Click OK. The Key database content frame displays.