Certificate management

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.

Examining certificates

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:

MQeRegistry.LocalRegType (ascii)
For a public registry, set this parameter to com.ibm.mqe.registry.MQeFileSession. For a private registry, set it to com.ibm.mqe.registry.MQePrivateSession.

MQeRegistry.DirName (ascii)
The name of the directory holding the registry files.

MQeRegistry.PIN(ascii)
The PIN protecting the registry. This is only required for private registries.

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:

regName
The name of the registry whose certificates are to be listed. It can be a private registry belonging to a queue manager, a queue or another entity. It can be a public registry, or, for the administrator, it can be the mini-certificate server's registry. If you want to list the certificates in a queue's registry, you must specify its name as <queue manager>+<queue>, for example myQM+myQueue. If you want to list the certificates in a public registry, it must have the name MQeNode_PublicRegistry. It will not work for a public registry with any other name. The name of the mini-certificate server's registry is MiniCertificateServer .

ini file
This is the name of a configuration file that contains a section for the registry. This is typically the same configuration file that is used for the queue manager or mini-certificate server. For a queue, this is typically the configuration file for the queue manager that owns the queue. This parameter should be specified for all registries except public registries, for which it can be omitted.

level
The level of detail for the listing. This can be:

This parameter is optional and if omitted the "brief" level of detail is used.

cert names
This is a list of names of the certificates to be listed. It starts with the flag "-cn" followed by names of the certificates, for example -cn ExampleQM putQM .If this parameter is used, only the named certificates are listed. If this parameter is omitted, all the certificates in the registry are listed.

The MQe_Explorer configuration tool can also be used to examine certificates which belong to queue managers or queues.

Renewing certificates

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.



© IBM Corporation 2002. All Rights Reserved