+

Search Tips | Advanced Search

Create a key ring file

In this scenario, we can request a certificate and create a key ring file to allow MQIPT to use TLS.


Before starting

Before you start to use this scenario, make sure that we have completed the prerequisite tasks listed in Getting started with IBM MQ Internet Pass-Thru.

This task assumes you request a new certificate from a trusted Certificate Authority (CA) by using mqiptKeyman (iKeyman), and that your personal certificate is returned to you in a file (for example, server.cer). This is sufficient to perform server authentication. If you require client authentication we must request a second certificate (for example, client.cer) and perform the following steps twice, to create two key ring files.


About this task

We can use either the mqiptKeycmd command line interface (CLI) or the mqiptKeyman GUI to request the certificate. We should then specify the key ring file that contains the certificate in the SSLServerKeyRing or SSLClientKeyRing MQIPT route property, depending on whether the certificate is for use by inbound or outbound connections.


Procedure

Use one of the following methods to create a key ring file:

  • Use the mqiptKeycmd command line interface (CLI)
    1. Enter the following command to create a new PKCS #12 key ring file: 
      mqiptKeycmd -keydb -create -db server_name.pfx -pw password -type pkcs12
      where:

      • -db specifies the name of the key ring file (server_name.pfx).
      • -pw specifies the key ring password (password) that you must later encrypt using the mqiptPW command.

    2. Enter the following command to create a new certificate request: 
      mqiptKeycmd -certreq -create -db server_name.pfx -pw password -type pkcs12
            -file cert_file_name.req -label label -dn DN_identity
            -sig_alg signature_algorithm -size key_size
      where:

      • -file specifies a file name for the requested certificate.
      • -label specifies a unique name of our choice; it is preferable not to include space characters.
      • -dn specifies the appropriate Distinguished Name identity for the MQIPT route; for example, "CN=Test Certificate,OU=Sales,O=Example,C=US".
      • -sig_alg specifies the hash algorithm; for example, SHA256WithRSA.
      • -size specifies the size of the public key; for example, 2048.

      If we use the example values given, this 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 an appropriate public key encryption algorithm, key size, and digital signature algorithm for the organization's security needs. See Digital certificate considerations for MQIPT for more information.

      Send the certificate request file (cert_file_name.req) created by the command to your CA to be signed.

    3. When you receive the signed personal certificate from the CA, enter the following command to add the certificate to the server key ring: 
      mqiptKeycmd -cert -receive -db server_name.pfx -pw password
            -type pkcs12 -file cert_file_name.crt

  • Use the mqiptKeyman GUI
    1. Open the GUI by running the following command: 
      mqiptKeyman
    2. Click Key database file > New.
    3. Select the type of the key database, PKCS12.
    4. Enter the file name and location for the new key ring file. Click OK.
    5. Enter, and confirm, a password for the new key ring file. This is the key ring password that we must later encrypt using the mqiptPW command. Click OK to create the new personal-certificate key ring file.
    6. Create the certificate request by clicking Create > New Certificate Request.
    7. Enter a label for the new certificate in the Key Label field. The label can be any unique name you choose; it is preferable not to include space characters.
    8. Select the key size and digital signature algorithm as appropriate for the organization's security needs. See Digital certificate considerations for MQIPT for more information.
    9. Enter the appropriate Distinguished Name identity for the MQIPT route in the optional DN fields.
    10. Enter the file name for the certificate request to create, and click OK. The certificate request is generated and saved with the name you specify. Send this file to your CA to be signed.
    11. When you receive the signed personal certificate from the CA, we must receive it in the key ring file. In the "Key database content" panel select Personal Certificates from the drop-down list. Then click Receive.
    12. Enter the name of the file where the signed certificate is stored, then click OK.


What to do next

We must also ensure that the CA certificate of the CA that signed the personal certificate is present in the CA key ring file. Depending on your MQIPT configuration, the CA key ring file might be a different file from the personal certificate key ring file.

To use a separate CA key ring file, we can either use the sample CA key ring file named sslCAdefault.pfx that is supplied with MQIPT, or create a new PKCS #12 key ring file. You will need to add the public CA certificate of the CA that signed your personal certificates to the CA key ring, unless it is already present in the sample key ring file. The public CA certificate may have been returned with your personal certificate. If not, then we must request the CA certificate from the same CA that supplied your personal certificates and then add it to the key ring.

To add a CA certificate, we can use either the mqiptKeycmd CLI or the mqiptKeyman GUI.

To add a CA certificate by using the mqiptKeycmd CLI, issue the following command: 
mqiptKeycmd -cert -add -db sslCAdefault.pfx -pw password -type pkcs12
            -file ca_file_name.crt -label label
where:

  • -db specifies the CA key ring file name, in this case sslCAdefault.pfx.
  • -pw specifies the key ring password. The password for the sample CA key ring file named sslCAdefault.pfx is mqiptSample.
  • -file specifies the name of the file returned by the CA.
  • -label specifies a unique name of our choice; it is preferable not to use space characters.

To add a CA certificate by using the iKeyman GUI:

  • In the Key Database Content panel, select Signer Certificates from the drop-down list
  • Click Add.
  • Enter the name of the file containing the CA certificate, then click OK.
  • Enter a label for the CA certificate. The label can be any unique name you choose; it is preferable not to use space characters. Click OK.

Encrypt the key ring passwords by issuing the following command:

mqiptPW
Enter the key ring password to encrypt when prompted. Set the value of the appropriate property in the mqipt.conf configuration file to the encrypted password that is output by the mqiptPW command; for example, SSLServerKeyRingPW or SSLClientKeyRingPW, depending on whether the certificate is for use by inbound or outbound connections. For more information about encrypting key ring passwords, see Encrypting stored passwords to encrypt the key ring passwords. To use these new key ring files for server authentication, place the key ring files in a directory named ssl under the MQIPT home directory and set the following route properties:
SSLClientCAKeyRing=C:\\mqiptHome\\ssl\\sslCAdefault.pfx
SSLClientCAKeyRingPW=encrypted_password
SSLServerKeyRing=C:\\mqiptHome\\ssl\\myServer.pfx
SSLServerKeyRingPW=encrypted_password
SSLServerCAKeyRing=C:\\mqiptHome\\ssl\\sslCAdefault.pfx
SSLServerCAKeyRingPW=encrypted_password
See the scenario Authenticating a TLS server for more information on configuring MQIPT to use TLS. Parent topic: Getting started with IBM MQ Internet Pass-Thru

Last updated: 2020-10-04