Scenario: Creating a key-ring file

In this scenario, we can request a certificate and create a key-ring file.

Before you begin

• Before you start to use this scenario, make sure that we have completed the prerequisite tasks listed in Scenarios: Getting started with MQIPT.

This task assumes you request a new certificate from a trusted Certificate Authority (CA) by using 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 you 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 iKeyman command-line interface (CLI) or the iKeyman GUI to request the certificate.

Procedure

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

• Use the iKeyman command-line interface (CLI)
  1. Create a new PKCS#12 file:

     mqiptKeycmd -keydb -create -db server_name.pfx -pw key_password -type key_type
     

     where:
     • -db specifies the file (server_name.pfx) that corresponds to the key-ring property of the MQIPT route. For example, use SSLClientKeyRing for an SSLClient route and SSLServerKeyRing for an SSLServer route.
     • -pw specifies the password (key_password) that you must use later with the mqiptPW utility to store the encrypted key-ring password.
     • -type specifies the format of the key database; for example, pkcs12.
  2. Generate a new certificate request:

     mqiptKeycmd -certreq -create -db server_name.pfx -pw key_password -type key_type
                 -file cert_file_name.req -label label -dn DN_identity
                 -sig_alg signature_algorithm -size key_size
     

     where:
     • -type specifies the format of the key database; for example, pkcs12.
     • -file specifies a file name for the requested certificate.
     • -label specifies a unique name of your 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 your 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, add it into the server key ring:

     mqiptKeycmd -cert -receive -db server_name.pfx -pw key_password
                 -type key_type -file cert_file_name.crt
     

• Use the iKeyman GUI
  1. Open the iKeyman GUI by running the following command:

     mqiptKeyman

  2. Click Key database file > New.
  3. Select the type of the key database; for example, PKCS12.
  4. Enter the file name and location for the new key-ring file. This must correspond to the key-ring property of the MQIPT route; for example, use SSLClientKeyRing for an SSLClient route and SSLServerKeyRing for an SSLServer route. Click OK.
  5. Enter, and confirm, a password for the new key-ring file. This is the password that you must use later with the mqiptPW utility to store the encrypted key-ring password. 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 your 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, you 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

You 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. Check the contents of the sample CA key-ring file, sslCAdefault.pfx, by using iKeyman, to see if your personal certificates were signed by one of the listed CAs.

• If your personal certificates were signed by a listed CA, then we can use the sample CA key-ring file.
• If your personal certificates were signed by a different CA, you must create a key-ring file containing the public CA certificate of the CA that signed your personal certificates. This may have been returned with your personal certificate. If not, then you must request the CA certificate from the same CA that supplied your personal certificates and then add it to sslCAdefault.pfx.

If you need to add a CA certificate, we can use either the iKeyman CLI or the iKeyman GUI.

To add a CA certificate by using the iKeyman CLI:

mqiptKeycmd -cert -add -db sslCAdefault.pfx -pw key_password -type key_type
            -file ca_file_name.crt -label label

where:

• -db specifies the CA key-ring file, in this case sslCAdefault.pfx.
• -pw specifies the key-ring password.
• -type specifies the format of the key database; for example, pkcs12.
• -file specifies the name of the file returned by the CA.
• -label specifies a unique name of your 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.

To use these new key-ring files for server authentication, see the scenario Authenticating an SSL/TLS server, and set the following route properties:

SSLClientCAKeyRing=C:\\mqipt\\ssl\\sslCAdefault.pfx
SSLClientCAKeyRingPW=C:\\mqipt\\ssl\\sslCAdefault.pwd
SSLServerKeyRing=C:\\mqipt\\ssl\\myServer.pfx
SSLServerKeyRingPW=C:\\mqipt\\ssl\\myServer.pwd
SSLServerCAKeyRing=C:\\mqipt\\ssl\\sslCAdefault.pfx
SSLServerCAKeyRingPW=C:\\mqipt\\ssl\\sslCAdefault.pwd

To use these new key-ring files for client and server authentication, see the scenario SSL/TLS client authentication, and set the following route properties:

SSLClientKeyRing=C:\\mqipt\\ssl\\myClient.pfx
SSLClientKeyRingPW=C:\\mqipt\\ssl\\myClient.pwd
SSLClientCAKeyRing=C:\\mqipt\\ssl\\sslCAdefault.pfx
SSLClientCAKeyRingPW=C:\\mqipt\\ssl\\sslCAdefault.pwd 
SSLServerKeyRing=C:\\mqipt\\ssl\\myServer.pfx
SSLServerKeyRingPW=C:\\mqipt\\ssl\\myServer.pwd 
SSLServerCAKeyRing=C:\\mqipt\\ssl\\sslCAdefault.pfx
SSLServerCAKeyRingPW=C:\\mqipt\\ssl\\sslCAdefault.pwd