Setting up the end user CA signed certificate for mqweb

You want to use certificates to authenticate access to a mqweb server.  You can use self signed, which is fine for test and small environments, or use signed certificate which are suitable for production,  and typical environments.  Using certificates means you do not need to specify userid and password.

The userid is taken from the CN part of the subject, and this userid is used to grant access depending on the configuration in the mqwebuser.xml file.

This section assumes you have set up your mqweb using a certificate authority.

Information about certificates used for authentication are stored in the trust store.  For a CA signed certificate, you only need the CA certificates, not the individual certificates.  With self signed, you need a copy of the individual self signed certificate.

Create the trust store if required.

/opt/mqm/bin/runmqckm -keydb -create -db trust.jks -pw zpassword -type jks

You need to do this once.

Add the CA certificate to the trust store

/opt/mqm/bin/runmqckm -cert -add -db trust.jks -file cacert.pem -label CACert -type jks -pw zpassword

You need to do this for each CA certificate you want to add, giving each CA a unique label.

You need to restart mqweb so it picks up any changes to the trust store, but as you will be changing the mqwebuser.xml – the restart can wait will later.

Create the certificate request for the end user

openssl req -config client.cnf -newkey rsa:2048 -out colinpaice.csr -outform PEM -keyout colinpaice.key.pem -subj “/C=GB/O=cpwebuser/CN=colinpaice” -extensions client_extensions -passin file:password.file -passout file:password.file

  • openssl req – the absence of -x509 makes this a certificate request
  • -config client.cnf – use this config file
  • -newkey rsa:2048 – create a new private key with 2048 bits rsa key
  • -out colinpaice.csr – put the request in this file
  • -outform PEM – with this format
  • -keyout colinpaice.key.pem – put the key in this file
  • -subj “/C=GB/O=cpwebuser/CN=colinpaice” – this is the DN.   The CN= is the userid used by mqweb to determine the role.  It must match the case of userid
  • -extensions client_extensions – see below
  • -passin file:password.file -passout file:password.file – passwords are in this file
[ client_extensions ]

subjectKeyIdentifier = hash
# basicConstraints = CA:FALSE
subjectAltName       = DNS:localhost, IP:127.0.0.1
nsComment = "OpenSSL ColinClient"
keyUsage = critical, nonRepudiation,digitalSignature,
extendedKeyUsage = critical, clientAuth

You need to do this for each user.

Sign it

Send the certificate request to your CA.  You can use the following command to sign it.

openssl ca -config openssl-ca-user.cnf -policy signing_policy -extensions signing_req -md sha256 -keyfile cacert.key.pem -out colinpaice.pem -infiles colinpaice.csr

  • openssl ca – the signing request
  • -config openssl-ca-user.cnf – use this config file
  • -policy signing_policy – defines the requirements for the DN.  See below
  • -extensions signing_req – see below
  • -md sha256 – what encryption to be used for the message digest
  • -keyfile cacert.key.pem – the CA authorities private key
  • -out colinpaice.pem – where the output goes
  • -infiles colinpaice.csr – the input file that needs signing

Send the *.pem file back to the requestor.

You need to do this for each user.

The signing policy allows the CA administrator to define which elements are required in the DN.

[ signing_policy ]
organizationName = supplied
commonName = supplied

The certificate needs extensions which say how the certificate can be used.

[ signing_req ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints    = CA:FALSE
keyUsage            = digitalSignature
extendedKeyUsage    =  clientAuth

Create an intermediate pkcs12 keystore so certificate can be imported

You need to import the certificate and private key into the browser’s keystore.   The only way I found of doing this was via an intermediate pkcs12 keystore (with extension .p12).   If you import the certificate and key from the web browser, it will expect a .p12 file.

openssl pkcs12 -export -inkey colinpaice.key.pem -in colinpaice.pem -out colinpaice.p12 -CAfile cacert.pem -chain -name colinpaice -passout file:password.file -passin file:password.file

  • openssl pkcs12 – request to process a pkcs12 keystore
  • -export – to create it
  • -inkey colinpaice.key.pem – this private key
  • -in colinpaice.pem – this certificate returned from the CA
  • -out colinpaice.p12 – the name of the temporary key store which is created
  • -CAfile cacert.pem – use this CA certificate
  • -chain – include any CA certificates with the certificate and key
  • -name colinpaice – create this name in the keystore
  • -passout file:password.file -passin file:password.file – use these passwords

Import the temporary keystore into the Chrome keystore

pk12util -i colinpaice.p12 -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb/ -W password

  • pk12util   – this command
  • -i  colinpaice.p12  – from the temporary keystore you just created
  • -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb/ – into this key store
  • -W password  – using this password (for the temporary .p12 file)

Remove the intermediate file

rm colinpaice.p12

You do not need to import the certificate into the mqweb trust store.

Update the mqweb configuration if required

<webAppSecurity allowFailOverToBasicAuth="false" />
<keyStore id="defaultKeyStore" 
          location="/home/colinpaice/ssl/ssl2/mqweb.p12" 
          type="pkcs12" 
          password="password"/>

<keyStore id="defaultTrustStore" 
          location="/home/colinpaice/ssl/ssl2/trust.jks" 
          type="JKS" 
          password="password"/>

<ssl     id="defaultSSLConfig" 
         keyStoreRef="defaultKeyStore" serverKeyAlias="mqweb" 
         trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2"
         clientAuthentication="true" 
         clientAuthenticationSupported="true" 
/>

Stop mqweb

It is better to stop and restart mqweb if you change the xml config files, otherwise you can get strange errors.

/opt/mqm/bin/endmqweb

Start mqweb

/opt/mqm/bin/strmqweb

No messages are produced in  /var/mqm/web/installations/Installation1/servers/mqweb/logs/messages.log if the trust store was opened successfully.

Use a command like grep ” E ” messages.log  and check for messages like

CWPKI0033E: The keystore located at /home/colinpaice/ssl/ssl2/trust.jks did not load because of the following error: Keystore was tampered with, or password was incorrect

Try using it in Chrome

You need to restart Chrome to pick up the changes to its keystore.  Use the url chrome://restart/

Use the url chrome://settings/certificates , to check your certificate is present under “Your certificates”. If not use url chrome://version to display the profile being used, and that it matches the store used in the pk12util command above.

Try connecting to mqweb using a url like https://127.0.0.1:9443/ibmmq/console/ .

You should be logged on with no password request. In the top right hand corner of the screen you should have a black circle with a white “i” in it.   This shows you are logged on with certificates.  Click on this to show how you are logged on.

Setting up a self signed certificate for the mqweb server end

When using mqweb with certificates you can use

  • a self signed certificate to identify the server
  • a CA signed certificate to identify the server

You can use certificates to authenticate…

  • a self signed certificate at the client end
  • a CA signed certificate at the client end

This post explains how I set up mqweb to use a self  signed certificate at the server, and to import the certificate into my Chrome browser.

The tasks are

  • create the self signed certificate
  • create the keystore and import the certificate
  • update the mqwebuser.xml file
  • import the certificate into the browser keystore

Create the openssl config file

You configure parameters in sections in a config file, and use a command parameter to identify which sections to use.

For the self signed certificiate I set up ss_extensions

[ ss_extensions ]

subjectKeyIdentifier = hash
#Note: there is a bug in Chrome where it does 
# not accept certificates if basicConstraints
# is specified
# basicConstraints = CA:false

subjectAltName = DNS:localhost, IP:127.0.0.1
nsComment = "OpenSSL ColinClientSS28"
keyUsage = critical, keyEncipherment
extendedKeyUsage = critical, serverAuth

Create the self signed certificate

I set up a shell script to automate the tasks

Create the self signed certificate

openssl req -x509 -config openssl-client2.cnf -newkey rsa:2048 -out ss.pem -keyout ss.key.pem -subj “/C=GB/O=aaaa/CN=colinpaice” -extensions ss_extensions -passin file:password.file -passout file:password.file

  • -config openssl-client2.cnf  – the location of the openssl configutation file ( see -extensions)
  • -newkey rsa:2048 – define a self signed certiticate
  • -out ss.pem – where the certificate is stored
  • -keyout ss.key.pem– where the private key is stored
  • -subj “/C=GB/O=aaaa/CN=colinpaice” – this is the DN of the certificate.  I Used O=aaaa so it was at the top of any list of certificates
  • -extensions ss_extensions see above
  • -passin file:password.file -passout file:password.file – openssl uses passwords. The file has two lines each with a password in it.

delete the old keystore

rm ssks.p12

  • delete the old keystore

create the keystore and import the certificate

openssl pkcs12 -export -in ss.pem -inkey ss.key.pem -out ssks.p12 -name “server” -passin file:password.file -passout file:password.file

  • pkcs12 -export – create the pkcs12 keystore
  • -in ss.pem -inkey ss.key.pem – the two files which are imported into the keystore
  • -out ssks.p12 – this is the keystore used by mqweb
  • -name “server”– this is the label given to the certificate in the keystore, used in serverKeyAlias in the mqweb xml configuration
  • -passin file:password.file -passout file:password.file – this gives the passwords to use

Other commands I used, to display information about the certificate

  • openssl x509 -purpose -in ss.pem -inform PEM -nocert
  • openssl x509 -in ss.pem -noout -ext subjectAltName
  • openssl x509 -in ss.pem -noout -ext keyUsage
  • openssl x509 -in ss.pem -noout -ext extendedKeyUsage

Update the mqweb configutation file

<keyStore id="defaultKeyStore" 
          location="/home/colinpaice/ssl/ssks.p12"  
          type="pkcs12" 
          password="password"/> 
<!-- this is used for authentication with user certificates
<keyStore id="defaultTrustStore" 
          location="/home/colinpaice/ssl/key.jks" 
          type="JKS" 
          password="zpassword"/>
-->
<ssl id="defaultSSLConfig" 
     keyStoreRef="defaultKeyStore" 
     serverKeyAlias="server" 
     clientAuthentication="false" 
     clientAuthenticationSupported="false" 
/>
<!--trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2"
-->

Stop mqweb

/opt/mqm/bin/endmqweb

Start mqweb

/opt/mqm/bin/strmqweb

Check /var/mqm/web/installations/Installation1/servers/mqweb/logs/messages.log for messages like

[14/01/20 09:12:15:730 GMT] 00000024 com.ibm.ws.ssl.config.WSKeyStore E CWPKI0033E: The keystore located at /home/colinpaice/ssl/ssks.p12 did not load because of the following error: keystore password was incorrect.

Import it into Chrome

If you do not import it into the web browser, the web browser will complain and give you the option to accept it as untrusted.  If this is just a test system this may be acceptable.  If you want to be able to trust the web server, you need to import the certificate into the browser’s keystore, as trusted.

I have several profiles for Chrome.  At one point it hickuped and created a new profile.

Find the keystore

In Chrome use the url chrome://version/ this gives the profile path, for example /home/colinpaice/snap/chromium/986/.config/chromium/Default

Remove the old certificate

certutil -D -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb -n server

  • certutil -D – delete the certificate
  • -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb – from this keystore directory
  • -n server with this name

Add the new certificate

certutil -A -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb -t “P,,” -n server -i $name.pem

  • certutil -A – add a certificate
  • -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb – into this keystore directory
  • -t “P,,” – give it these permissions.
    • P says Trusted Peer certificate.   The certificate appears in Chrome under “servers”
  • -n server – with this name
  • -i ss.pem – and this certificate

Tell Chrome to pickup the changes

Use the url chrome://restart to restart chrome

Try using it

use the url like https://127.0.0.1:9443/ibmmq/console/

You should get the IBM MQ Console – login

 

Certificates in Chrome

You can import certificates without using the certutil command.

You can display the certificates in Chrome using the url chrome://settings/certificates .

If you click on “Your certificates” or “Servers”, and then click on import, you can import a certificate.

I selected the directory, and then the ss.pem file.   The certificate ended up in “Others” under

org-aaaa

  • UNTRUSTED colinpaice

Use the url chrome://restart to restart chrome

Use the url like https://127.0.0.1:9443/ibmmq/console/

This gave me the “Your connection is not private”,  NET::ERR_CERT_AUTHORITY_INVALID.

The only way I found of making it trusted was to use the certutil command

certutil -L -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb

This listed the certificates in the store.   The one I had just added was colinpaice #2

certutil -M -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb -n “colinpaice #2” -t P,,

This modifies the certificate to be a Trusted Peer.  Restart Chrome, and the certificate appeared in the “Servers” section.

Using the mqweb url now worked successfully

Setting up a CA signed certificate for the mqweb server end

When using mqweb with certificates you can use

  • a self signed certificate to identify the server
  • a CA signed certificate to identify the server

You can use certificates to authenticate…

  • a self signed certificate at the client end
  • a CA signed certificate at the client end

This post explains how I set up mqweb to use a CA  signed certificate at the server, and to import the CA into my Chrome browser.

The steps are

  • Create your certificate authority certificate
  • Create the certificate request for mqweb server
  • Sign the request
  • Create the mqweb keystore and import the mqweb certificate
  • Import the CA into the web browser keystore if required

Create your certificate authority certificate

If you do not already have a certificate authority and a process for signing certificates you need to set these up.   To do it properly, you should create a certificate request and have an external CA sign it.

The following command creates a self signed certificate.   This is your CA authority certificate and private key.

openssl req -x509 -config openssl-ca.cnf -newkey rsa:4096 -subj “/C=GB/O=SSS/OU=CA/CN=SSCA” -nodes  -out cacert.pem -keyout cacert.key.pem -outform PEM

  • openssl req -x509 – create a self signed certificate request.  -x509 says self signed.
  • -config openssl-ca.cnf – use this file for the definitions
  • -newkey rsa:4096 – generate a new key
  • -nodes  – do not encrypt the private keys.  I do not know if this should be specified or not.
  • -subj “/C=GB/O=SSS/OU=CA/CN=SSCA” –  with this DN
  • -out cacert.pem – output the certificate.   This is used when signing.    This file is sent to all users.
  • -keyout cacert.key.pem – output the private key.  This is used when signing.  This files stays on the machine.
  • -outform PEM – in this format

In the config file, the important options I had were

[ req_extensions ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always, issuer
basicConstraints = critical,CA:TRUE, pathlen:0
keyUsage = keyCertSign, digitalSignature

You need to distribute the cacert.pem certificate to all your users, so they import it into their keystores.

Create the certificate request for mqweb server

The following command creates a certificate request which will be sent to the CA to sign.

openssl req -config mqwebserver.config -newkey rsa:2048 -out mqweb.csr -outform PEM -keyout mqweb.key.pem -subj “/C=GB/O=cpwebuser/CN=mqweb” -passin file:password.file -passout file:password.file

  • openssl req – as this request does not have -x509 specified it is for a certificate request
  • -config mqwebserver.config – use definitions in the specified  file
  • -newkey rsa:2048 – create a new  certificate request and private key with a 2048 bit  RSA key
  • -out mqweb.csr – use this output file for the request to be sent to the CA
  • -outform PEM – use pem format
  • -keyout mqweb.key.pem – put the private key in this file
  • -subj “/C=GB/O=cpwebuser/CN=mqweb” – with this distinguished name. It can have any values which meet your enterprise standards.
  • -passin file:password.file -passout file:password.file – use the passwords in the file(s).  The file:… says use this file. You can specify a password instead.  As the same file is used twice, two lines in the file are used.

In the config file, the important options were

[ req_extensions ]
subjectKeyIdentifier = hash
basicConstraints = CA:FALSE
subjectAltName = DNS:localhost, IP:127.0.0.1
nsComment = "OpenSSL mqweb server"
keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = critical, serverAuth

Sign the request

Send the *.csr file to your CA.

Initial setup of ca signing process

If this is the first time you are using your CA you need to set up some files.  The files are referred to in the config file used by openssl ca command

touch index.txt
echo '01' > serial.txt

  • index.txt  is the certificate database index file.  This name is used in the config file option database =… .  For the format of this file see here. 
  • serial.txt contains the current serial number of the certificate. This name is used in the config file option serial =… .

Sign the certificate request

This takes the .csr file and signs it.

openssl ca -config casign.config -md sha384 -out mqweb.pem -cert cacert.pem -keyfile cacert.key.pem -infiles mqweb.csr

  • openssl ca – do the ca signing
  • -config casign.config – using the specified config file
  • -md sha384 – what message digest strength to use
  • -out mqweb.pem – put the signed certificate in this file
  • -cert cacert.pem – sign it with this ca file
  • -keyfile cacert.key.pem – sign it with this ca private  file
  • -infiles mqweb.csr – this is the input certificate request file

This displays the certificate, so check it is correct.  You get prompted

  • Sign the certificate? [y/n]:y
  • 1 out of 1 certificate requests certified, commit? [y/n]y

In the config file the important section is

[ ca_extensions ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints = CA:FALSE
keyUsage = keyEncipherment
extendedKeyUsage = serverAuth

Send the signed certificate back to the requestor.

Create the keystore to be used by mqweb and import the certificate

You can delete the certificate in the keystore using runmqckm -cert -delete -db mqweb.p12 -pw password -label mqweb .  This is not required.

openssl pkcs12 -export -inkey mqweb.key.pem -in mqweb.pem -out mqweb.p12 -CAfile cacert.pem -chain -name mqweb -passout file:password.file -passin file:password.file

This command creates the keystore (if requried) and imports the signed certificate and private key into the store with the specified name.   If a certificate exists with the same name, it is replaced.

  • openssl pkcs12 -export – this says a pkcs12 file will be created
  • -inkey mqweb.key.pem – using this private key file
  • -in mqweb.pem – and this signed certificate
  • -out mqweb.p12 – output put it to this pkcs12 keystore, used by mqweb
  • -CAfile cacert.pem – using this CA certificate
  • -chain – include all of the certificates needed when adding the certificate to the key store
  • -name mqweb – create this name in the keystore.  It is used to identify the key in the key store.
  • -passout file:password.file -passin file:password.file – use these password files

There is no config file for this operation.

Use chmod and chown to protect this keystore file from unauthorised access.

Change the mqweb configuration file.

<keyStore id="defaultKeyStore" 
          location="/home/colinpaice/ssl/mqweb.p12"  
          type="pkcs12" 
          password="password"/> 
<!-- the trust store is used when authenticating 
<keyStore id="defaultTrustStore" 
          location="/home/colinpaice/ssl/key.jks" 
          type="JKS" 
          password="zpassword"/>
-->
<ssl id="defaultSSLConfig" 
     keyStoreRef="defaultKeyStore" 
     serverKeyAlias="mqweb" 
     clientAuthentication="false" 
     clientAuthenticationSupported="false" 
/>
<!--trustStoreRef="defaultTrustStore" sslProtocol="TLSv1.2"
-->

The keystore name and server key alias which identifies which certificate to use,  are highlighted.

Stop mqweb

/opt/mqm/bin/endmqweb

Start mqweb

/opt/mqm/bin/strmqweb

Check /var/mqm/web/installations/Installation1/servers/mqweb/logs/messages.log for

Successfully loaded default keystore: /home/colinpaice/ssl/ssl2/mqweb.p12 of type: pkcs12.   This means it has successfully opened the keystore.

If you do not get this message use a command like grep ” E ” messages.log  and check for messages like

E CWPKI0033E: The keystore located at …. did not load because of the following error: keystore password was incorrect.

Import the CA certificate into Chrome

You need to do this once for every CA certificate

I have several profiles for Chrome.  At one point it hickup-ed and created a new profile, my scripts carried on updating the old profile until I realized a different profile was now being used.

Find the keystore

In Chrome use the url chrome://version/ this gives the profile path, for example /home/colinpaice/snap/chromium/986/.config/chromium/Default

You can remove the old certificate CA

certutil -D -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb -n myCACert

  • certutil -D – delete the certificate
  • -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb – from this keystore directory
  • -n  myCACertr with this name

Add the new CA certificate

certutil -A -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb -t “C,,”  -i cacert.pem -n myCACert

  • certutil -A – add a certificate
  • -d sql:/home/colinpaice/snap/chromium/986/.pki/nssdb – into this keystore directory
  • -t “C,,” – give it these permissions.
    • C says Trusted CA.   The certificate appears in Chrome under “certificate authorities”
  • -i cacert.pem – import this certificate
  • -n myCACert – with this name

Tell Chrome to pickup the changes

Use the url chrome://restart to restart chrome

Try using it.   Use the url like https://127.0.0.1:9443/ibmmq/console/

You should get the IBM MQ Console – login

Understanding the TLS concepts for using certificates to authenticate in mqweb.

This blog post gives background on setting up mqweb to use digital certificates. The IBM documentation in this area is missing a lot of information, and did not work for me.   I started documenting how to set up the certificates for the mqweb support, and found I was having to explain details of what was needed, before giving the command to do it.  I have also tried to cover it from a production environment, where you will use signed certificates, and automated deploy etc, instead of GUIs.   I suggest you read it before trying to set up mqweb with TLS .   Most of the content applies to the REST API as well as web browsers, but tools like CURL and Python  are much easier to set up and use.

If I have made mistakes (and it is easy to do so) or there are better ways of doing things,  please let me know.

It covers

  • How certificates are used
  • Different levels of mqweb security and authentication
  • How is mqweb security set up
    • The mqweb server end
    • At the web browser
  • How does the handshake work if certificates are being used?
  • Commands to issue REST commands to MQWEB
  • Setting up certificates.
    • Distinguished names
    • Certificate purpose for signed certificates
    • Self signed certificate
    • Strong protection
    • Certificates expire
  • Encrypting passwords in the config file
  • Which keystores should I use

How certificates are used

As part of the TLS handshake to do authentication, a certificate is send from the sender to the end user to identify the server. If you are doing authentication with certificates, a “client” certificate is sent up to the server providing information about the subject (person) and how the certificate can be used, for example for authentication or just providing encryption.

You can have “self signed” certificates and certificates signed by a certificate authority.

With self signed, you need a copy of the certificate at each end of the connection, so the certificate received from the client is checked with the server’s copy.  With more than one certificate, it quickly becomes impractical to use self signed certificates, and these would not be used in production. (Consider you have 100 partners you work with; you have 100 Linux servers you need to keep up to date; and on average, a certificate expires every week) . Also emailing a copy of the self signed certificate to a recipient is open to a “man in the middle” attack where your certificate is replaced with a bogus one, and so is not secure.  Self signed are fine for test systems.

The term Certificate Authority(CA)  is a term used for a chain of certificates which are used to sign other certificates.  If both ends share a common certificate, then the receiver can validate the payload.  Strictly, the CA owns the root certificate which certifies the rest of the chain.

With a signed certificate, a checksum of the certificate is encrypted by the signer, and appended to the certificate as part of the “signing process”. When the a certificate is sent to a recipient, it contains the certificate authority’s certificate. The recipient checks to make sure the certificate authorities match, then does the same calculation on the checksum and compares it with the value passed in the certificate. If they match the passed certificate is valid.
This means that the server only needs to have the certificate authority certificate chain in its trust  store, it does not need the individual client certificates.  Similarly when the server sends down the certificate to the browser, the browser does not need a copy of the certificate, just the CA chain.  If you change the certificate at the server end, you do not need to change the browser end.

This greatly simplifies the use of digital certificates, as you only need one certificate in the server, to identify the server, each user needs just one certificate and there is no emailing of certificates.

CA signed certificates are more secure than self signed certificates, and the validation has stronger checks.  A certificate has “extensions” which define how the certificate can be used, for example signing code, but not for authentication; it can be used to identify a server, but not an end user.

Certificates have a validate date range not-valid-before and not-valid-after. You need a process to renew certificates before they expire. This applies to the “client” certificate and the certificate authority certificate.

Certificate have a Distinquished Name, for example CN=colinpaice, OU=Test, O=IBM,C=GB. Where CN is Common Name, and is the user name, OU is Organization Unit, O is the Organization and C is the Country.

When I used curl with a self signed certificate I got

curl: (60) SSL certificate problem: self signed certificate in certificate chain
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

If you use the curl – – insecure option  you avoid this message, and it works.

Different levels of mqweb security and authentication

There are different levels of security and authentication

  1. No TLS. Data flows between a web server and web browser in clear text.  This is not used by mqweb.
  2. The server sends a certificate to the web browser. This provides an encryption key for traffic. It also provides the URL of the web server.  For a CA signed certificate, the web browser then checks the URL coming from the web server, with the names in the certificate to make sure they match. This gives protection from a bad person trying to point your browser at their server using a different URL. If you are not using certificates to authenticate, you logon with userid and password.  Data flowing is encrypted using information sent down in the certificate.   This is used by mqweb.
  3. As 2), and in addition, a certificate is sent up from the client and used instead of entering a password and userid. This is configurable at the mqweb level.  The certificate is validated by the server, and the Common Name is used as the userid.  This means
    1. Every certificate needs a unique CN
    2. a password is not used
    3. DN:CN=colinpaice,O=SSS,OU=TEST,C=GB and DN:CN=colinpaice,O=SSS,OU=PROD,C=GB

would both be accepted for userid colinpaice if they both had the same CA.

In all cases the userid is checked with the information in the mqweb configuration xml file.

You can specify userids or groups in the xml file.  It is better to specify groups than userids as it is less administration. If a person joins a department, or leaves a department, then you just have to update the group, not all of the configuration files.

How is mqweb security set up?

The mqweb server end

The server’s certificate and private key is stored in a key store – this store will have one, and can have many certificates and private keys

The certificates used for client authentication are stored in the trust store.

For example with the definition in the mqwebuser.xml

<ssl id="defaultSSLConfig"
  keyStoreRef="defaultKeyStore" serverKeyAlias="colincert"
  trustStoreRef="defaultTrustStore"
  sslProtocol="TLSv1.2"
  clientAuthentication="true"
  clientAuthenticationSupported="true"
/>

The keyStoreRef=”defaultKeyStore” says look for the definition with defaultKeyStore. This will point to a key store. Use the certificate with the name defined in the serverKeyAlias

So with

<keyStore id="defaultKeyStore"
          location="/home/colinpaice/ssl/key.pkcs12"
          type="pkcs12"
          password="zpassword "/>

the keystore /home/colinpaice/ssl/key.pkcs12 with certificate colincert will be used.

The trustStoreRef=”defaultTrustStore” says look for the definition with defaultTrustSstore. This will point to the trust store.

With

<keyStore id="defaultTrustStore"
   location="/home/colinpaice/ssl/key.jks"
   type="JKS"
   password="zpassword"/>

the trust store at location /home/colinpaice/ssl/key.jks will be used.

This needs to have the CA certificates, and any self signed certificates.

At the web browser

The web browser needs to have the self signed certificate or the CA certificate, for the certificate which is sent to the browser as part of the handshake “Hello I am the server”, so it can be validated.  If the certificate cannot be validated,  for example there was no copy of the self signed certificate, the browser will notify you and may allow you to accept the risk.   This is insecure, and ok for a test environment.

If certificates are to be used for authentication, then the web browser also needs the user’s certificate and private key, along with with any CA certificates.

How does the handshake work if certificates are being used?

The web server extracts the specified certificate from the keystore and sends it to the web browser.

The certificate is validated either with the browser’s self signed copy, or with the browser’s copy of the CA certificates.

For a signed certificate, the url from the web server is checked with the names in the “Certificate Subject Alternate Name” extension within the certificate. For example IP:127.0.0.1

If client authentication is used, the certificates are read from the server’s trust store. The DN of the self signed certificates and the DN of the CA certificates are extracted and sent down to the browser.

The browser takes this list and checks through the “user” certificates in its key store, for those self signed certificates with a matching DN, or those certificates which have been signed by the CA.

The list of matching certificates is displayed for the user to select.
For example

If the mqweb server trust store had

  • CN=colinpaice,ou=SSS1,o=SSS,C=GB self signed
  • CN=CA,O=SSS,C=GB Certificate Authority

and the browser’s keystore had

  • CN=colinpaice,ou=SSS1,o=SSS,C=GB self signed
  • CN=colinpaice1,ou=ZZZZ,o=SSS,C=GB self signed
  • CN=colinpaice2,ou=signed,o=SSS,C=GB signed by CN=CA,O=SSS,C=GB
  • CN=colinpaice3,ou=signed,o=ZZZ,C=GB signed by CN=CA,O=ZZZ,C=GB

the list displayed to the user would indicate the following certificates

  • CN=colinpaice,ou=SSS1,o=SSS,C=GB
  • CN=colinpaice2,ou=signed,o=SSS,C=GB

The Chrome and Firefox remember this decision until the browser is restarted, so if you want to change to use a different certificate – tough; you have to restart the browser.

The browsers use a keystore which you can access through the browser or commands like certutil or pk12util.

Commands to issue REST commands to MQWEB

If you use commands like curl, you can specify the certificate authority file, the user certificate, and the user private key using parameters. You do not need a keystore.  For example 3 .pem files are used, one for the certificate, one for the private key and one for the CA certificates.

curl –cacert ./cacert.pem –cert ./colinpaice.pem:password –key colinpaice.key.pem https://127.0.0.1:9443/ibmmq/rest/v1/admin/qmgr

If you use python requests package you can issue “requests” and again specify the various files needed for the certificates.

Setting up certificates.

It is fairly complicated setting up certificates as there are many options.

Distinguished names

Your organization will have standards you need to conform to. For example

The Distinquished Name (eg CN=colinpaice,ou=test,o=SSS,C=GB). Organisation is usually your enterprise name, OU could be department name, CN could be userid or other name. You can set up MQ channels to restrict the DN for example to containing ou=test,o=SSS,C=GB.

I set up a DN with C=GB,O=cpwebuser,CN=colinpaice. If I look at the certificate it has CN = colinpaice, O = cpwebuser, C = GB – in a different order.

If I look in the browser’s keystore, the certificates show up under the “O” value, so under “org-cpwebuser”.

As the CN is used as the userid, make sure it is the same case. On my linux machine my userid is colinpaice, the CN must be colinpaice.

Certificate purpose for signed certificates

If you create a certificate signed by a CA (even your private CA) the following checks are done during the TLS handshake.

  • The certificate has been signed with “serverAuth” to allow it to be used to authorise servers.
  • The key usage has  been signed with “Authentication”
  • The certificate has the IP address of the server.

If any one of these fail, the handshake fails.

A certificate can be used for many purposes, for example signing code, signing certificates (by a certificate authority). These properties are defined when the certificate is signed.

Both client and server certificates needs keyUsage = digitalSignature.

The Extended Key Usage (EKU) indicates the purpose, or what the certificate public key can be used for.

  • A client certificate needs extendedKeyUsage = clientAuth
  • A server certificate needs extendedKeyUsage = serverAuth.

The command openssl x509 -purpose -in colinpaice.pem -inform PEM -nocert gave

Certificate purposes:

  • SSL client : Yes
  • SSL client CA : No
  • SSL server : No
  • SSL server CA : No

So we can see this has clientAuth key usage.

If these are not set up properly  you can get errors about unauthorized access and “SSLHandshakeException: null cert chain” errors.

use openssl x509 -in colinpaice.pem -noout -text |less
and search for Usage

This gave me

X509v3 Key Usage: 
   Digital Signature
X509v3 Extended Key Usage: 
   TLS Web Client Authentication

 

Self signed certificate

A self signed certificate is considered weaker than a signed certificate, and some of the checks are not done.

If you are using a self signed certificate, the certificate needs keyUsage = digitalSignature, keyCertSign , it does not need  the IP address of the server, nor extendedKeyUsage.

It needs to be installed into the browser keystore as Trusted.  If it is not flagged as trusted, then the browsers give errors, and may allow you to continue if you accept it the risk.

Strong protection

There are different strengths of encryption. Stronger ciphers take longer to break. Some encryption or hashing techniques are considered weak, and may not be accepted. For example SHA1 is weak (some browsers will not accept it), SHA256 and SHA348 are much stronger.

Some encryption can be offloaded to specialized chips, so have a smaller CPU cost. You need to use your enterprise standard levels of encryption and hashing.

Certificates expire

All certificates (user and CA) have a valid date range. If they are used beyond their end date, you will get an error, and it will not work. You need to have a process in place to renew certificate, including CA certificates.  If you use an external CA, it can take days to get a new certificate and deploy it.

Keystores

Some processing need a keystore.  For example Firefox and Chrome use a nss format keystore.  The mqweb server needs a keystore to store the certificate to identify the server, and can use a truststore to contain remote authentication certificates.

There are a variety of tools to manage keystores.  IBM provide GUI interfaces such as strmqikm, and a command line interfaces runmqikm.   There is keytool from Oracle, and other tools such as openssl, pkcs12 and certutil.

There are different sorts of keystores

  • nssdb – used by browsers to store keys
  • pkcs12 has certificates and the  private key
  • cms  contains keys certificate etc
  • jks – Java keystore  – used by java to contain certificates

Certificates can be in different formats

  • .pem this is a certificate encoded in base 64 encoding.   This may look like
-----BEGIN CERTIFICATE-----
MIIDfzCCAmegAwIBAgIURubFS5yEwZYi//7Qx0kTmX/LnMUwDQYJKoZIhvcNAQEL
...
-----END CERTIFICATE-----
  • .der this is a binary format

I found it easiest to create certificates using openssl, and import them into the keystores, rather than use a GUI and then export them.  This means it it can be scripted and automated, and requires less work.

Encrypting passwords in the config file

Keystores usually have a password.

For example in the mqwebuser.xml file is

<keyStore id="defaultTrustStore"
    location="/home/colinpaice/ssl/key.jks" 
    type="JKS"
    password="zpassword"/>

This password can encrypted using the /opt/mqm/web/bin/securityUtility command. See here.

For example to encrypt the string “zpassword”

/opt/mqm/web/bin/securityUtility encode –encoding=aes zpassword gives

{aes}AJOmiC8YKMFZwHlfJrI2//f2Keb/nGc7E7/ojSj37I/5

doing it again gave a different value

{aes}AMsUYgpOjy+rxR7f/7wnAfw1gZNBdpx8RpxfwjeIG8Wj

Your mqwebuser.xml file would then have

<keyStore id="defaultTrustStore"
    location="/home/colinpaice/ssl/key.jks" 
    type="JKS"
    password="{aes}AMsUYgpOjy+rxR7f/7wnAfw1gZNBdpx8RpxfwjeIG8Wj"/>

Which keystores should I use?

I used openssl to define and manage my certificates, because the IBM tools did not have all of the capabilities.

I used a pkcs12 (.pkcs12 or .p12) store for the keystore and a jks(.jks) store for the trust store.

Firefox and Chrome use a nssdb (Netscape) database.   I used tools pkcs12 to insert certificates, and certutil to display and manage the database.

Getting MQConsole (brower interface to administer MQ via mqweb) working

It was a new year, as I sat in my basement cave while the gale force winds blow around the house, I thought I would try to use the new MQWeb and MQConsole, and see how it stands up to “the Paice treatement”.    The MQWeb allows you to administer MQ from a web browser, or a rest interface (for example using CURL or Python).  This technology has been around for a few years now.  I know it is being enhanced every few months through the continuous delivery channel.

The installation and getting started reminded me of an old car belonging to my father.  The car was not easy to get started (it had a starting handle!), but once it was started it worked pretty well.

Getting it up and running in a test sandbox took about 1 hour.   It took me about two week to get mqweb set up properly using digital certificates, and to document how I did it.  Being security related, there must be a team which tries to make it as hard as possible to diagnose problems so as not to provide useful information to a hacker.  It also took a while to  work out how to use mqweb  in an enterprise where you have multiple machines and have to support many users.  It also feels a bit buggy and some of it was frustrating, but as it is being continuously improved, I am sure it will get better.

Ive written some blog posts

I had MQ 9.1.3 running on my laptop running Ubuntu 18.04.

Getting it installed and up and running.

Initially I followed the  9.1 instructions here.   After lots of clicking and guessing I got to this page which gave me some instructions (but they were not very helpful). There are various mistakes on the page such as var/mqm/web should be /var/mqm/web.  I ignored the instructions and simply used sudo apt install /home/colinpaice/…/ibmmq-web_9.1.3.0_amd64.deb to install it.

The configuration file /opt/mqm/web/mq/samp/configuration/basic_registry.xml has predefined userids and the configuration is suitable to have an initial look at the MQWEB.

I used

cp /opt/mqm/web/mq/samp/configuration/basic_registry.xml 
/var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml

to copy the configuration file.

Starting and stopping the mqweb

The strmqweb command failed for me.   This was strange  as commands like strmqm works.  This is because there is a symbolic link /usr/bin/strmqm which points to /opt/mqm/bin/strmqm, but no link for the mqweb commands.

See here  which explains there is a /usr/bin/strmqm → /opt/mqm/bin/strmqm , but not for the mqweb stuff. I think this is an IBM Whoops.

I created these myself using

sudo ln -s /opt/mqm/bin/dspmqweb /usr/bin/dspmqweb
sudo ln -s /opt/mqm/bin/endmqweb /usr/bin/endmqweb
sudo ln -s /opt/mqm/bin/setmqweb /usr/bin/setmqweb
sudo ln -s /opt/mqm/bin/strmqweb /usr/bin/strmqweb

The configuration file is deep down a directory tree.

I created  a symbolic link to the file using

ln -s /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml web.xml

so I can do  gedit ~/web.xml

and if you forget where the file really is, use ls -l web.xml

I used the strmqweb command to start the mqweb server.

I used dspmqweb and got

MQWB1124I: Server ‘mqweb’ is running.

MQWB1123E: The status of the mqweb server applications cannot be determined.  A request was made to read the status of the deployed mqweb server applications, however the data appears corrupt. This may indicate that there is already an mqweb server started on this system, probably related to another IBM MQ instance.

The MQWB1123E message only happened occasionally – I think it is a timing problem and can be ignored.

I stopped the mqweb instance using endmqweb

Log files

There is a file /var/mqm/web/installations/Installation1/servers/mqweb/logs/console.log  which has audit type statement in it.

There is a file /var/mqm/web/installations/Installation1/servers/mqweb/logs/messages.log which has more messages (including time stamps).   This file is more useful.

I defined a symbolic link to this file, to make debugging easier.

ln -s/var/mqm/web/installations/Installation1/servers/mqweb/logs/messages.log messages.log 

When the strmqweb command is issued,

  • it deletes the previous console.log
  • it rename the messages.log to a file with a time stamp in the file name
  • it deletes any other message logs files.

After starting and stopping the web server several times the only files I had were

  • messages_20.01.05_15.18.50.0.log
  • messages.log
  • console.log

You may want to put the strmqweb command in a shell script which saves away any message and console files.

The command dspmqweb gives output like

MQWB1124I: Server 'mqweb' is running.
URLS:
  https://localhost:9443/ibmmq/rest/v1/
  https://localhost:9443/ibmmq/console/

This tells you which URL you need to use.

Note: port 9443 is the default port for WebSphere Liberty Profile.  If it is in use you will have to configure a different port.

First logon

I logged on to Firefox browser using the address https://localhost:9443/ibmmq/console/Make sure you the https in https:… .  If you use http: without the https, the logon fails with message “The connection was reset”.

Using https:… gave me big error screen and

Warning: Potential Security Risk Ahead 
localhost:9443 uses an invalid security certificate.
The certificate is not trusted because it is self-signed.
Error code: MOZILLA_PKIX_ERROR_SELF_SIGNED_CERT

While  you are exploring the mqconsole, you can accept this.  To fix it properly is a big piece of work.  See my other blog posts.

I signed on using userid mqadmin and password mqadmin and it showed the queue managers.

Select the row of an active queue manager. The table header changes to give options.  Select properties to display the queue manager properties.

The queue manager attributes do not refresh in real time

You have to go back to the queue manager table and re-display the data.   This is not a big problem as the attributes do not typically change frequently.  I noticed this when I changed an accounting parameter, and the attribute page did not show the change.

Adding widgets to the dashboard.

There are two ways of adding widgets for MQ objects.

  1. From the list of queue manages, select a queue manager, then on the title like, click on the “…”  (more actions) button and select “Add new dashboard tab”. This creates a dashboard with all of the MQ Objects defined, MQ Queues, client connections, MCA connections, listeners etc. You can select and delete widgets you do not need.
  2. Click on the “Add widget” button.

It may be quicker and easier to use the first option to add all widgets and delete the widgets you do not need.

Create more tabs

At the top of the browser window next to the “tab”,  click on the “+”. This defines a new dashboard, use the add widget button to select the widget you want to define.

Each userid has their own dashboard (tab layout and widget)

See the next topic if you want people to have the same dashboard.

Export the dashboard for enterprise deploy or backup

At the top of the screen is an icon with three vertical dots for dashboard settings. You can export the dashboard and widgets to a JSON file.

  • You can change the queue manager names and import it on another queue manager.  This is useful to enterprise users who have to support many queue managers in a similar environment.  Being a JSON file you can process the JSON to change queue manager names.  I could not find a way of importing it except from a web page.  This make it challenging to deploy automatically.
  • You can have another user import it, so they get the same dashboard.  If it changes, they have to import it manually.
  • You may want to export your dashboard every week and back it up.

Using the widgets

I clicked on the “Queue on …”  widget.

I clicked on the “Queue depth” column for queues, and it quickly sorted the queue depth.

I could see I had a total of 33 non system queues. By clicking on the settings wheel, I could select “show system objects”.

If you select the settings wheel, you can select a different queue manager.  By changing this you could have one tab showing queues on different queue managers on the machine, and another tab showing channels on different queue managers on the machine.  You could also have a tab per queue manager, and have queues and channels for one queue manager on that tab.

I could refresh a widget by using the refresh icon.

There is a search box at the top of each widget. It searches for the value in any column. So typing in 003 gave me queue CP00003 and DEEPQ with depth 1000003.
At the bottom of the widget it said Total: 90 Filtered:2

If you select a row, the search box changes and give you a list of actions.

  • Delete queue
  • Properties
  • Put message
  • Browse message
  • More actions → Manage authority records
  • 1 item selected
  • Deselect

You can select all the objects in a widget by typing “a” , or to deselect using “shift a”.  Note: it selects all items – not just the filtered items. For example I typed “a” and the header line said “33 objects selected”. At the bottom of the widget is said total 33 filtered 8.  So be careful if you were thinking of doing bulk changes on all objects.

I was unable to select more than one object, using the cursor keys.

It was easy to delete widgets by selecting the X icon.

You can move the widgets around by grabbing the title line and dragging it.

If you hover on the title line of a widget, a pencil icon appears which allows you to rename the widget.

You can control how many widgets are displayed per line by clicking on the down arrow in the tab (at the top of the page) and selecting how many columns to use.  This is a not very smart.

  • I selected 5 column layout.
  • It did not reflow the widgets automatically.  Each line had 2 widgets and lots of space to the right.  I could drag a widget to the top line.  If I then went to 2 column layout, and back to 5 column layout – I got back to two widgets per line
  • If you select an item, the search box becomes a list of icons.  With a narrow widget, you only get the as many icons as fit in the space, for example you do not get the  “…” (more action) icon.
  • The formatting within a table is not very smart. I had a truncated queue name SYSTEM.ADMIN.CH and lots of space for the queue depth. I think the data is displayed in a table and the columns are the same width, and not changeable.

It may be better to have no more than 2 or 3 widgets per line.

Using operating system security.

The basic mqweb configuration file used hard coded userids mqadmin with password mqadmin. This is not very secure.

You can use the operating system userids and passwords using a different configuration file

I used

  • cp /opt/mqm/web/mq/samp/configuration/local_os_registry.xml  /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml
  • chmod o+w /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml
    • to give me update access to the file.

I changed my file to have

<enterpriseApplication id="com.ibm.mq.console">
  <application-bnd>
    <security-role name="MQWebAdmin">
      <user name="colinpaice" realm="defaultRealm"/>
    </security-role>
    <security-role name="MQWebAdminRO">
      <group name="test"/>
    </security-role>
   </application-bnd>
</enterpriseApplication>

Notes.

  • The realm=”defaultRealm” is to do with Jave Enterprise Edition security. Just specify it.
  • Each security-role name section must be unique. I specified <security-role name=”MQWebAdminRO”>… twice. Only the last one was used, I was hoping it would be cumulative.
  • You can specify multiple <user …> or <group… > lines.

See here  and here  for pointers to the IBM documentation.

Managing mqwebuser.xml

You can include files into the mqwebuser.xml files using the xml

<include optional="true" location="pathname/filename"/>
or
<include optional="true" location="url"/>

You can put groups of definitions in one file and have them included.

For example in the file payroll.xml have

<group name="mqsysprog"/>
<group name="payroll"/>

For each of the configuration files for the payroll queue managers have

<security-role name="MQWebAdmin">
  <include optional="true" location="payroll.xml"/> </security-role> <security-role name="MQWebAdminRO"> <group name="test"/> </security-role>

How do I check what role I have?

At the top right of your browser window is a porthole with a circle in it. Click on this, and then click on “about”. It gave me

Principal:colinpaice - Administrator (Password Authentication)
A different userid gave
Principal:testuser - Read-Only Administrator (Password Authentication)

Can I have the logon time out?

Yes, you set a time out value using the ltpaExpiration value. See here.

Use dspmqweb properties -a|grep ltpaEx  and note the ltpaExpiration value.

Use  setmqweb properties -k ltpaExpiration -v time    to set the time in minutes.

Note:

  • After you are logged on for this time period, your session is cancelled and you have to logon again, this happens whether the session is busy or idle.
  • The setmqweb command updates the mqwebuser.xml file on disk. If you were editing the file you will need to reload the file from disk and reapply the changes.
  • The above setmqweb command added <variable name=”ltpaExpiration” value=”10″/> to the mqwebuser.xml file. You could just update the file yourself and avoid this concurrent  update problem.

There is one timeout value for all users, so if you have a screen displaying charts from mqweb, this will also time out.

If you are using certificates to provide authentication

  • your session will be dropped, and automatically reconnected.
  • you cannot logoff – you have to drop the browser tab
  • in the top right of your page the icon will be a black circle with a which “i” in it.  If you are not using certificates this will be a porthole with a circle in it.

Understanding queue high events and time since reset

I  was testing out my java program for processing PCF messages and snagged a “problem” with queue high events.

I had set max depth of the queue to 1.

I put two messages out of syncpoint, and got the following events on the SYSTEM.ADMIN.PERFM.EVENT queue.

"PCFHeader":{
  "Type" :MQCFT_EVENT
  ,"ParameterCount" :6
  ,"Command" :MQCMD_PERFM_EVENT
  ,"Control" :MQCFC_LAST
  ,"Reason" :Queue_Depth_High
  ,"MsgSeq" :1
  ,"Version" :1
  }
  ,"QMGR_Name" :QMA 
  ,"Base_Object_Name/mqca_Base_Q_Name" :CP0000 
  ,"Time_Since_Reset" :53
  ,"High_Q_Depth" :1
  ,"Msg_Enq_Count" :1
  ,"Msg_Deq_Count" :0

and

PCFHeader":{
  "Type" :MQCFT_EVENT
  ,"ParameterCount" :6
  ,"Command" :MQCMD_PERFM_EVENT
  ,"Control" :MQCFC_LAST
  ,"Reason" :Queue_Full
  ,"MsgSeq" :1
  ,"Version" :1
 }
 ,"QMGR_Name" :QMA 
 ,"Base_Object_Name/mqca_Base_Q_Name" :CP0000   
 ,"Time_Since_Reset" :0
 ,"High_Q_Depth" :1
 ,"Msg_Enq_Count" :0
 ,"Msg_Deq_Count" :0

 

I think this is telling me

  1. The Queue high event occurred 53 seconds after some other event
  2. One message was put, causing the queue high event
  3. The queue full event occurred 0 seconds after some event.  The documentation says “Time, in seconds, since the statistics were last reset”
  4. A message was put to the queue, unsuccessfully, as Enq_Count is zero.

I think the documentation is not clear.  I did not issue a reset statistics command.   The time since reset varies between 0 and over 6000 seconds.   My qmgr Stats interval was 10 seconds.

I think the time_since_reset is time since previous event or something else, so looks pretty useless.  When I issued a reset qmgr reset(Statistics) it made no difference to the time since reset.

This time value is MQIA_TIME_SINCE_RESET in the PCF.

 

I noticed that the event messages are non persistent, so make sure you process the messages before you shut down your queue manager!

Processing Activity Trace PCF messages with Java

This post covers some of the things I found about extending my java program for processing PCF, to cover activity trace 

Operation date has an inconsistent format

The field with MQCACF_OPERATION_DATE  is a field with format SimpleDateFormat(“yyyy-MM-dd” but is a 12 byte field (instead of the 10 you  might expect), and is padded with nulls instead of blanks.  You need to do date = …getStringParameterValue(MQConstants.MQCACF_OPERATION_DATE).substring(0, 10) to  capture the key data.

 

MQIACF_APPL_FUNCTION_TYPE.

This maps to fields MQFUN_TYPE_* with values like MQFUN_TYPE_UNKNOWN, MQFUN_TYPE_USERDEF, MQFUN_TYPE_JVM.   I got Unknown, and do not know what this means.  I think they are connected to the iSeries.

Using the high resolution timer, with microsecond precision.

Puts and gets have a high precision time value. The field MQIAMO64_HIGHRES_TIME gives a microsecond level precision of the time of the time.

To process these values I used

long milliseconds = (long) p.getValue()/1000;
long microseconds = (long ) p.getValue()%1000000;
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(milliseconds);
Date dateTimeVal = cal.getTime(); 
SimpleDateFormat sdfFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss", Locale.ENGLISH);
System.out.println(""High res timer:" + sdfFormat.format(dateTimeVal 
                                      + "." 
                                      + String.format("%06d", microseconds)  // add microseconds
                                      +"Z") ;

You can use the micro seconds value when doing calculations such as duration between operations.

You get the high resolution timer when doing MQGET, MQPUT, MQPUT1, for the other calls, such as MQOPEN, MQCLOSE, MQCMIT you only get the timer from the “Operation_Time” file for example 18:09:34.
It is not easy to find where your application is spending its time.

For example

MQ Verb OperationTime OperationDuration micro seconds Hi res timer
MQOPEN 18:09:34 56
MQPUT 18:09:34 66 18:09:34.747837
MQCMIT 18:09:34 12
MQGET 18:09:34 60 18:09:34.754299
MQCLOSE 18:09:34 54

This application was doing just MQ verbs. The time between the start of the get and the start of the put 6462 micro seconds.  The put took 66 microseconds, and the commit took 12 microseconds, so there was 6384 microseconds unaccounted for.    This reported duration is at the queue manager level.   There will be elapsed time from issuing the request to get into the queue manager, and back out again.

I put a microsecond timer in my client program to time the MQ requests.   After the MQOPEN, the first MQGET took 2800 microseconds, the second MQGET took 500 microseconds.

There is a big difference in the time as reported by the queue manager, and the time as seen by the application,

  • Work has to be done from the API request to be able to issue the network request.
  • The request has to flow over the network
  • The queue manager has code to catch the network request and issue it to the queue manager
  • there is the duration of the request – as seen by the accounting trace
  • The reply has to be transformed to a network request
  • The reply has to flow over the network
  • The reply has to be caught and returned to the application.

If the application was using local bindings it would be quicker, as there would be no network component.

The timer code was

long start = System.nanoTime();
queue.get(msg, gmo);
long duration_in_microseconds = (System.nanoTime() – start) /1000;

Note: the machine may not be able to provide a timer accurate at the nanosecond level.

Embedded structures

Requests for get have embedded structures for MQMD (type MQBACF_MQMD_STRUCT  -7028) and GMO (MQBACF_MQGMO_STRUCT – 7027).
Requests for put have embedded structure for PMO( MQBACF_MQPMO_STRUCT – 7029).

The parameter types are the values for MQ CallBack, and have been reused.

The data is a byte string (MQCFBS) .  I could not find how to easily extract the fields from these structures and display them with having to construct each field myself.   The integer fields can be in bigendian or little endian.  The version field for me was “01000000”  or “02000000” which little endian.  If it was big endian the value would have been “0000001”

I had to write some methods to chomp my way along the string to produce the fields.  I could not find a way of passing the string to a  method and get the fields back.

I created a method for longs, strings, bytes, byte.  I found it easiest to use the get StringValue for the structure.    This gives it to you in a hexadecimal string.   You need to do additional processing for example convert from hex to a String,  convert the string to an integer using base 16.   Byte arrays could be used unchanged.