Channel security exit programs

We can use security exit programs to verify that the partner at the other end of a channel is genuine. This is known as authentication. To specify that a channel must use a security exit, specify the exit name in the SCYEXIT field of the channel definition.

Note: Authentication can also be achieved with channel authentication records. Channel authentication records provide great flexibility in preventing access to queue managers from certain users and channels, and in mapping remote users to IBM MQ user identifiers. TLS support is also provided by IBM MQ to authenticate your users and to provide encryption and data integrity checks for your data. For more information about TLS, see TLS security protocols in IBM MQ. However, if you still require more sophisticated (or different) forms of security processing, and other types of checks and security context establishment, consider writing security exits. For security exits written prior to IBM WebSphere MQ Version 7.1 it is worth noting that earlier versions of IBM MQ queried the underlying secure sockets provider (e.g. GSKit) to determine the remote partner's certificate Subject Distinguished Name (SSLPEER) and Issuer Distinguished Name (SSLCERTI). In IBM WebSphere MQ Version 7.1 support was added for a range of new security attributes. In order to access these attributes IBM WebSphere MQ Version 7.1 obtains the DER encoding of the certificate and uses it to determine the Subject and Issuer DN. The Subject and Issuer DN attributes appear in the following channel status attributes:

  • SSLPEER (PCF selector MQCACH_SSL_SHORT_PEER_NAME)
  • SSLCERTI (PCF selector MQCACH_SSL_CERT_ISSUER_NAME)
These values are returned by channel status commands as well as the data passed to channel security exits listed, as shown:

  • MQCD SSLPeerNamePtr
  • MQCXP SSLRemCertIssNamePtr
In IBM WebSphere MQ Version 7.1, a SERIALNUMBER attribute is also included in the Subject DN and contains the serial number for the remote partner's certificate. Also some DN attributes are returned in a different sequence from previous releases. Consequently the composition of the SSLPEER and SSLCERTI fields are altered in Version 7.1 from previous releases and it is therefore recommended that any security exits or applications dependant on these fields be examined and updated.

Existing IBM MQ peer name filters specified via the SSLPEER field of a channel definition are not affected and continue to operate in the same manner as in earlier releases. This is because the IBM MQ peer name matching algorithm has been updated to process existing SSLPEER filters without any need to alter the channel definitions. This change is most likely to affect security exits and applications which depend upon the Subject DN and Issuer DN values returned by the PCF programming interface.

A security exit can be written in C or Java™.

Channel security exit programs are called at the following places in the processing cycle of an MCA:

  • At MCA initiation and termination.
  • Immediately after the initial data negotiation is finished on channel startup. The receiver or server end of the channel can initiate a security message exchange with the remote end by providing a message to be delivered to the security exit at the remote end. It might also decline to do so. The exit program is started again to process any security message received from the remote end.
  • Immediately after the initial data negotiation is finished on channel startup. The sender or requester end of the channel processes a security message received from the remote end, or initiates a security exchange when the remote end cannot. The exit program is started again to process all subsequent security messages that might be received.

A requester channel never gets called with MQXR_INIT_SEC. The channel notifies the server that it has a security exit program, and the server then has the opportunity to initiate a security exit. If it does not have one, it informs the requester and a zero length flow is returned to the exit program.

Note: Avoid sending zero-length security messages. Examples of the data exchanged by security-exit programs are illustrated in figures Figure 1 through Figure 4. These examples show the sequence of events that occur involving the security exit of the receiver, and the security exit of the sender. Successive rows in the figures represent the passage of time. In some cases, the events at the receiver and sender are not correlated, and therefore can occur at the same time or at different times. In other cases, an event at one exit program results in a complementary event occurring later at the other exit program. For example, in Figure 1:
  1. The receiver and sender are each invoked with MQXR_INIT, but these invocations are not correlated and can therefore occur at the same time or at different times.
  2. The receiver is next invoked with MQXR_INIT_SEC, but returns MQXCC_OK which requires no complementary event at the sender exit.
  3. The sender is next invoked with MQXR_INIT_SEC. This is not correlated with the invocation of the receiver with MQXR_INIT_SEC. The sender returns MQXCC_SEND_SEC_MSG, which causes a complementary event at the receiver exit.
  4. The receiver is then invoked with MQXR_SEC_MSG, and returns MQXCC_SEND_SEC_MSG, which causes a complementary event at the sender exit.
  5. The sender is then invoked with MQXR_SEC_MSG, and returns MQXCC_OK which requires no complementary event at the receiver exit.
Figure 1. Sender-initiated exchange with agreement

Figure 2. Sender-initiated exchange with no agreement

Figure 3. Receiver-initiated exchange with agreement

Figure 4. Receiver-initiated exchange with no agreement

The channel security exit program is passed an agent buffer containing the security data, excluding any transmission headers, generated by the security exit. This data can be any suitable data so that either end of the channel is able to perform security validation.

The security exit program at both the sending and receiving end of the message channel can return either of two response codes to any call:

  • Security exchange ended with no errors
  • Suppress the channel and close down
Note:
  1. The channel security exits typically work in pairs. When you define the appropriate channels, make sure that compatible exit programs are named for both ends of the channel.
  2. In IBM i , security exit programs that have been compiled with Use adopted authority (USEADPAUT=*YES) can adopt QMQM or QMQMADM authority. Take care that the exit does not use this feature to pose a security risk to your system.
  3. On a TLS channel on which the other end of the channel provides a certificate, the security exit receives the Distinguished Name of the subject of this certificate in the MQCD field accessed by SSLPeerNamePtr and the Distinguished Name of the issuer in the MQCXP field accessed by SSLRemCertIssNamePtr. Uses to which this name can be put are:

    • To restrict access over the TLS channel.
    • To change MQCD.MCAUserIdentifier based on the name.