Emir Gaza (Consulting IT Specialist, Hursley Software Lab Services) and I are currently putting together a list of SSL gotchas based on our personal experiences and, of course, those of our customers. Our list covers many problems and solutions already well documented in the manuals (e.g. Error messages), but what we’re trying to do is compile a single list containing both common problems and those with sometimes cryptic solutions.

We aim to expand this list in future with more items and more detail, but for now, here’s the list we have compiled… Comments most welcome…

1.1 CSQX630E Channel requires SSL

Platform: z/OS

Problem description

This may happen when you start an SSL channel, and there are no SSL tasks running.

Solution

To start SSL tasks use ALTER QMGR( ) SSLTASKS(n) and restart the channel initiator.

1.2 CSQX642E No SSL certificate for channel name

Platform: z/OS

Problem description

You attempt to start an SSL channel with mutual authentication (receiver has SSLCAUTH(REQUIRED)) and you get this error message.

If you change SSLCAUTH to OPTIONAL the channel starts!

This may happen when the SSL certificates do not have the correct Key Usage attributes.

Solution

Key Usage must be:

  • Either blank, or
  • If not blank, it must include HANDSHAKE

A certificate with this Key Usage will not work:

Key Usage: DATAENCRYPT

This will work:

Key Usage: HANDSHAKE, DATAENCRYPT

1.3 Certificate not signed

Platform: z/OS

Problem description

You sent a certificate for signature by the Certification Authority, but, when you list the certificate, you find that Subject and Issuer are the same. This means that the certificate is not signed.

Solution

The most probable cause is that you did not ADD the certificate to the RACF database.

1.4 CSQX686E SSL private key error

Platform: z/OS

Problem description

If you list the certificate that gives you this error, you will see that it has Private Key = NONE.

Most probably you sent a certificate for signature and then added the signed certificate with the wrong label.

For example, you sent a certificate with label ibmWebSphereMQCSQ2 and added the signed certificate with label ibmWebSphereMQCSQ1. The latter will not have a private key.

Solution

Add the signed certificate with the same label of the original, self-signed certificate sent for signature.

1.5 CSQX632I SSL certificate has no associated user ID

Platform: z/OS

Problem description

MQ cannot find a userid from the certificate. The channel will run under the CHINIT userid (this may be a security exposure).

Solution

There are two solutions:

1.5.1 Install the peer certificates

Extract the peer certificates and install them in the RACF database. The label must match z/OS requirements (that is, ibmWebSphereMQ<qmgr>, not ibmwebspheremq<qmgr>). The certificate must be in the queue manager’s key ring.

1.5.2 Create a RACF MAP

This JCL maps a certificate to a userid:

RACDCERT ID(EMIR) DELMAP (LABEL(’MQMAP’))

RACDCERT ID(EMIR) MAP +

IDNFILTER(’CN=MQCA.O=IBM.C=GB’) WITHLABEL(’MQMAP’) TRUST

SETROPTS RACLIST(DIGTNMAP) REFRESH

RACDCERT ID(EMIR) LISTMAP (LABEL(’MQMAP’))

 

1.6 Certificate corrupted after FTP to z/OS

Platform: z/OS

Problem description

When transferring certificates to z/OS from distributed platforms, the certificates are corrupted.

Solution

The files must be received on z/OS with RECFM=VB.

Use the FTP command quote site recfm=vb

1.7 No need to restart the CHINIT

Platform: z/OS

Tip

If you change a certificate or key repository on MQ for z/OS V6, you can use REFRESH SECURITY TYPE(SSL) to pick up the updates.

This saves restarting the CHINIT.

Note this will not work if there are no SSL tasks already running. No SSL channels will run until at least 2 SSL tasks are started. To change the number of SSL tasks, you have to restart the CHINIT.

1.8 Key repository not found

Platform: Clients

Problem description

You write a client application and use the MQSCO.KeyRepository field to specify the key repository. The program fails because it cannot find the key repository.

Solution

The most probable cause, if the file name is correct, is that the file extension (for example, .kdb) has been specified. It must not be specified

1.9 Wrong type of key repository

Platform: Clients

Problem description

Your MQ Java or JMS application cannot access the key repository.

Solution

For Java client programs (either MQ classes or JMS), you must use a key repository of type JKS. Non-java components must use key repositories of type CMS. There are tools (available on the web) to convert between the two, but the process is not trivial.

1.10 CSQX631E/AMQ9631 CipherSpecs do not match

Platform: All

Problem description

You attempted to start a channel or client application connection. The start failed and found the CSQX631E (z/OS) or AMQ9631 (other platforms) in the error logs. This is caused because the CipherSpecs on each end of a channel do not match.

Solution

Alter the channel definitions and/or client application so that each end of the channel specifies the same CipherSpec. See here for more information: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp?topic=/com.ibm.mq.csqzaj.doc/sc12320_.htm

1.11 Corrupted certificates

Platform: All

Problem description

You attempt to import, add or use a certificate, which has been transmitted (e.g. via FTP) or copied using a text editor, and encounter errors.

Solution

The following types of certificate must be FTPed in ASCII:

  • PEM (privacy-enhanced mail)
  • Base64 encoded X.509

The following types of certificate must be FTPed in binary:

  • DER encoded binary X.509
  • PKCS #7 (CA certificates)
  • PKCS #12 (personal certificates)

Also, you should only processed in text editors that do not strip trailing blanks or perform other character changes (i.e. use NOTEPAD, not Wordpad).

1.12 Expired certificates

Platform: All

Problem description

You encounter errors when using certificates as they have expired. You can view the expiry of a certificate using RACDCERT commands (z/OS) or GSKit (other platforms).

Solution

You should have processes in place that replace/renew certificates before they expire.

1.13 Duplicate certificate serial numbers

Platform: All

Problem description

You encounter errors when processing certificates that have been signed using GSkit because more than one certificate has the same serial number.

This can occur, for instance, if you generate more than one certificate request using RACF (z/OS) and then sign them using GSKit (i.e. using the gsk7cmd command on Windows or Unix). By default GSKit can give multiple certificates the same serial number, meaning that only one of the signed certificates will be accepted by RACF - which validly treats all the signed certificates with the same serial number as the same certificate.

Solution

GSKit was never intended as a PKI substitute so you should manage serial numbers manually for the certificates you sign or alternatively sign your certificates using another SSL signing system (e.g. OpenSSL or RACF).

To manually set serial numbers use the ‘–sernum’ runmqckm option, as follows :

runmqckm -cert -sign -file <certreq file> -db <db file> -pw <password> -label <label> -target <cert file> -format ASCII -expire <expire days> -sernum <serial number>

Having to manually set serial numbers implies that you need a serial number authority (most likely the certificate authority itself) which uses a number naming convention.

1.14 GSKit GUI and command line differences

Platform: Windows + Unix

Problem description

You have problems administering certificates using the command line (gsk7cmd), when the GUI (gsk7ikm) works fine.

Solution

Be aware that different options are available in the GSKIT GUI and command line. For instance, both the distinguished name attribute ‘PC’ can be specified and expired key database passwords changed in the GUI, but neither of these features are available using the command line.

1.15 Add or receive?

Platform: Windows and Unix

Problem description

You are not sure whether to use ‘add’ or ‘receive’ when trying to import a certificate to a key database.

Solution

Use ‘receive’ for queue manager certificates and ‘add’ for CA certificates.

1.16 AMQ9660 or AMQ9657

Platform: Unix

Problem description

You see channel errors when starting channels, as they attempt to access a key database.

Solution

Ensure that the key database file permissions are set so that the MQ channel process can read from it. Note: There are other solutions to these error messages (see the error message documentation).

1.17 Problems using makecert

Platform: Windows

Problem description

You see unexpected errors returned from makecert commands.

Solution

There have been problems with some versions of makecert. Use V5.131.3617.0 or the latest version recommended by IBM service.

1.18 gsk6cmd, gsk7cmd or runmqckm?

Platform: Windows + Unix

Problem description

You are not sure which command line tool to use.

Solution

Although gsk6cmd, gsk7cmd and runmqckm are very similar, there are slight differences between them in terms of parameters and behaviour. Use the documented command relevant to the release of WebSphere MQ you are using, unless instructed differently by IBM service.

1.19 Problems migrating from V5.3 to V6.0 on Windows

Platform: Windows

Problem description

You encounter problems with SSL certificates and channels after migrating from WebSphere MQ V5.3 for Windows to WebSphere MQ V6.0 for Windows.

Solution

The SSL implementation differs between these two releases so migration of key repositories is required. Read the V6 SSL migration documentation (http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/com.ibm.mq.csqzao.doc/wmqm1000.htm) as early as possible because steps can be taken when implementing V5.3 SSL that will make a later migration to V6.0 easier.

1.20 Password not stashed

Platform: Windows + Unix

Problem description

You use the GSKit GUI (gsk7ikm) and subsequently encounter problems using the key database, possibly seeing errors related to passwords or stash files.

Solution

Ensure that you close the GUI using the close menu (i.e. ‘Key Database File -> Close’) the password isn’t stashed. To fix the problem start the GUI, select ‘Key Database File -> Open’, open the key database, select ‘Key Database File -> Stash Password’ and then close the GUI using ‘Key Database File -> Close’.

Possibly related posts: (automatically generated)