I have written three blog post on using the MQ REST API
- Setting up to use MQ Rest API and CURL to get to MQ on z/OS using digital certificates, and a z/OS keyring for authentication (rather than passing a userid and password)
- What can I do with the MQ Rest API data
- Debug hints for MQ Rest API and CURL to get to MQ on z/OS using digital certificates
This post is setting up to use MQ Rest API and CURL from my Redhat linux machine to get to MQ on z/OS
The process below worked for me, - there may be better ways of doing it!
To use a REST API, you send a request to an HTTP server (MQ uses a WAS Liberty server also known as mqweb server), and this server sends a response back. The request is self contained.
There are many ways of sending the request to the server:
- Curl (Command line tool for transferring data with URLs) can be used in scripts to issue requests and get responses back. I used Curl because it is easy to use and demonstrates the REST API. I used it in a Bash script on Linux.
- Java script and Java are very common
You can have Liberty check the credentials of users that connect to it. You can also have Liberty send its credentials to the client knows it is talking to the correct server.
Digital certificates and keys.
There are two parts to your certificate
- Your private key. This allows you to encrypt data and shows the data came from you. You must protect this. On z/OS this can be stored in tamper proof hardware. You can send this file around, protected by a password.
- Your certificate. This contains your public key that you to decrypt what has been encrypted with the private key. It contains information about the public key. This is usually signed by someone trustworthy like a Certificate authority.
When you are downloading the certificate parts you need to be careful to download the just the certificate, or the certificate and the key, and avoid downloading the key unnecessarily.
A CA certificate is used to sign other certificates. When a certificate is created for a user you can have is signed by a CA certificate. At a remote site if I have a copy of the CA Certificate, I can validate any certificates which have been signed by it. So with one certificate I can validate thousands of certificates.
I created my two certificate authorities for clarity.
Certificates on z/OS
On z/OS when you set up a certificate, it is identified with an owner, and a label. For example owner PAICE, and label MYWEBCERT The certificate itself has information like CN=ColinPaice for common name, O=IBM for organisation, and C=GB for country.
Setting up the server
The MQWEB server runs as a started task, and has a userid associated with it. I refer to this userid as the MQWEB userid.
I set up a Certificate Authority(CA) certificate owner CERTAUTH with label ZZZZZZZZ, and the certificate had CN=ZZZZZZZZ O=HURSLEY.
I created a certificate for the MQWEB server userid, ID(SCENSTC) with label YYYYYYYY, and the certificate had CN=YYYYYYYY O=HURSLEY, signed by CERTAUTH.ZZZZZZZZ
With this server certificate I specified the DOMAIN name (TCP Hostname) that it can be used with. This is required by modern clients.
I connected both of these certificates to the keyring SCENSTC.RING2 with user ID SCENSTC.
* create the CA
RACDCERT CERTAUTH -
O ('IBM') -
KEYUSAGE ( CERTSIGN )
* Export the CA certificate
RACDCERT CERTAUTH EXPORT(LABEL('ZZZZZZZZ')) -
* connect the CA to the MQWEB user's keyring
RACDCERT ID(SCENSTC) CONNECT(CERTAUTH LABEL('ZZZZZZZZ') -
* Create the certificate for the MQWEB server task
RACDCERT ID(SCENSTC) GENCERT -
SUBJECTSDN(CN('YYYYYYYY') C('GB')) -
NOTBEFORE( DATE(2017-01-01) ) -
NOTAFTER( DATE(2018-01-01) ) -
SIGNWITH(CERTAUTH LABEL('ZZZZZZZZ') )-
KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN) -
RACDCERT ID(SCENSTC) ALTER (LABEL('YYYYYYYY')) TRUST
* connect the server's certificate to the keyring.
RACDCERT ID(SCENSTC) CONNECT(ID(SCENSTC) LABEL('YYYYYYYY') -
In my xml definitions for MQWEB I had
<ssl id="mqDefaultSSLConfig" keyStoreRef="defaultKeyStore"
<keyStore filebased="false" id="defaultKeyStore"
Setting up the client
I set up a Certificate Authority certificate CERTAUTH with label SCENCA and the certificate had CN=SCENCA, O=IBM.
I created a certificate for the end user SCENSTC with label CONSOLE and the certificate had CN=CONS4096 O=CONSOLE3, C=GB signed with CERTAUTH label SCENCA.
I connected CERTAUTH.SCENCA to the keyring used by MQWEB . When the client connects using CN=CONS4096, O=HURLSEY, the CA will be able to verify it
I downloaded CN=CONS4096 and Certauth SCENCA to my Redhat machine.
* Create the end user Certificate Authority
RACDCERT CERTAUTH -
O ('IBM') -
KEYUSAGE ( CERTSIGN )
* connect it to the keyring
RACDCERT ID(SCENSTC) CONNECT(CERTAUTH LABEL('SCENCA') -
* now the end user certificate
RACDCERT ID(SCENSTC ) GENCERT -
SUBJECTSDN(CN('CONS4096') O('CONSOLE3') C('GB')) -
SIGNWITH(CERTAUTH LABEL('SCENCA')) -
KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN)
RACDCERT ID(SCENSTC ) ALTER (LABEL('CONS4096')) TRUST
* export the certificate and key in PKCS12 format
* (The default if password is specified)
RACDCERT ID(SCENSTC) EXPORT(LABEL('CONS4096')) -
This exports the user certificate, the signer's certificate and the private key. (Known as a PKCS12 format package).
Processing the server's CA on Redhat
FTP file PAICE.ZZZZZZZZ.OUT to my Redhat machine in ascii as zzzzzzz.pem.
This file can be used as-is.
Processing the certificate for the redhat userid.
FTP file PAICE.CERT.OUT to my Redhat machine in binary (name of file on Redhat cert.bin)
OpenSSL does not recognize the PKCS12 package, so you have to do a two stage process to split the certificate and the key
openssl pkcs12 -in cert.bin -out cert.crt.pem -clcerts -nokeys
Enter Import Password:
It gave MAC verified OK
openssl pkcs12 -in cert.bin -out cert.key.pem -nocerts -nodes -passin pass:MYPASSWORD2
MAC verified OK
Note you can specify the password using -passin .. or let it prompt. Letting it prompt is more secure.
Finally! I could then use
curl --cacert ./zzzzzzzz.pem --cert ./cert.crt.pem --key ./cert.key.pem https://winmvsca.hursley.ibm.com:9444/ibmmq/rest/v1/admin/qmgr
--cacert is the name of the CA certificate used to validate the request passed down from the server (Label YYYYYYYY)
--cert is the user certificate
--key is the private key
This returned an array of queue managers.