Private registry service

Note:
The private registry service does not apply to the C codebase.

This section describes the private registry service provided by WebSphere MQ Everyplace.

Private registry and the concept of authenticatable entity

Queue-based security, that uses mini-certificate based mutual authentication and message-level security, that uses digital signature, have triggered the concept of authenticatable entity. In the case of mutual authentication it is normal to think about the authentication between two users but, messaging generally has no concept of users. The normal users of messaging services are applications and they handle the user concept.

WebSphere MQ Everyplace abstracts the concept of target of authentication from user to authenticatable entity. This does not exclude the possibility of authenticatable entities being people, but this would be application selected mapping.

Internally, WebSphere MQ Everyplace defines all queue managers that can either originate or be the target of mini-certificate dependent services as authenticatable entities. WebSphere MQ Everyplace also defines queues defined to use mini-certificate based authenticators as authenticatable entities. So queue managers that support these services can have one (the queue manager only), or a set (the queue manager and every queue that uses certificate based authenticator) of authenticatable entities.

WebSphere MQ Everyplace provides configurable options to enable queue managers and queues to auto-register as an authenticatable entity. WebSphere MQ Everyplace private registry service, MQePrivateRegistry provides services that enable a WebSphere MQ Everyplace application to auto-register authenticatable entities and manage the resulting credentials.

All application registered authenticatable entities can be used as the initiator or recipient of message-level services protected using MQeMTrustAttribute.

Private registry and authenticatable entity credentials

To be useful every authenticatable entity needs its own credentials. This provides two challenges, firstly how to execute registration to get the credentials, and secondly where to manage the credentials in a secure manner. WebSphere MQ Everyplace private registry services help to solve these two problems. These services can be used to trigger auto-registration of an authenticatable entity creating its credentials in a secure manner and they can also be used to provide a secure repository.

Private registry (a descendent of base registry) adds to base registry many of the qualities of a secure or cryptographic token. For example, it can be a secure repository for public objects (mini-certificates) and private objects (private keys). It provides a mechanism to limit access to the private objects to the authorized user. It provides support for services (for example digital signature, RSA decryption) in such a way that the private objects never leave the private registry. Also, by providing a common interface, it hides the underlying device support.

Auto-registration

WebSphere MQ Everyplace provides default services that support auto-registration. These services are automatically triggered when an authenticatable entity is configured; for example when a queue manager is started, or when a new queue is defined, or when an WebSphere MQ Everyplace application uses MQePrivateRegistry directly to create a new authenticatable entity. When registration is triggered, new credentials are created and stored in the authenticatable entity's private registry. Auto-registration steps include generating a new RSA key pair, protecting and saving the private key in the private registry; and packaging the public key in a new-certificate request to the default mini-certificate server. Assuming the mini-certificate server is configured and available, and the authenticatable entity has been pre-registered by the mini-certificate server (is authorized to have a certificate), the mini-certificate server returns the authenticatable entity's new mini-certificate, along with its own mini-certificate and these, together with the protected private key, are stored in the authenticatable entity's private registry as the entity's new credentials.

While auto-registration provides a simple mechanism to establish an authenticatable entity's credentials, in order to support message-level protection, the entity requires access to its own credentials (facilitating digital signature) and to the intended recipient's public key (mini-certificate).

Usage scenario

The primary purpose of WebSphere MQ Everyplace's private registry is to provide a private repository for WebSphere MQ Everyplace authenticatable entity credentials. An authenticatable entity's credentials consist of the entity's mini-certificate (encapsulating the entity's public key), and the entity's keyring protected private key.

Typical usage scenarios need to be considered in relation to other WebSphere MQ Everyplace security features:

Queue-based security with MQeWTLSCertAuthenticator
Whenever queue-based security is used, where a queue attribute is defined with MQeWTLSCertAuthenticator, mini-certificate based mutual authentication, the authenticatable entities involved are WebSphere MQ Everyplace owned. Any queue manager that is to be used to access messages in such a queue, any queue manager that owns such a queue and the queue itself are all authenticatable entities and need to have their own credentials. By using the correct configuration options and setting up and using an instance of WebSphere MQ Everyplace mini-certificate issuance service, auto-registration can be triggered when the queue managers and queues are created, creating new credentials and saving them in the entities' own private registries.
Message-level security with MQeMTrustAttribute
Whenever message-level security is used with MQeMTrustAttribute, the initiator and recipient of the MQeMTrustAttribute protected message are application owned authenticatable entities that must have their own credentials. In this case, the application must use the services of MQePrivateRegistry (and an instance of WebSphere MQ Everyplace mini-certificate issuance service ) to trigger auto-registration to create the entities' credentials and to save them in the entities' own private registries.

Secure feature choices

WebSphere MQ Everyplace does not provide support for any alternative secure repository for an authenticatable entity's credentials. If queue-based security with MQeWTLSCertAuthenticator or message-level security using MQeMTrustAttribute are used, private registry services must be used.

Usage guide

Prior to using queue-based security, WebSphere MQ Everyplace owned authenticatable entities must have credentials. This is achieved by completing the correct configuration so that auto-registration of queue managers is triggered. This requires the following steps:

  1. Setup and start an instance of WebSphere MQ Everyplace mini-certificate issuance service.
  2. Using MQe_MiniCertificateServer, add the name of the queue manager as a valid authenticatable entity, and the entity's one-time-use certificate request PIN.
  3. Configure MQePrivateClient1.ini and MQePrivateServer1.ini so that when queue managers are created using SimpleCreateQM, auto-registration is triggered. This section explains which keywords are required in the registry section of the ini files, and where to use the entity's one-time-use certificate request PIN.

Prior to using message-level security to protect messages using MQeMTrustAttribute, the application must use private registry services to ensure that the initiating and recipient entities have credentials. This requires the following steps:

  1. Setup and start an instance of WebSphere MQ Everyplace mini-certificate issuance service.
  2. Add the name of the application entity, and allocate the entity a one-time-use certificate request PIN.
  3. Use a program similar to the pseudo-code fragment below to trigger auto-registration of the application entity . This creates the entity's credentials and saves them in its private registry.
	/* SIMPLE MQePrivateRegistry FRAGMENT*/
    try 
       {
       /* setup PrivateRegistry parameters  */
       String EntityName   			= "Bruce";
       String EntityPIN          	= "11111111";
       Object KeyRingPassword     	= "It_is_a_secret";
       Object CertReqPIN          	= "12345678";
       Object CAIPAddrPort        	= "9.20.X.YYY:8082";
       /* instantiate and activate a 
				Private Registry. */
       MQePrivateRegistry preg  = new MQePrivateRegistry( );
       preg.activate( EntityName,        
			/* entity name                */
                      ".//MQeNode_PrivateRegistry", 
			/* directory root  */
                      EntityPIN,        
			/* private reg access PIN     */
                      KeyRingPassword,  
			/* private credential keyseed */
                      CertReqPIN,        
			/* on-time-use Cert Req PIN   */
                      CAIPAddrPort );    
			/* addr and port MiniCertSvr  */
       trace(">>> PrivateRegistry activated OK ..."); 
       }
    catch (Exception e)
       {
       e.printStackTrace( );
       }