Requesting a personal certificate on AIX, Linux, and Windows

Follow this procedure to create a request for a personal certificate.

Note: IBM® MQ does not support SHA-3 or SHA-5 algorithms. You can use the digital signature algorithm names SHA384WithRSA and SHA512WithRSA because both algorithms are members of the SHA-2 family.

[Deprecated] The digital signature algorithm names SHA3WithRSA and SHA5WithRSA are deprecated because they are an abbreviated form of SHA384WithRSA and SHA512WithRSA respectively.

You can request a personal certificate by using the runmqakm or runmqktool (keytool) commands. If you need to manage SSL or TLS certificates in a way that is FIPS compliant, use the runmqakm command.

Not all digital certificates can be used with all CipherSpecs. Ensure that you create a certificate that is compatible with the CipherSpecs that you use. IBM MQ supports three different types of CipherSpec. For more information, see Interoperability of Elliptic Curve and RSA CipherSpecs.

To use the Type 1 CipherSpecs (those with names beginning ECDHE_ECDSA_) you must use the runmqakm command to create the certificate and you must specify an Elliptic Curve ECDSA signature algorithm parameter. For example, by specifying the parameter -sig_alg EC_ecdsa_with_SHA384.

If you are using cryptographic hardware, see Requesting a personal certificate for your PKCS #11 hardware.

Using runmqakm

Issue the following command to create a certificate request with the runmqakm command:

runmqakm -certreq -create -db filename -pw password -label label
         -dn distinguished_name -size key_size
         -file filename -fips -sig_alg algorithm

where:

-db filename

Specifies the fully qualified file name of a key repository. The key repository must already exist.

-pw password

Specifies the password for the key repository.

-label label

Specifies the certificate label. The certificate label is case-sensitive.

The label of a TLS certificate that is used by IBM MQ is either the value of the CERTLABL attribute if it is set, or the default ibmwebspheremq with the name of the queue manager or the IBM MQ MQI client user ID appended, all in lowercase. For more information, see Digital certificate labels, understanding the requirements.

-dn distinguished_name

Specifies the X.500 distinguished name enclosed in double quotation marks. At least one attribute is required in the distinguished name. You can supply multiple OU and DC attributes.

Note: The runmqakm command refers to the postal code attribute as POSTALCODE, not PC. Always specify POSTALCODE in the -dn parameter when you use the runmqakm command to request certificates with a postal code.

-size key_size

Specifies the key size.

This size ranges in value based on the key type:

For RSA signature algorithms (the default algorithm that is used if no -sig_alg is specified), the value can be 512, 1024, 2048, or 4096. An RSA key size less than 2048 bits is not permitted if the -fips parameter is enabled. The default RSA key size is 2048 bits.
For Elliptic Curve algorithms, the value can be 256, 384, or 512. The default Elliptic Curve key size depends upon the signature algorithm. For SHA256, it is 256; for SHA384, it is 384; and for SHA512, it is 512.

The value can be 512, 1024, or 2048.

-file filename

Specifies the file name for the certificate request.

-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 validated. If the ICC component does not initialize in FIPS mode, the runmqakm command fails.

-sig_alg

Specifies the hashing algorithm that is used when the certificate request is created. This hashing algorithm is used to create the signature that is associated with the certificate request. The value can be md5, MD5_WITH_RSA, MD5WithRSA, SHA_WITH_DSA, SHA_WITH_RSA, sha1, SHA1WithDSA, SHA1WithECDSA, SHA1WithRSA, sha224, SHA224_WITH_RSA, SHA224WithDSA, SHA224WithECDSA, SHA224WithRSA, sha256, SHA256_WITH_RSA, SHA256WithDSA, SHA256WithECDSA, SHA256WithRSA, SHA2WithRSA, sha384, SHA384_WITH_RSA, SHA384WithECDSA, SHA384WithRSA, sha512, SHA512_WITH_RSA, SHA512WithECDSA, SHA512WithRSA, SHAWithDSA, SHAWithRSA, EC_ecdsa_with_SHA1, EC_ecdsa_with_SHA224, EC_ecdsa_with_SHA256, EC_ecdsa_with_SHA384, or EC_ecdsa_with_SHA512.

The default value is SHA1WithRSA.

For more information about these parameters and the values that can be specified, see runmqakm -certreq.

Using runmqktool

Before you can create a certificate request with the runmqktool command, you must generate a key pair by using the runmqktool -genkeypair command. For more information about the runmqktool -genkeypair command, see Creating a self-signed personal certificate on AIX, Linux, and Windows.

Issue the following command to create a certificate request with the runmqktool command:

runmqktool -certreq -keystore filename -storepass password -alias label
           -file filename

where:

-keystore filename: Specifies the name of the key repository.
-storepass password: Specifies the key repository password.
-alias label: Specifies the certificate label. This is the certificate label that was specified when the key pair was generated. The certificate label is case-insensitive.
-file filename: Specifies the file name for the certificate request.

For more information about these parameters and the values that can be specified:

For version IBM MQ 9.4.3 and earlier, see certreq.
From IBM MQ 9.4.4, see The keytool Command.

What to do next

Submit a certificate request to a CA. When you receive the signed certificate from the CA, add the signed certificate into the key repository. For more information, see Receiving personal certificates into a key repository on AIX, Linux, and Windows.