WebSphere MQ Everyplace can use private or public key encryption for message level security using the MQeMTrustAttribute, and for queue based security using the MQeWTLSCertAuthenticator. Any entity, for example queue manager, queue, application, person, which needs private and public keys must have a private registry. When the registry is initialised it generates and store the keys, if the associated information is supplied. The private key is encrypted and stored directly in the registry. The public key is sent to the certificate server, this returns a public certificate containing the public key and the registry stores the certificate. For message level security, the certificates must also be copied to public registries so that they are available to other entities that need them. This is not required for queue based security.
The certificate server normally issues certificates, which are valid for 12 months. The certificates cannot be used once they have expired, so it is important to keep track of the expiry dates and to renew the certificates before they expire.
Certificates can be examined using the com.ibm.mqe.attributes.MQeListCertificates class. This class opens a registry and allows you to list all the certificates in it, or to examine specific certificates by name. To use the class, you must supply the name of the registry and a MQeFields object that contains the information required to open it:
No other parameters are required to open the registry for this class. If the registry is a public registry with the name "MQeNode_PublicRegistry"and the class is initialised in the directory that contains the registry, the MQeFields object can be null. If the registry belongs to the mini-certificate server, its name is "MiniCertificateServer". If the registry belongs to a queue, its name is "MiniCertificateServer". If the registry belongs to a queue, its name is
MQeListCertificates list; String fileRegistry = "com.ibm.mqe.registry.MQeFileSession"; String privateRegistry = "com.ibm.mqe.registry.MQePrivateSession"; void open(String regName, String regDirectory, String regPIN) throws Exception { MQeFields regParams = new MQeFields(); // if regPIN == null, assume file registry String regType = (regPIN == null) ? fileRegistry : privateRegistry; regParams.putAscii(MQeRegistry.RegType, regType); regParams.putAscii(MQeRegistry.DirName, regDirectory); if (regPIN != null) regParams.putAscii(MQeRegistry.PIN, regPIN); list = new MQeListCertificates(regName, regParams); }
This constructor opens the registry. Once this has been done, the registry entries for the certificates can be retrieved. They can either be retrieved individually by name:
MQeFields entry = list.readEntry(certificateName);
or all the certificate entries in the registry can be retrieved together:
MQeFields entries = list.readAllEntries();
The value returned from readAllEntries() is a MQeFields object that contains a field for each certificate in the registry, the name of the field is the name of the certificate and the contents of the field is a MQeFields object containing the registry entry. You can process each registry entry using an enumeration:
Enumeration enum = entries.fields(); if (!enum.hasMoreElements()) System.out.println("no certificates found"); else { while (enum.hasMoreElements()) { // get the name of the certificate String entity = (String) enum.nextElement(); // get the certificate's registry entry MQeFields entry = entries.getFields(entity); // do something with it ... } }
The certificate can be obtained from the registry entry using the getWTLSCertificate() method:
Object certificate = list.getWTLSCertificate(entry);
Information can now be obtained from the certificate:
String subject = list.getSubject(certificate); String issuer = list.getIssuer(certificate); long notBefore = list.getNotBefore(certificate); long notAfter = list.getNotAfter(certificate);
The notBefore and notAfter times are the number of seconds since the midnight starting 1st January 1970, that is the standard UNIX format for dates and times.
Finally, the list object should be closed:
list.close();
The MQeListCertificates class is used in the example program, examples.certificates.ListWTLSCertificates, which is a command-line program that lists certificates.
The program has one compulsory and three optional parameters:
ListWTLSCertificates <regName>[<ini file>][<level>][<cert names>]
where:
This parameter is optional and if omitted the "brief" level of detail is used.
The MQe_Explorer configuration tool can also be used to examine certificates which belong to queue managers or queues.
To ensure continuity of service, we recommend that you renew certificates before they expire. Certificates are renewed using the same mini-certificate issuance service that originally issued them. Before requesting a renewal, the request must be authorized with the issuance service and a one-time-use certificate request PIN obtained, in just the same way as for the initial certificate issuance.
When a certificate is renewed, the new certificate contains the same public key as the old certificate. For additional security, you may wish to change credentials regularly. This involves generating a new private and public key, storing the new private key in the registry, and requesting a new certificate for the public key. If you use message level security with the MTrustAttribute, and change credentials, you will not be able to use the new credentials to read messages sent with the old credentials. The old credentials are not deleted, but are renamed within the registry so that they are still available.
The class com.ibm.mqe.registry.MQePrivateRegistryConfigure can be used both to renew certificates and to generate new credentials. To use the class, you must supply the name of the registry, an MQeFields object that contains the information required to open it, and optionally the registry's PIN.