mqiptKeyman and mqiptKeycmd

mqiptKeyman (iKeyman) is a certificate and key management application that is already familiar to IBM MQ users. The mqiptKeyman and mqiptKeycmd commands can be used to manage symmetric and asymmetric keys, digital certificates, and certificate requests in key ring files used by IBM MQ Internet Pass-Thru. These files can also be used to manage the key ring files themselves.

mqiptKeyman and mqiptKeycmd use the term key database to refer to a key ring file; these terms are synonymous.

iKeyman can be run in two modes, graphical user interface (GUI) and command-line interface (CLI). Use the mqiptKeyman command to start the GUI and the mqiptKeycmd command to run the CLI.

The equivalent commands for managing certificates in IBM MQ are strmqikm to start the GUI, and runmqckm to run the CLI. The IBM MQ commands are described in Use runmqckm, runmqakm, and strmqikm to manage digital certificates.

Required key ring file format for MQIPT

When creating key ring files for use in MQIPT, you must use the PKCS #12 file format:

In the UI, select PKCS#12 in the Key database type field when creating the key ring file.
In the CLI, include the -type pkcs12 parameter on the mqiptKeycmd -keydb -create command.

MQIPT can also access certificates stored in cryptographic hardware that supports the PKCS #11 interface. The interface can also be used to manage certificates on PKCS #11 hardware. For more information, see Use PKCS #11 cryptographic hardware.

Encrypting the key ring password for MQIPT

After creating the key ring file, we must encrypt the key ring password in a format which MQIPT can use to access the file. See Encrypting a key ring password for information about this.

Note that the stash file facility is not supported by MQIPT. We must use the mqiptPW command to encrypt the key ring password instead of using a stash file.

Command line examples

The CLI uses the same syntax as the IBM MQ runmqckm command. Append the required parameters to mqiptKeycmd, as illustrated in the following examples:

To create a PKCS#12 file:

mqiptKeycmd -keydb -create -db key.p12 -pw password -type pkcs12

To create a self-signed personal certificate for testing purposes:
```
mqiptKeycmd -cert -create -db key.p12 -pw password -type pkcs12 
-label mqipt -dn "CN=Test Certificate,OU=Sales,O=Example,C=US"
-sig_alg SHA256WithRSA -size 2048
```
The command creates a digital certificate with a 2048-bit RSA public key and a digital signature that uses RSA with the SHA-256 hash algorithm. When creating a certificate, take care to choose a public key encryption algorithm, key size, and digital signature algorithm that are appropriate for your organization's security needs. See Digital certificate considerations for MQIPT for more information.
This example uses a self-signed certificate that is suitable for test purposes. However, in a production environment we should use a Certificate Authority signed certificate instead.

Note that MQIPT v2.0 and older versions do not support SHA-2 digital signatures, so this certificate is not suitable for establishing secure socket connections to previous MQIPT releases; an older signature algorithm, such as SHA1WithRSA, would be required.
To create a certificate request for a CA signed certificate for production purposes:
```
mqiptKeycmd -certreq -create -db key.p12 -pw password -type pkcs12 -file cert.req 
-label mqipt -dn "CN=Test Certificate,OU=Sales,O=Example,C=US" 
-sig_alg SHA256WithRSA -size 2048
```
The command creates a digital certificate request with a 2048-bit RSA public key and a digital signature that uses RSA with the SHA-256 hash algorithm. When creating a certificate, take care to choose a public key encryption algorithm, key size, and digital signature algorithm that are appropriate for the organization's security needs. See Digital certificate considerations for MQIPT for more information.
To receive the CA signed personal certificate file cert.crt into the key ring file:
```
mqiptKeycmd -cert -receive -db key.p12 -pw password -type pkcs12 -file cert.crt
```
We must ensure that the CA certificate of the CA which signed the personal certificate is present in the CA key ring file, for example:
```
mqiptKeycmd -cert -add -db key.p12 -pw password -type pkcs12 -file ca.crt -label rootCA
```

Digital certificate considerations for MQIPT

Parent topic: SSL/TLS support