Mini-certificate issuance service

The ES03 WebSphere MQ Everyplace SupportPac, "WebSphere MQ Everyplace WTLS Mini-Certificate Server" is available as a separate free download from http://www.ibm.com/software/ts/mqseries/txppacs/. WebSphere MQ Everyplace includes a default mini-certificate issuance service that can be configured to satisfy private registry auto-registration requests. With the tools provided, a solution can setup and manage a mini-certificate issuance service so that it issues mini-certificates to a carefully controlled set of entity names. These are a prerequisite for MQeMTrustAttribute-based message-level security. The characteristics of this issuance service are:

The tools provided in the ES03 SupportPac enable a mini-certificate issuance service administrator to authorize mini-certificate issuance to an entity by registering its entity name and registered address and defining a one-time-use certificate request PIN. This would normally be done after off line checking to validate the authenticity of the requestor. The certificate request PIN can be posted to the intended user, as bank card PINs are posted when a new card is issued. The user of the private registry (for example the WebSphere MQ Everyplace application or WebSphere MQ Everyplace queue manager) can then be configured to provide this certificate request PIN at startup time. When the private registry triggers auto-registration, the mini-certificate issuance service validates the resulting new certificate request , issues the new mini-certificate and then resets the registered certificate request PIN so it cannot be reused. All auto-registration of new mini-certificate requests is processed on a secure channel.

We recommend that you refer to the MQe_MiniCertificateServer documentation included in the ES03 SupportPac, "WebSphere MQ Everyplace WTLS Mini-Certificate Server", for more details of how to install and use the WTLS digital certificate issuance service for WebSphere MQ Everyplace.

Renewing mini-certificates

The certificates issued for an entity by the mini-certificate issuance service are valid for one year from the date of issue and it is advisable to renew them before they expire. Renewed certificates are obtained from the same mini-certificate issuance service. 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 you use the server to obtain the PIN for renewal, remember that you are updating the entity, not adding it.

When a certificate is issued for an entity, a copy of the mini-certificate server's own certificate is issued with it. This is needed to check the validity of other certificates. With versions of WebSphere MQ Everyplace earlier than 1.2, the certificate server's certificate could expire before the entity's certificate. If this happens you can renew the server's certificate by requesting a renewal of the entity's certificate; a new copy of the mini-certificate server's certificate will be returned along with the entity's certificate. From mini-certificate server Version 1.2, the mini-certificate server's certificate will expire later than the entity's certificate.

The class com.ibm.mqe.registry.MQePrivateRegistryConfigure contains a method renewCertificates() which can be used to request renewed certificates. This is used in the example program examples.certificates.RenewWTLSCertificates, which implements a command-line program that requests renewed certificates from the issuance service

The program has four compulsory parameters:

RenewWTLSCertificates <entity> <ini file> <MCS addr> <MCS Pin>

where:

entity
is the name of the entity for which a renewed certificate is required. This should be either a queue manager, a queue or other authenticatable entity. The name of a queue should be specified as <queue manager>+<queue>, for example myQM+myQueue.
ini file
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. For a queue, this typically the configuration file for the queue manager that owns the queue.
MCS addr
is the host name and port address of the mini-certificate server (for example: myServer:8085)
MCS Pin
is the one-time use PIN issued by the mini-certificate server administrator to authorize this renewal request.

Obtaining new credentials (private and public keys)

When you renew a certificate, you get an updated certificate for your existing public key. This allows you to continue to use your existing private and public key pair. If you want to change your private and public key pair, you must request new credentials. This includes a request to the mini-certificate issuance service for a new public certificate embodying the new public key. Before requesting a certificate for the new credentials, the request must be authorized with the issuance service and a one-time-use certificate request PIN must be obtained, in the same way as for the initial certificate issuance. (When you use the server to obtain the PIN for the new certificate, remember that you are updating the entity, not adding it.)

The class com.ibm.mqe.registry.MQePrivateRegistryConfigure contains a method getCredentials() which can be used to request new credentials. This is used in the example program examples.install.GetCredentials, which implements a GUI program that requests new credentials from the issuance service.

Note:
When new credentials are issued, the existing ones are archived in the registry. You will no longer be able to decrypt messages created using your earlier credentials. The new certificate will not validate a digital signature (used with MQeMTrustAttribute) created with your earlier credentials.

Listing mini-certificates

It can be useful to list the certificates in a registry, for example to check on their expiry dates. You can do this using methods in the class com.ibm.mqe.attributes.MQeListCertificates. These are used in the example program examples.certificates.ListWTLSCertificates, which implements a command-line program that lists certificates.

The program has one compulsory and three optional parameters:

ListWTLSCertificates <reg Name>[<ini file>] [<level>] [<cert names>]

where:

regName
is 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
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
is the level of detail for the listing. This can be:
-b or -brief
prints the names of the certificate, one name per line
-n or -normal
prints the names of the certificates, one per line, followed by their type (old or new format)
-f or -full
prints the names of the certificates, their type, and some of the contents
This parameter is optional and if omitted the "normal" level of detail is used.
cert names
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.

Updated mini-certificate format for WebSphere MQ Everyplace Version 2.0

The mini-certificates used by WebSphere MQ Everyplace are based on the WTLS certificates used by WAP. The certificates used by WebSphere MQ Everyplace Versions 1.0 and 1.1 were based on the latest draft of the WTLS specification that was available at the time of development. A standard for the certificates has since been approved. In WebSphere MQ Everyplace Version 2.0, updated mini-certificates that conform to the approved standard have been introduced.

You can upgrade your certificates to the new format by running the mini-certificate server from WebSphere MQ Everyplace Version 2.0 and renewing the certificates. The renewed certificates are in the new format.