Practical mastering IBM MQ basics
SSL/TLS configuration (1)
*This series may be revised based on the latest mqpgf/mqpcf. Please always download and use the latest version.
IBM MQ can use SSL/TLS for server-to-server connections and client connections.
Over the next few times, we'll discuss how to set up and use the TLS configurations available in IBM MQ.
I will leave the explanation of SSL / TLS itself to others, and here I will explain only the configuration method.
When using SSL/TLS, there are three main methods for signing digital certificates, and IBM MQ can use any of them.
| Operate with external CA signed certificates |
This method is the most common in actual operation.
Use a digital certificate signed by an external CA (Public Certificate Authority). |
| Operate with a self-signed certificates |
Due to its simple configuration procedure, it is most often used only to test and/or verify SSL/TLS communication. |
| Operate with certificates signed by a private CA. | Build and operate a private certificate authority. Once you have a CA in your organization, it is freer and easier to operate than using an external CA (Public Certificate Authority). Private CAs are sometimes referred to as intranet CAs. |
Here, we will introduce how to easily build a private CA using Openssl and verify SSL/TLS communication.
The construction procedure shows three types of platforms as an example: Windows, Linux, and HPE NonStop.
You can use different private CAs for each machine / queue manager, or you can use a common CA.
If the MQ network operates only within an intranet environment, it is unlikely that there will be multiple CAs, but if external CAs are utilized, they often use separate certificate authorities(CAs).
Therefore, the explanation is based on the assumption that different CAs are intentionally used for each machine/queue manager.
From here, it is assumed that you can set up the basic MQ configuration by yourself.
The procedure for creating, configuring, and operating the queue manager in the basic part is omitted, so if you are uncertain about that part, please refer to the previous series.
Creating a private CA using Openssl
The procedure for configuring a private CA using Openssl is much simpler than you might think.
Once you get used to that method, you will understand that it is easy and very convenient to verify SSL/TLS with MQ.
*The procedure for creating a private CA is the same for Windows / Linux / HPE Nonstop unless otherwise specified.
Preparation before CA construction
Openssl is included with MQ for HPE NonStop so you can use it, but it is not included with the Windows and Linux versions of MQ. The compiled version of the Windows version is available for download, so it is convenient to use it. In the case of Linux, it is often already available, but if not, please set it up. The explanation of the procedure is omitted here, so please refer to other sites as necessary. For MQ for HPE NonStop, the openssl command is installed in <MQ Install Directory>/opt/mqm/bin.
Consideration for high entropy
Openssl requires seed data to be input to the Pseudo-Random Number Generator(PRNG).
This requires that a seed value with sufficient entropy be provided.
This is also required when using Openssl command line tools.
For Windows, get seeds to enter into PRNG from various sources, such as what is displayed on the screen.
For Unix/Linux, /dev/urandom, /dev/random, etc. are used (/dev/urandom takes precedence), so make sure they are available.
For HPE NonStop, the service (/etc/egd-pool) is used with the OSS file system socket.
As the entropy daemon to use this, amqjkdm0 was provided in MQ5.3, but it is not provided in MQ8, so prngd provided by the OS side is used.
You can continue to use amqjkdm0 in an environment where MQ5.3 and MQ8 coexist.
| amqjkdm0 | Provided on IBM MQ 5.3 server. |
| /usr/local/bin/prngd | Provided by HP Integrity NonStop Server Open Source Technology Library. |
Since MQ for HPE NonStop uses the Openssl library even for MQ communication using SSL/TLS, it is necessary to start these daemons even while the queue manager is running.
For reference, I will introduce how to start/stop prngd manually. Please refer to the OS document for details.
Start and stop the entropy daemon by SUPER.SUPER.
| Example of starting manually |
OSS> run -term=/G/ZHOME /usr/coreutils/sbin/prngd /etc/egd-pool -m 0777 *In the above example, all users are allowed to use the entropy daemon.(-m 0777) |
| Example of stopping manually | OSS> run -term=/G/ZHOME /usr/coreutils/sbin/prngd /etc/egd-pool -k |
When using the command line tool, if sufficient entropy cannot be secured, the '-rand' option, RANDFILE parameter of Opennssl configuration file, RANDFILE environment variable can be used, but the explanation of how to use them is omitted. Please refer to other documents
Creating files/directories used by the CA
Create directories used by the private CA.
| <ca_root> | The root directory of the CA. Create it anywhere and with any name. Assume winca for Windows, lnxca for Linux, and nsca for NonStop. |
| <ca_root>/certs | The issued certificate is stored. |
| <ca_root>/crl | The issued certificate revocation list is stored. |
| <ca_root>/newcerts | The default location where the new certificate will be placed. |
| <ca_root>/private | The CA's private key is stored. |
$ mkdir openssl $ cd openssl $ mkdir lnxca $ cd lnxca $ mkdir certs $ mkdir certs crl newcerts private $ ls -l total 32 drwxr-xr-x 1 mqm mqm 4096 Jun 24 09:59 certs drwxr-xr-x 1 mqm mqm 4096 Jun 24 09:59 crl drwxr-xr-x 1 mqm mqm 4096 Jun 24 09:59 newcerts drwxr-xr-x 1 mqm mqm 4096 Jun 24 09:59 private
*For Windows, you can use Explorer or any text editor to create the following required directories and files.
Create various files used by the private CA.
| serial | The serial file contains the serial number used to issue the certificate and is incremented each time it is issued. |
| index.txt | The index.txt file is a history of certificates issued by the CA. |
$ echo 01 > serial $ cat serial 01 $ touch index.txt $ ls -l index.txt -rw-rw-r--. 1 mqm mqm 0 Jun 23 16:05 index.txt $
The serial file uses "01" as the initial value, and the index.txt file is created as an empty file.
Openssl configuration file preparation
Place and edit the Openssl configuration file (openssl.cnf) file. The Openssl installation includes a sample openssl.cnf file, copy it for editing. The location is essentially free, but it can be the root directory of the CA created above for clarity. For windows, the sample openssl.cnf file is usually located at <openssl install dir>bin/cnf/openssl.cnf. For Linux, it is in /etc/pki/tls/openssl.cnf etc., but if it does not exist, please check the document on the OS side.
CA configuration definition
The CA section prepared here will be used later when signing the server certificate (when using the openssl ca command).
The important parameters to be set in the openssl.cnf file for CA configuration are described below.
*The part in blue is the part changed from the default setting.
| section | parameter | example value | description |
| [ ca ] | default_ca | winca | The name of the CA section. You can leave the default (CA_default) or use a descriptive name to identify it. If you change this, you will also need to change the next section name [CA_default]. (In the example [ winca ]) |
| [ CA_default ] | dir | C:/.../openssl/winca | The root directory of the CA. You can specify a relative path, but it is more convenient to specify an absolute path. On Windows, the directory separator uses'/' instead of back slash. |
| certs | $dir/certs | This is the place where the issued certificate is stored. | |
| crl_dir | $dir/crl | This is where the issued certificate revocation list is stored. | |
| database | $dir/index.txt | Database index file. | |
| new_certs_dir | $dir/newcerts | This is the default location where the new certificate will be placed. | |
| certificate | $dir/cacert.pem | The file name of the CA certificate. | |
| serial | $dir/serial | Current serial number. | |
| crlnumber | $dir/crlnumber | Current certificate revocation list number. | |
| crl | $dir/crl.pem | Current certificate revocation list. | |
| private_key | $dir/private/cakey.pem | CA private key. | |
| RANDFILE | $dir/private/.rand | This is a private random number file. Stores part of the seed data (256 bytes). Useful for low entropy systems and adds to existing entropy. | |
| x509_extensions | usr_cert | Section name to set the extension to add to the certificate. | |
| default_days | 365 | This is the default value for certificate expiration. Change it if necessary. | |
| default_crl_days | 30 | The default value for certificate revocation list(CRL) expiration dates. Change it if necessary. | |
| default_md | sha256 | If the value is set to "default", the Openssl default message digest will be used. In OpenSSL 1.1, the default digest has changed from MD5 to SHA256. Here, sha256 is explicitly set for clarity. | |
| policy | policy_anything | The sample openssl.cnf has a [policy_match] section and a [policy_anything] section as policies for handling DN (distinguished name). For type CA, CSR countryName, stateOrProvinceName. The organizationName attribute must match the CA certificate (policy_match). Here, policy_anything is specified for ease of verification in the test. | |
| [ usr_cert ] | basicConstraints | CA:FALSE | Set the CA element to False so that the certificate issued by this CA cannot be used as a certificate for another CA. |
Sample openssl.cnf: .... #################################################################### [ ca ] #default_ca = CA_default # The default ca section default_ca = winca # The default ca section #################################################################### #[ CA_default ] [ winca ] dir = C:/.../openssl/winca # Where everything is kept certs = $dir/certs # Where the issued certs are kept crl_dir = $dir/crl # Where the issued crl are kept database = $dir/index.txt # database index file. #unique_subject = no # Set to 'no' to allow creation of # several certs with same subject. new_certs_dir = $dir/newcerts # default place for new certs. certificate = $dir/cacert.pem # The CA certificate serial = $dir/serial # The current serial number crlnumber = $dir/crlnumber # the current crl number # must be commented out to leave a V1 CRL crl = $dir/crl.pem # The current CRL private_key = $dir/private/cakey.pem# The private key x509_extensions = usr_cert # The extensions to add to the cert # Comment out the following two lines for the "traditional" # (and highly broken) format. name_opt = ca_default # Subject Name options cert_opt = ca_default # Certificate field options # Extension copying option: use with caution. # copy_extensions = copy # Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs # so this is commented out by default to leave a V1 CRL. # crlnumber must also be commented out to leave a V1 CRL. # crl_extensions = crl_ext default_days = 365 # how long to certify for default_crl_days= 30 # how long before next CRL #default_md = default # use public key default MD default_md = sha256 # use public key default MD preserve = no # keep passed DN ordering # A few difference way of specifying how similar the request should look # For type CA, the listed attributes must be the same, and the optional # and supplied fields are just that :-) #policy = policy_match policy = policy_anything # For the CA policy [ policy_match ] countryName = match stateOrProvinceName = match organizationName = match organizationalUnitName = optional commonName = supplied emailAddress = optional # For the 'anything' policy # At this point in time, you must list all acceptable 'object' # types. [ policy_anything ] countryName = optional stateOrProvinceName = optional localityName = optional organizationName = optional organizationalUnitName = optional commonName = supplied emailAddress = optional .... [ usr_cert ] # These extensions are added when 'ca' signs a request. # This goes against PKIX guidelines but some CAs do it and some software # requires this to avoid interpreting an end user certificate as a CA. basicConstraints=CA:FALSE
Set the information to generate the root certificate in the configuration file
Define the req section of the openssl.cnf file.
| section | parameter | example value | description |
| [ req ] | |||
| default_bits | 2048 | Generate a private key for the certificate in 2048bit. | |
| default_keyfile | C:/.../openssl/winca/ private/cakey.pem |
The private key file to generate. Here, it matches the file path specified in the ca section. | |
| default_md | sha256 | Since we specified sha256 for the new certificate to be issued and the message digest used to sign the CRL, specify it explicitly here as well so that there is no contradiction. | |
| distinguished_name | req_distinguished _name |
The name of the section that contains the distinguished name for the certificate. | |
| x509_extensions | v3_ca | The name of the section that describes extensions you want to include in the certificate. | |
| [ req_distinguished_name ] | |||
| countryName_default | JP | Abbreviation of country name(2 letters) | |
| stateOrProvinceName _default |
Chiba | State or Province Name | |
| 0.organizationName _default |
Pulsar Integration Inc. | Organization name(company name, etc.) | |
| commonName | www.pulsarintegration.com | The domain part that includes up to the subdomain of the URL of the site. | |
| emailAddress | support@pulsarintegration.com | E-mail address. | |
| [ v3_ca ] | |||
| basicConstraints | critical*,CA:true | The CA element of the extended area is set to true, and this certificate is allowed to be used as the CA that signs the certificate and CRL. 'critical' tells the program to adhere to the settings. | |
| keyUsage | critical*,cRLSign, digitalSignature, keyCertSign |
keyUsage extension: Contains a bit string that defines the use of the certificate. If critical is specified, the information in this extension must be used to determine the validity of the certificate use. cRLSign: CA certificate digitalSignature: Signature of the object keyCertSign: Signature of the certificate |
|
*The OpenSSL version has been changed from 1.1 to 3.0 since MQ8.1.0.15 for HPE NonStop. As a result, the "Critical" setting is now required for both the basicConstraints extension and the keyUsage extension (omitting KeyUsage itself is also prohibited). When the OpenSSL SSL_VERIFY_PEER() function is called to check the root and intermediate CA certificates in the peer certificate chain, if these certificates do not have "Critical" flags, the channel will fail to start.
Sample openssl.cnf: .... #################################################################### [ req ] default_bits = 2048 #default_keyfile = privkey.pem default_keyfile = C:/.../openssl/winca/private/cakey.pem default_md = sha256 # default MD distinguished_name = req_distinguished_name attributes = req_attributes x509_extensions = v3_ca # The extensions to add to the self signed cert # Passwords for private keys if not present they will be prompted for # input_password = secret # output_password = secret # This sets a mask for permitted string types. There are several options. # default: PrintableString, T61String, BMPString. # pkix : PrintableString, BMPString (PKIX recommendation before 2004) # utf8only: only UTF8Strings (PKIX recommendation after 2004). # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings). # MASK:XXXX a literal mask value. # WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings. string_mask = utf8only # req_extensions = v3_req # The extensions to add to a certificate request [ req_distinguished_name ] countryName = Country Name (2 letter code) #countryName_default = AU countryName_default = JP countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) #stateOrProvinceName_default = Some-State stateOrProvinceName_default = Chiba localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) #0.organizationName_default = Internet Widgits Pty Ltd 0.organizationName_default = Pulsar Integration Inc. # we can do this but it is not needed normally :-) #1.organizationName = Second Organization Name (eg, company) #1.organizationName_default = World Wide Web Pty Ltd organizationalUnitName = Organizational Unit Name (eg, section) #organizationalUnitName_default = #commonName = Common Name (e.g. server FQDN or YOUR name) commonName = www.pulsarintegration.com commonName_max = 64 #emailAddress = Email Address emailAddress = support@pulsarintegration.com emailAddress_max = 64 # SET-ex3 = SET extension number 3 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 unstructuredName = An optional company name .... [ v3_ca ] .... basicConstraints = critical,CA:true
Creating a self-signed root certificate
If the PATH to the openssl command is not set, set it.
For HPE NonStop, loading the mqprofile script will set the path to the included openssl.
*For Windows >set PATH=%PATH%;C:\Program Files\OpenSSL-Win64\bin >openssl version OpenSSL 1.1.1k 25 Mar 2021 > *For Unix-like OS export PATH=$PATH:/usr/local/ssl/bin $ openssl version OpenSSL 1.1.1j 16 Feb 2021 $ *For HPE NonStop $ . <MQ install directory>/var/mqm/wmqprofile(For MQ5.3.1) $ . <MQ install directory>/var/mqm/mqprofile(For MQ8)
Set the OPENSSL_CONF environment variable.
*For Windows >set OPENSSL_CONF=C:\...\openssl\winca\openssl.cnf *For Unix-like OS $ export OPENSSL_CONF=/.../.../openssl.cnf *If not specified, the following warning may be output each time the openssl command is executed. WARNING: can't open config file: /usr/local/ssl/openssl.cnf
The command to create a self-signed root certificate is below.
openssl req -x509 -newkey rsa -out cacert.pem -outform PEM -days 3650
*Option descriptions
req: You can use this command to create, verify, operate certificate requests and to create a self-signed certificate (root certificate) suitable for establishing a root CA.
-x509: Create a self-signed certificate (suitable for use with the root CA), not a certificate request.
-newkey rsa: Create a new key pair and use RSA as its public key cryptosystem. For RSA you can also specify the length of the prime number.
If omitted, the default_bits value set in the [req] section of the configuration file is used.
-out <filename>: The file name to which the self-signed certificate or certificate request is output. If omitted, standard output is used.
-outform: Specify the format of the self-signed certificate or certificate request (DER or PEM).
The default is PEM.
-days <number>: The number of days the self-signed certificate to generate will expire.
After moving to the CA directory, execute the above command. At that time, you will be asked for the pass phrase. Make a note of this as you will need it later. You will be prompted to confirm each parameter of the Distinguished Name for the certificate, but if you want to keep the default value specified in the configuration file, enter only the return. Since the default value is not specified for commonName and emailAddress, enter them.
> cd ..../winca > openssl req -x509 -newkey rsa -out cacert.pem -outform PEM -days 3650 Generating a RSA private key ..............................................................................+++++ .................................................+++++ writing new private key to '..../winca/private/cakey.pem' Enter PEM pass phrase: winca Verifying - Enter PEM pass phrase: winca ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [JP]: State or Province Name (full name) [Chiba]: Locality Name (eg, city) []: Organization Name (eg, company) [Pulsar Integration Inc.]: Organizational Unit Name (eg, section) []: www.pulsarintegration.com []:www.pulsarintegration.com support@pulsarintegration.com []:support@pulsarintegration.com >
Check the created self-signed root certificate by text dumping it with the following command.
openssl x509 -in cacert.pem -text -noout
*Option descriptions
x509: Create, verify, and perform various other operations on X.509 certificates.
-in <filename>: File name to read (in this case an X.509 self-signed root certificate).
-text: Converts the read certificate into a readable format and outputs it.
-noout: Suppresses the output of the certificate in encoded form.
Check if the parts in blue (Signature Algorithm, Issuer, Validity, Subject, Public Key Algorithm, X509v3 Basic Constraints, Signature Algorithm) are as specified (assumed).
>openssl x509 -in cacert.pem -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
78:8c:a6:a9:32:69:37:d5:aa:d6:74:40:a1:29:b4:2f:ce:2d:99:36
Signature Algorithm: sha256WithRSAEncryption
Issuer: C = JP, ST = Chiba, O = Pulsar Integration Inc., CN =
www.pulsarintegration.com, emailAddress = support@pulsarintegration.com
Validity
Not Before: Jul 16 04:14:26 2021 GMT
Not After : Jul 14 04:14:26 2031 GMT
Subject: C = JP, ST = Chiba, O = Pulsar Integration Inc., CN =
www.pulsarintegration.com, emailAddress = support@pulsarintegration.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:9b:4d:5e:b7:54:6b:8f:a1:d3:95:52:d3:69:2e:
f7:30:23:46:67:21:9e:30:32:6a:cd:a8:cf:75:52:
89:73:53:1b:f1:e1:00:95:d8:a7:05:df:2d:fd:7b:
19:fe:b7:40:0e:98:ed:6a:af:e5:de:f5:23:78:88:
29:9d:0b:4d:e0:74:8c:0e:9f:88:4d:bd:15:db:43:
56:a9:e0:0d:a2:96:fe:15:66:f4:f3:66:54:84:c4:
bb:86:02:c0:0a:69:34:24:d6:f0:a8:1d:db:14:7c:
7a:62:e9:d3:70:0e:42:c3:af:45:6c:cc:17:e8:9e:
ef:5e:ed:e4:d1:a8:04:ef:46:66:b7:5d:ed:09:91:
ba:e1:19:98:44:d6:2e:29:4a:2a:92:87:38:f3:e4:
87:37:74:b1:29:03:ee:62:ab:fc:c9:63:c3:a8:7f:
ce:aa:13:95:bf:1d:2d:46:73:73:4a:a1:68:26:f5:
7c:04:b0:be:6c:0c:bb:63:b5:45:e9:b6:33:d8:e8:
77:21:5c:11:ea:74:41:0c:d7:a5:51:17:0f:d8:93:
26:51:32:24:76:4e:ed:89:88:6d:52:2f:72:b8:35:
69:fc:85:bb:04:ca:8a:a3:0c:69:bc:75:52:8e:79:
66:65:33:43:c9:3c:82:f4:70:ba:fc:99:bf:32:04:
32:1b
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
23:0B:5D:88:01:02:F5:6E:2B:F7:67:3D:67:A3:EF:AB:72:8D:43:A2
X509v3 Authority Key Identifier:
keyid:23:0B:5D:88:01:02:F5:6E:2B:F7:67:3D:67:A3:EF:AB:72:8D:43:A2
X509v3 Basic Constraints: critical
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
38:80:07:0e:eb:0b:31:fb:f8:22:7d:f0:fa:50:33:00:f8:63:
e3:84:83:a9:8f:60:d4:72:d0:98:d8:04:b9:28:82:71:ff:4d:
ce:03:86:d8:e2:ab:21:7e:56:8f:98:ec:1c:41:9f:ae:67:1e:
83:ca:52:24:60:3a:59:e4:80:e4:f8:4d:da:64:96:05:45:0e:
e2:ef:82:50:b8:53:5e:b3:bd:fa:74:b8:1a:85:e1:fc:29:2d:
d7:bc:be:3a:b8:81:a5:ef:bf:1f:ad:49:74:0e:ec:ba:7a:53:
5e:12:3a:f1:39:0f:bd:bd:f8:ba:26:b0:00:85:3c:dc:d6:05:
83:00:53:f3:67:96:9f:cf:36:9a:74:ee:06:6f:eb:5b:af:28:
1f:da:73:96:34:4f:4b:86:61:00:09:9c:30:11:b1:69:aa:62:
77:5b:26:bf:7a:6c:fe:ca:9f:35:50:19:95:dc:79:00:c7:91:
19:e9:2d:6e:01:d7:91:c8:38:7c:07:9f:31:da:44:5b:1d:86:
e7:49:0f:89:73:d1:0b:dd:4e:9b:01:08:7f:b2:48:ff:f2:1b:
9e:19:be:7e:7e:4c:22:fa:78:d3:5a:9e:01:4c:76:13:90:94:
3f:4f:67:ba:4d:bb:7b:6c:a6:8c:ce:19:49:f8:74:85:04:2e:
7a:10:62:d8
>
Make sure that the CA's private key has also been created. PEM is a Base64-encoded certificate format.
>cd private >dir ... 2021/07/16 13:14 1,884 cakey.pem ... > type cakey.pem (For Windows) > cat cakey.pem (For Unix-like OS) -----BEGIN ENCRYPTED PRIVATE KEY----- MIIFHDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQInBgXOOHH1XkCAggA MAwGCCqGSIb3DQIJBQAwFAYIKoZIhvcNAwcECLR2QB+/LXw1BIIEyAlOn8D3P/Hh .... goFBi9hkAqG7xCmwPGqGziC8ZQnvBRRQ4FkcXiQUqgox+BkzWk4/tzaXua96D1Nx cNQ/COBPLF+AIVG5cNCUbg== -----END ENCRYPTED PRIVATE KEY----- >
SSL/TLS setup on each server (to create CSR) (GSKit)
MQ for Multiplatforms uses GSKit(IBM Global Security Kit) for SSL/TLS libraries.
MQ8 for HPE NonStop will continue to use Open SSL, similar to MQ5.3.1.
First, I will explain the work procedure with GSKit.(The procedure for working with MQ8 for HPE NonStop(Open SSL) will be described later.)
The procedure after this is verified with the following version.
| Windows |
9.2.0.0 |
| Linux | 9.1.0.4/9.2.0.4 |
GSKit commands used in SSL/TLS setup
With GSKit, you can use the strmqikm(iKeyman), runmqckm(iKeycmd), and runmqakm(GSKCapiCmd) commands.
| strmqikm(iKeyman) |
Manage keys and digital certificates using the iKeyman GUI. *Can be used on Unix, Linux, and Windows. |
| runmqckm(iKeycmd) | Perform key and digital certificate management tasks in the iKeycmd command line interface. |
| runmqakm(GSKCapiCmd) |
The command syntax for runmqakm is the same as the syntax for runmqckm.
Use the runmqakm command when you need to manage SSL certificates in a FIPS-compliant manner.
If FIPS compliance is required, the CipherSpecs that can be used are limited. *Even if FIPS compliance is not required, use the runmqakm command to use a key size of 2048 or larger. |
Subsequent steps basically use the runmqckm command and use runmqakm only when creating a certificate request.
Prepare key repository for each queue manager(Windows, Linux)
If the MQ environment is not set up in the login environment of each machine, set up the queue manager environment that configures SSL/TLS.
*For Windows
> cd
*If -s is specified for setmqenv, the same installation environment as the executed setmqenv will be set among multiple MQ installations.
Create a key repository. The default key repository location is set in queue manager SSLKEYR property.
> mqpcf mqsc -qm PL92W -s "dis qmgr SSLKEYR" 1: AMQ8408I: ... QMNAME(PL92W) SSLKEYR(C:\ProgramData\IBM\MQ\qmgrs\PL92W\ssl\key) *Default for Windows
*Option descriptions
mqsc: Execute any mqsc command.
-s : MQSC command string
The default for Linux is SSLKEYR (/var/mqm/qmgrs/PL91L/ssl/key).
The "key" at the end is the filename of the repository, not the directory.
Move to the location of the repository.
>*For Windows >cd C:\ProgramData\IBM\MQ\qmgrs\PL92W\ssl *For Linux $ cd /var/mqm/qmgrs/PL91L/ssl
Create a key repository using the runmqckm command.
*The following is an example of Windows, but the same applies to Linux.
...\ssl>runmqckm -keydb -create -db key.kdb -pw PL92Wpass -type cms -stash 5724-H72 (C) Copyright IBM Corp. 1994, 2020.
*Option descriptions
-keydb: The target of the command is the key database
-create: Create key database
-db filename: Specify the fully qualified file name of the CMS key database.
The file extension must be ".kdb".
-pw password: Specify the password for the CMS key database.
-type cms: Specifies the type of key database.
For IBM MQ, always specify cms (Certificate Management System).
-stash: Save the key database password to a file.
The following three files will be created.
>dir ... 2021/07/21 14:43 88 key.kdb 2021/07/21 14:43 80 key.rdb 2021/07/21 14:43 193 key.sth ...
Here's a brief description of these files.
| key.kdb | "Key database" file. Stores personal certificates, personal certificate requests, and signer certificates. |
| key.sth | Contains the obfuscated key database password. This file also contains the private key, if any. |
| key.rdb | "Request" database file. It is created automatically when you create ".kdb" database file. This file contains certificate requests that have not been processed and have not yet been received from the CA. When the CA returns the certificate, it looks for a matching certificate request in the .rdb file (based on the public key). If a match is found, the certificate is received and the corresponding certificate request is removed from the .rdb file. If no match is found, the attempt to receive the certificate will be rejected. The certificate request contains the common name, organization name, address, and other information specified at the time of the request, as well as the public and private keys associated with the request. |
Overview of CERTLABL
Since MQ8.0, you can specify CERTLABL for each channel and select a different personal certificate for each channel.
Inbound channels (including RCVR, CLUSRCVR, unqualified SERVER, and SVRCONN channels) rely on detecting channel name using TLS Server Name Indication (SNI), will only send the configured certificate if the IBM MQ version of the remote peer fully supports certificate label configuration and the channel is using a TLS CipherSpec.
Be aware that MQ8.0 and earlier releases will only receive certificates configured with her CERTLABL parameter in the queue manager, so there are restrictions when connecting to older queue managers such as MQ5.3 for HPNonStop.
(Detailed explanation of this restriction is omitted here.)
The queue manager's default CERTLABL is ibmwebspheremq on his Windows/Linux plus the queue manager's name (lowercase) and is blank on HPE NonStop.
>mqpcf mqsc -qm PL92W -s "dis qmgr CERTLABL" *For Windows/Linux 1: AMQ8408I: QMNAME(PL92W) CERTLABL(ibmwebspheremqpl92w)
Hereafter, the procedure will be described using the case of specifying CERTLABL for each channel as an example.
Create Certificate Signing Request(CSR) (Windows, Linux)
A CSR (Certificate Signing Request) is a request to a CA to sign a server certificate.
When creating a CSR, use runmqakm instead of runmqckm if you want to use 2048 for the key size.
At that time, -fips is not specified.
*The following is an example of Windows, but the same applies to Linux, and it is specified in one line.
For DN, specify the contents for each server.
...\ssl>runmqakm -certreq -create -db key.kdb -pw PL92Wpass -label PL92WA -dn "CN=www.pulsarintegration.PL92W.com,O=Pulsar Integration PL92W Inc.,S=Chiba,C=JP" -size 2048 -file key.csr -sig_alg sha256 5724-H72 (C) Copyright IBM Corp. 1994, 2020.
*Option descriptions
-certreq: The target of the command is a certificate request
-create: Create a certificate request
-db filename: Specifies the fully qualified file name of a CMS key database.
-pw password: Specifies the password for the CMS key database.
-label label: Specifies the key label attached to the certificate.
The label is either the value of the CERTLABL attribute, if it is set, or the default ibmwebspheremq with the name of the queue manager all in lowercase.
-dn: distinguished_name: Specifies the X.500 distinguished name enclosed in double quotation marks.
At least one attribute is required.
-size: Key size.
-file: File name of a certificate request.
-sig_alg: The hashing algorithm used during the creation of a certificate request.
A certificate request file "key.csr" is created.
>dir ... 2021/07/21 16:00 1,038 key.csr 2021/07/21 14:43 88 key.kdb 2021/07/21 16:00 5,080 key.rdb 2021/07/21 14:43 193 key.sth
Make sure that the certificate request is created as expected.
...\ssl>runmqckm -certreq -details -label PL92WA -db key.kdb ... A password is required to access the source key database. Please enter a password: PL92Wpass Label:PL92WA Key Size:2048 Subject: CN=www.pulsarintegration.PL92W.com, O=Pulsar Integration PL92WA Inc., ST=Chiba, C=JP Fingerprint: 07:47:A3:DE:98:5E:DC:88:6E:35:AC:90:4E:B6:E7:70 Signature Algorithm: SHA256withRSA (1.2.840.113549.1.1.11)
*Option descriptions
-certreq: The target of the command is a certificate request
-detail: Show the details of a specific certificate request
-label label: Specifies the key label attached to the certificate.
-db filename: Specifies the fully qualified file name of a CMS key database.
SSL/TLS setup on each server (to create CSR) (Openssl)
HPE NonStop also uses openssl for all of the following tasks: In the following, we are working on creating a directory with the queue manager name under .../openssl/ nsca. There is no fixed method for work management, so feel free to decide and work according to the convenience of the system.
$ cd ..../openssl/nsca $ mkdir PL81N $ cd PL81N
Create Certificate Signing Request(CSR) (HPE NonStop)
Create openssl.cnf in the working directory to create a certificate signing request(CSR).
Define the [req] section of the openssl.cnf file.
| section | parameter | example value | description |
| [ req ] | default_bits | 2048 | Generate a private key for the certificate in 2048bit. |
| default_md | sha256 | Specify sha256 as the message digest to use. | |
| distinguished_name | req_distinguished _name |
The name of the section that contains the distinguished name for the certificate. | |
| x509_extensions | v3_req | The name of the section that describes extensions you want to include in the certificate. | |
| [ req_disting uished_name ] |
countryName_default | AU | Abbreviation of country name(2 letters) |
| stateOrProvinceName _default |
Sydney | State or Province Name | |
| 0.organizationName _default |
Pulsar Integration PL81NA Inc. |
Organization name(company name, etc.) | |
| commonName | www.sd.pulsarintegration .PL81N.com |
The domain part that includes up to the subdomain of the URL of the site. | |
| [ v3_req ] | basicConstraints | CA:FALSE | Prohibited to use as a CA certificate. |
Sample openssl.cnf: .... #################################################################### [ req ] default_bits = 2048 default_keyfile = privkey.pem default_md = sha256 distinguished_name = req_distinguished_name attributes = req_attributes #x509_extensions = v3_ca # The extensions to add to the self signed cert x509_extensions = v3_req # Passwords for private keys if not present they will be prompted for # input_password = secret # output_password = secret # This sets a mask for permitted string types. There are several options. # default: PrintableString, T61String, BMPString. # pkix : PrintableString, BMPString (PKIX recommendation before 2004) # utf8only: only UTF8Strings (PKIX recommendation after 2004). # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings). # MASK:XXXX a literal mask value. # WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings. string_mask = utf8only # req_extensions = v3_req # The extensions to add to a certificate request [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_default = AU countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) #stateOrProvinceName_default = Some-State stateOrProvinceName_default = Sydney localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) #0.organizationName_default = Internet Widgits Pty Ltd 0.organizationName_default = Pulsar Integration PL81NA Inc. # we can do this but it is not needed normally :-) #1.organizationName = Second Organization Name (eg, company) #1.organizationName_default = World Wide Web Pty Ltd organizationalUnitName = Organizational Unit Name (eg, section) #organizationalUnitName_default = #commonName = Common Name (e.g. server FQDN or YOUR name) commonName = www.sd.pulsarintegration.PL81N.com commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 # SET-ex3 = SET extension number 3 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 unstructuredName = An optional company name .... [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
Set the created configuration file in the OPENSSL_CONF environment variable.
$ export OPENSSL_CONF=..../openssl/nsca/PL81N/openssl.cnf
Load the MQ preference file.
$ . <MQ install directory>/var/mqm/wmqprofile (For MQ5.3.1)
$ . <MQ install directory>/var/mqm/mqprofile (Fpr MQ8)
Make sure the entropy daemon is running.
$ ps -ef|grep prngd | grep -v grep SUPER.SUPER 1744830575 .... 00:00 /usr/coreutils/sbin/prngd /etc/egd-pool -m 0777
If the entropy daemon is not running, start it.(Already mentioned above) If the entropy daemon is not running, the following error occurred when generating the RSA Private Key in this test.
$ openssl req ... Generating a RSA private key Error Generating Key 0:error:2406C06E:random number generator:RAND_DRBG_instantiate:error retrieving entropy:... 0:error:2406C06E:random number generator:RAND_DRBG_instantiate:error retrieving entropy:... ...
The command to create a certificate request (CSR) is:
openssl req -newkey rsa:2048 -sha256 -keyout PL81Nkey.pem -passout pass:PL81Npass -out PL81Nreq.pem
*Option descriptions
req: Use this command to create, verify, and manipulate certificate requests.
-newkey rsa: Create a new key pair and use RSA as its public key cryptosystem.
For RSA you can also specify the length of the prime number.
If omitted, the default_bits value set in the [req] section of the configuration file is used.
-sha256: Specify sha256 as the message digest algorithm used to sign the certificate request.
-keyout <filename>: Specify the file name to which the used private key is output.
-passout pass:&pass phrase>: A passphrase used to encrypt a private key when it is generated with a certificate or certificate request.
-out <filename>: File name of the output destination of the certificate request to be output.
After moving to the working directory of the queue manager name, execute the above command. You will be prompted to confirm each parameter of the Distinguished Name for the certificate, but if you want to keep the default value specified in the configuration file, enter only the return. Here, only the commonName is entered.
$ openssl req -newkey rsa:2048 -sha256 -keyout PL81Nkey.pem -passout pass:PL81Npass -out PL81Nreq.pem Generating a RSA private key .....................................+++++ ...........................................................+++++ writing new private key to 'PL81Nkey.pem' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: State or Province Name (full name) [Sydney]: Locality Name (eg, city) []: Organization Name (eg, company) [Pulsar Integration PL81NA Inc.]: Organizational Unit Name (eg, section) []: www.sd.pulsarintegration.PL81N.com []:www.sd.pulsarintegration.PL81N.com Email Address []: Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []:
A PEM-formatted private key file and a certificate request file are generated.
.../openssl/nsca/PL81N: ls -l total 28 -rw------- 1 MQM.MANAGER MQM 1854 Jul 21 20:22 PL81Nkey.pem -rw-r--r-- 1 MQM.MANAGER MQM 1021 Jul 21 20:22 PL81Nreq.pem -rw-rw-rw- 1 MQM.MANAGER MQM 11147 Jul 21 19:09 openssl.cnf
Make sure that the certificate request is created as expected.
.../openssl/nsca/PL81N: openssl req -in PL81Nreq.pem -text Certificate Request: Data: Version: 1 (0x0) Subject: C = AU, ST = Sydney, O = Pulsar Integration PL81NA Inc., CN = www.sd.pulsarintegration.PL81N.com Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public-Key: (2048 bit) Modulus: ... Exponent: 65537 (0x10001) Attributes: a0:00 Signature Algorithm: sha256WithRSAEncryption ... -----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----
*Option descriptions
req: Use this command to create, verify, and manipulate certificate requests.
-in: Specify the file name of the certificate request.
-text: Converts the read certificate request into a readable format and outputs it.
