Using PKCS #11 cryptographic hardware in MQIPT

MQIPT can access digital certificates that are stored in cryptographic hardware that supports the PKCS #11 interface.

Before you begin

Before you begin to configure MQIPT to use cryptographic hardware, ensure that the cryptographic card, the card driver, and any associated support software are installed and functioning properly.

Support for PKCS #11 cryptographic hardware in MQIPT is provided by the IBM® Java PKCS11 Cryptographic Provider (IBMPKCS11Impl provider). For more information on the IBMPKCS11Impl provider, and the list of cryptographic cards that are supported by Java 8, see IBM PKCS11 Cryptographic Provider.

About this task

You can store the personal certificates and CA certificates that are accessed by MQIPT in a cryptographic hardware key store. However, as a PKCS #11 device normally does not enough space available to store a large amount of signer certificates, you might want to use a separate file-based key store for CA certificates.

Follow this procedure to configure MQIPT to use certificates in a cryptographic hardware key store.

Note: The use of cryptographic hardware with MQIPT is an IBM MQ Advanced capability. To use this capability, the local queue manager that is connected using the MQIPT route is also required to have IBM MQ Advanced, IBM MQ Appliance, IBM MQ Advanced for z/OS® VUE, or IBM MQ Advanced for z/OS entitlement.

Procedure

Create the configuration file that is used when initializing the IBMPKCS11Impl provider.
Download sample configuration files for each of the hardware cryptographic cards that are supported by the IBMPKCS11Impl provider, and configure a sample for your system. The samples can be downloaded from the following topic in the IBM Documentation for Java: Configuration file.
The configuration file is a text file, and should contain at least the following attributes:

name

The name suffix of the provider instance.

library

The fully-qualified name of the PKCS #11 library that is supplied with the cryptographic hardware.

tokenlabel

The PKCS #11 cryptographic device token label.
For example, the configuration file could contain the following entries:
```
name = IPTPKCS11Provider
library = /usr/lib64/pkcs11/PKCS11_API.so
tokenlabel = icatoken
```
Edit the Java security properties file, java.security, located in the java/jre/lib/security subdirectory of the MQIPT installation directory.
1. 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
```
2. Add the fully-qualified name of the configuration file after the provider name.
  For example, if the configuration file you created in step 1 is called /opt/mqipt/pkcs11.cfg, you should add this path to the same line as the security provider:
```
security.provider.12=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /opt/mqipt/pkcs11.cfg
```
If you are using a key ring file for CA certificates, instead of storing CA certificates in the cryptographic hardware, create a PKCS #12 format CA key ring file.
You can create a CA key ring file by using either the mqiptKeyman graphical user interface (GUI) or mqiptKeycmd command line interface (CLI).
- To use the CLI, enter the following command:
```
mqiptKeycmd -keydb -create -db filename -pw password -type pkcs12
```
  where filename is the name of the key ring file to create, and password is the key ring password.
- To use the GUI, follow these steps:
  1. Start the GUI by entering the command mqiptKeyman.
  2. Click Key Database File > Open.
  3. Click Key database type and select PKCS11Config.
  4. Click OK. The Open Cryptographic Token window opens.
  5. Select the cryptographic device token label that you want to use to store the certificates.
  6. In the Cryptographic Token Password field, type the password needed to access the cryptographic hardware.
  7. To create a new CA key ring file, select Create new secondary key database file.
  8. Click Key database type and select PKCS12.
  9. In the File Name field, type the file name of the CA key ring.
  10. In the Location field, type the full path to the CA key ring file.
  11. Click OK. The Password Prompt window opens.
  12. Type a password for the CA key ring in the Password field, and type it again in the Confirm Password field.
  13. Click OK.
Using mqiptKeycmd or mqiptKeyman, request a personal certificate for the cryptographic hardware.
- To use the CLI, enter the following command:
```
mqiptKeycmd -certreq -create -crypto module_name -tokenlabel hardware_token
            -pw password -label label -size key_size
            -sig_alg algorithm -dn distinguished_name -file filename
```
  where:
  
  -crypto module_name
  
  Specifies the fully qualified name of the PKCS #11 library supplied with the cryptographic hardware.
  
  -tokenlabel token_label
  
  Specifies the PKCS #11 cryptographic device token label.
  
  -pw password
  
  Specifies the password for access to the cryptographic hardware.
  
  -label label
  
  Specifies the certificate label.
  
  -size key_size
  
  Specifies the key size. The value can be 512, 1024, 2048, or 4096.
  
  -sig_alg algorithm
  
  Specifies the asymmetric signature algorithm used for the creation of the entry's key pair. The value can be MD2_WITH_RSA, MD2WithRSA, MD5_WITH_RSA, MD5WithRSA, SHA1WithDSA, SHA1WithECDSA, SHA1WithRSA, SHA2/ECDSA, SHA224WithECDSA, SHA256_WITH_RSA, SHA256WithECDSA, SHA256WithRSA, SHA2WithECDSA, SHA3/ECDSA, SHA384_WITH_RSA, SHA384WithECDSA, SHA384WithRSA, SHA3WithECDSA, SHA5/ECDSA, SHA512_WITH_RSA, SHA512WithECDSA, SHA512WithRSA, SHA5WithECDSA, SHA_WITH_DSA, SHA_WITH_RSA, or SHAWithDSA. The default value is SHA256WithRSA.
  
  -dn distinguished_name
  
  Specifies the X.500 distinguished name enclosed in double quotation marks.
  
  -file filename
  
  Specifies the file name for the certificate request.
- To use the GUI, follow these steps:
  1. From the Create menu, click New Certificate Request.
  2. In the Key Label field, enter the certificate label.
  3. Select the Key Size and Signature Algorithm that you require.
  4. Enter values for Common Name and Organization, and select a Country. For the remaining optional fields, either accept the default values, or type or select new values.
  5. In the Enter the name of a file in which to store the certificate request field, either accept the default certreq.arm, or type a new value with a full path.
  6. Click OK.
  7. The Personal Certificate Requests list shows the label of the new personal certificate request you created. The certificate request is stored in the file you chose.
After the CA sends you the personal certificate, add the CA certificate to either the cryptographic key store or the CA key ring file, if it is not already present.
- To use the CLI to add the CA certificate to the CA key ring file, enter the following command:
```
mqiptKeycmd -cert -add -db filename -pw password -type pkcs12
            -label label -file cert_filename
```
  where filename is the name of the CA key ring file, password is the CA key ring password, label is the label attached to the certificate, and cert_filename is the name of the file containing the CA certificate.
- To use the CLI to add the CA certificate to the cryptographic hardware, enter the following command:
```
mqiptKeycmd -cert -add -crypto module_name -tokenlabel hardware_token
            -pw password -label label -file cert_filename
```
  where module_name is the fully qualified name of the PKCS #11 library supplied with the cryptographic hardware, hardware_token is the PKCS #11 cryptographic device token label, password is the password for access to the cryptographic hardware, label is the label attached to the certificate, and cert_filename is the name of the file containing the CA certificate.
- To use the GUI, follow these steps:
  1. In the Key database content field, select Signer Certificates.
  2. Click Add. The Add CA's Certificate from a File window opens.
  3. Type the certificate file name and location where the certificate is stored, or click Browse to select the name and location.
  4. Click OK. The Enter a Label window opens.
  5. In the Enter a Label window, type the name of the certificate.
  6. Click OK. The certificate is added to the key database.
Receive the personal certificate, provided by the CA, into the cryptographic hardware key store.
- To use the CLI, enter the following command:
```
mqiptKeycmd -cert -receive -file filename -crypto module_name
            -tokenlabel hardware_token -pw password
```
  where filename is the name of the file containing the certificate to receive, module_name is the fully qualified name of the PKCS #11 library supplied with the cryptographic hardware, hardware_token is the PKCS #11 cryptographic device token label, and password is the password for access to the cryptographic hardware.
  If the CA certificate is stored in a CA key ring, rather than in the cryptographic hardware, you will receive a warning that the certificate chain cannot be validated as the mqiptKeycmd command cannot access the CA key ring when receiving the personal certificate into the cryptographic key store.
- To use the GUI, follow these steps:
  1. Click Receive. The Receive Certificate from a File window opens.
  2. Type the certificate file name and location for the new personal certificate, or click Browse to select the name and location.
  3. Click OK. The Personal Certificates field shows the label of the new personal certificate you added.
Encrypt the password to access the cryptographic hardware by using the mqiptPW command.
Enter the following command:
```
mqiptPW -sf encryption_key_file
```
where encryption_key_file is the name of a file that contains the password encryption key for your MQIPT installation. You do not need to specify the -sf parameter if your MQIPT installation is using the default password encryption key. Type in the password to access the cryptographic hardware to encrypt when prompted.
For more information about encrypting key store passwords, see Encrypting a key ring password in MQIPT.
If you created a CA key ring file in step 3, encrypt the password for the CA key ring file by following the instructions in step 7.
Edit the mqipt.conf configuration file.
1. Confirm that you have the appropriate entitlement to use this IBM MQ Advanced feature by setting the EnableAdvancedCapabilities global property to true.
2. Enable the use of the cryptographic hardware key store on the route by setting one or more of the SSLServerKeyRingUseCryptoHardware, SSLServerCAKeyRingUseCryptoHardware, SSLServerKeyRingUseCryptoHardware, or SSLServerKeyRingUseCryptoHardware properties to true.
  For more information about the properties to enable the use of cryptographic hardware on a route, see MQIPT route properties.
  From IBM MQ 9.2.0, you can also use cryptographic hardware with the TLS command port by setting the SSLCommandPortKeyRingUseCryptoHardware property to true.
3. If you are using a key ring file for CA certificates, specify the location of the CA key ring by setting one or more of the SSLServerCAKeyRing or SSLServerCAKeyRing properties.
  If you have configured a route to use cryptographic hardware for the site certificate, and do not specify a CA key ring file, the cryptographic hardware key store is used as the CA key store.
4. Specify the encrypted password to access the cryptographic hardware and the CA key ring by using the SSLServerKeyRingPW, SSLServerCAKeyRingPW, SSLClientKeyRingPW, SSLClientCAKeyRingPW, or SSLCommandPortKeyRingPW property.
  Set the value of the SSL*KeyRingPW properties to the encrypted password output by the mqiptPW command.
5. If the cryptographic hardware contains more than one personal certificate, specify which certificate should be selected by MQIPT to send to the SSL/TLS server or client for authentication.
  You can specify which certificate should be selected by setting one or more of the SSLClientSite* properties for a SSL/TLS client route, or one of more of the SSLServerSite* properties for a SSL/TLS server route.
  You can specify which certificate should be used by the TLS command port by using the SSLCommandPortSiteLabel property to specify the certificate label name.
  For more information about selecting certificates from a key ring, see Selecting certificates from a key ring file in MQIPT. The properties to select a certificate from a key ring are described in MQIPT route properties.
For example, to use a cryptographic hardware key store for the site certificate on a TLS server route, and a key ring file to store the CA certificates for the same route, add the following properties to the route definition:
```
SSLServerKeyRingUseCryptoHardware=true
SSLServerKeyRingPW=<mqiptPW>1!gORdM4wft5d1rCgNMDEGag==!dZxhgQD2A8Ea0yeqawQvPg==
SSLServerCAKeyRing=/opt/mqipt/ssl/ca.pfx
SSLServerCAKeyRingPW=<mqiptPW>1!3Vdrpiu6kMwn0sWRCVgT5g==!LHltGLEg3OFvN8+02Re0YA==
SSLServerSiteLabel=mqiptsite
```
Restart MQIPT.