Security exits on a client connection

You can use security exit programs to verify that the partner at the other end of a channel is genuine. Special considerations apply when a security exit is applied to a client connection.

Figure 1 illustrates the use of security exits in a client connection, using the IBM® MQ object authority manager to authenticate a user.

Either the SecurityParmsPtr or SecurityParmsOffset field in the MQCNO structure is set by the client and there are security exits at both ends of the channel. After the normal security message exchange ends, and the channel is ready to run, the MQCSP structure is passed to the client security exit. The exit can access the MQCSP structure by using the SecurityParms field in the MQCXP structure. The exit type is set to MQXR_SEC_PARMS. The security exit can alter the credentials in the MQCSP structure, or leave them unchanged.

The data that is returned from the exit is then sent to the server-connection end of the channel. The MQCSP structure is rebuilt on the server-connection end of the channel and is passed to the server-connection security exit. The exit can access the MQCSP structure by using the SecurityParms field in the MQCXP structure. The security exit receives and processes this data. This processing is typically to reverse any change that is made to the credentials in the MQCSP structure by the client exit, which are then used to authorize the queue manager connection. The resulting MQCSP structure is referenced by using SecurityParmsPtr in the MQCNO structure on the queue manager system.

The memory address that is returned with the SecurityParms field of the MQCXP structure must remain addressable and unchanged until MQXR_TERM. An exit must not invalidate or free the memory back to the system before the exit is called for MQXR_TERM.

If the SecurityParmsPtr or SecurityParmsOffset field in the MQCNO structure is set, and there is a security exit at only one end of the channel, the security exit receives and processes the MQCSP structure. Actions such as encryption are inappropriate for a single user exit, as there is no exit to perform the complementary action.

If the SecurityParmsPtr and SecurityParmsOffset fields in the MQCNO structure are not set, and there is a security exit at either or both ends of the channel, the security exit or exits are called. Either security exit can return its own MQCSP structure that is addressed by the SecurityParmsPtr field. The security exit is not called again until it is terminated (ExitReason of MQXR_TERM). The exit writer can free the memory that is used for the MQCSP at that stage.

When a server-connection channel instance is sharing more than one conversation, the pattern of calls to the security exit is restricted on the second and subsequent conversations.

For the first conversation, the pattern is the same as if the channel instance is not sharing conversations. For the second and subsequent conversations, the security exit is never called with MQXR_INIT, MQXR_INIT_SEC, or MQXR_SEC_MSG. It is called with MQXR_SEC_PARMS.

In a channel instance with sharing conversations, MQXR_TERM is called only for the last conversation running.

Each conversation has the opportunity in the MQXR_SEC_PARMS invocation of the exit to alter the MQCD; on the server-connection end of the channel this feature can be useful to vary, for example, the MCAUserIdentifier or LongMCAUserIdPtr values before the connection is made to the queue manager.