WebSphere MQ for AIX, HP-UX, Linux, Solaris, and Windows, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp supply channel-exit programs for the security exit, the message exit, and the send and receive exits. The WebSphere MQ client for Windows 95 supplies channel-exit programs for the security exit and the send and receive exits. These programs take advantage of the Distributed Computing Environment (DCE) security services and encryption facilities. Before using the supplied exit programs from a WebSphere MQ client for Windows 95, see the note under How to use the DCE channel-exit programs.
The programs are supplied in source and object format. You can use the objects as they stand, or can use the source as the basis for creating your own user-exit programs. You should bear in mind that whereas the objects are supplied as working programs, the source code does not include any provision for tracing or error handling. If you chose to modify and use the source code, you should add your own tracing and error-handling routines.
You cannot use the supplied channel-exit programmes on a queue manager that also has SSL parameters set. This applies to queue managers on AIX, HP-UX, and Solaris.
The object has two entry points:
The supplied channel-exit programs address the Distributed Computing Environment (DCE) considerations for security in the areas of data encryption, and of authentication of a partner system when establishing a session. For a particular channel, each exit program has an associated DCE principal (similar to a user ID). A connection between two exit programs is an association between the two principals.
A secure connection between two security exit programs, one for the sending MCA and one for the receiving MCA, is established after the underlying session has been established. The sequence of operations is as follows:
At this stage, if both applications are satisfied with the authenticity of the partner's token, then the secure (authenticated) connection is established.
DCE Security provides an API to 'seal' and 'unseal' data and hence to selectively protect specified elements of a datastream. The supplied message, send, and receive exits encrypt and decrypt messages using these DCE Security API calls.
Figure 148. Security exit flows
The encryption algorithm used by the send exit must match the decryption algorithm used by the receive exit. The supplied send, receive, and message exits use the gss_seal() and gss_unseal() calls to encrypt and decrypt data. The qop_req parameter on the gss_seal() call is set to GSS_C_QOP_DEFAULT. The encryption provided by DCE depends on the DCE product installed.
The send, receive, and message exits are all used for encryption. The difference is that the message exit encrypts only the content of the message, whereas the send and receive exits also encrypt the message headers. Therefore, the message exit offers slightly better performance but at the expense of unencrypted header data.
The supplied code implements a security exit and message, send, and receive exits. Note that the message exit does not encrypt the WebSphere MQ header. The security exit provides mutual (two-way) authentication. The message, send, and receive exits provide encryption facilities based on a key managed by the security context set up by the security exit. Therefore, the message, send, and receive exits will not work unless the security exit has been called previously.
The code interfaces to DCE through the DCE GSS API provided as part of OSF DCE 1.1. This API provides a superset of the standard GSS API calls as specified in Internet RFCs 1508 and 1509. Some DCE-specific GSS calls have been added to the API by OSF.
The principal of a WebSphere MQ system that has a queue manager is the queue manager name.
A WebSphere MQ client does not have a queue manager. The principal used for a client is as follows:
It is important that queue manager names or user IDs that are to be used as DCE principals are syntactically acceptable to DCE; see your DCE documentation for information about valid DCE principal names. If the name is to be used only within the local cell directory, the only mismatch between the allowable characters in a queue manager name and the allowable characters in a principal name is that a principal name cannot contain a '/'. If there is any likelihood that the name will also need to be reflected in a global directory, you are recommended to restrict principal names to alphanumeric characters. As with any DCE principal, when you create it you must define it to the DCE security server and must also put an entry for it in the relevant keytable file. Therefore, when you delete a queue manager that is also a DCE principal you must remember to delete both its entries.
Remote queue manager names are transferred across a channel at channel initialization. When the security exit is called, if the remote WebSphere MQ system is not a client, the remote queue manager name (which is also the remote principal) is passed to the security exit in the WebSphere MQ MQCXP parameter list. The initiator exit uses the name provided. If the channel is being established between a WebSphere MQ client and a WebSphere MQ server, the client always initiates the first security flow. In all cases, the initiator exit's remote principal name is a queue manager name.
The flows shown in Figure 148 occur to establish the security context. As a part of these flows the initiator's principal is transferred to the acceptor.
It is possible to establish multiple security contexts between the same pair of principals, and hence to allow parallel channels to use the security exit.
You can set up restricted channels. The system administrator supplies a value in the Channel Security Exit User Data when defining this end of the channel. The presence of this value causes the security exit to check the remote principal name. If this check shows a mismatch the channel is not established. Note that the remote principals (queue manager names and default DCE principals) may be longer than the 32 characters allowed in the Channel Security Exit User Data. Only the first 32 characters of the remote principal are considered significant.
If the MCA forms part of a WebSphere MQ server system connected to a client, the security exchange will have caused the client principal to flow to the server. If the value is valid with regard to the optional restricted-channel check and the MCAUserIdentifier variable is not already defined, the client principal is copied into the server's MCAUserIdentifier variable. Note that client principals may be longer than the 12-character MCAUserIdentifier. Only the first 12 characters of such a remote principal are copied.
Thus the first 12 characters of the WebSphere MQ client's DCE principal name can become the user identifier to be used by the server's MCA for authorization for that client to access WebSphere MQ resources. The server system must be set up appropriately to allow this to work.
Do not run the supplied DCE message exit in combination with the supplied DCE send and receive exits on the same channel.
To use the supplied channel-exit programs you need to install DCE and define some channels. For installation information, see the Quick Beginnings book for your platform:
The supplied channel-exit programs are intended for use between systems operating within a single DCE cell. The setup of a DCE cell is described in the documentation provided with the DCE packages for the platforms incorporated in the cell. The exit programs operate the same way whether they are running on a system with a DCE security client installed or with a DCE security server installed.
Once the DCE cell has been configured, it is necessary to define the principals that the exit is going to use to DCE. DCE setup samples are provided on all the supported platforms. The samples are primarily intended for setting up DCE for the DCE Names installable component. They also contain comments indicating how they can be modified to set up the DCE security principals instead of, or as well as, the Names principal.
Each DCE security principal has its own keytable. On UNIX systems that support DCE security, the keytable is a file within the directory /var/mqm/dce/keytabs. On OS/2 and Windows it is a file within the directory \MQM\DCE\KEYTABS, where MQM is the name of your work path.
When the supplied channel-exit programs are called for a particular principal, they look in a keytable file that has the same name as the principal itself. Therefore, the keytable file for a particular principal must have the same name as that principal.
The use of separate keytables for each principal is recommended in the OSF DCE literature. On systems that support file access controls (UNIX systems and Windows) keytable access should be limited to:
In the case of queue manager WebSphere MQ systems, the processes that interface to the security exits at the sending end of the channel are runmqchl (and runmqchi on OS/2 and Windows NT). amqcrsta, amqcrs6a or runmqlsr interface to the security exits at the receiving end of the channel. On most systems these all run under the mqm user ID; in this case, non-supervisor/administrator access to the keytables relating to queue manager principals should be restricted to read access for the mqm user ID.
On client systems the user ID under which the security exit is called is the user ID under which the client application runs (often the login user ID of the user of the client system). Again, non-supervisor/administrator access to the relevant keytable should be restricted to read access by that user ID only.
The supplied exit code is in two formats: object and source.
The object is called amqrdsc0 on UNIX systems and amqrdsc0.DLL on OS/2, and Windows. It is installed as a standard part of the WebSphere MQ product for your platform and is loaded as a standard user exit. If you wish to run the supplied security channel exit to make use of authentication services then in your definition of the channel, specify:
SCYEXIT('<path>amqrdsc0(DCE_SEC_SCY_CHANNELEXIT)')
If you also wish to use the message exit to support data encryption, then in your definition of the channel, specify:
MSGEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')
Or you can use the send and receive exits to support data encryption by specifying the following in your definition of the channel:
SENDEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')
RCVEXIT('<path>amqrdsc0(DCE_SEC_SRM_CHANNELEXIT)')
<path> is the path to the directory containing the exit.
See topic "WebSphere MQ for z/OS without CICS" through topic "MQSeries for Compaq NonStop Kernel" for information about how to call user exits on the platform you are using.
The exit source file is called amqsdsc0.c. It can be found in <mqmtop>/samp on UNIX systems and in <bootdrive>:\mqm\tools\c\samples on OS/2, and Windows. If you choose to modify the source versions, rather than running the objects as they stand, you will need to recompile the modified source. It is compiled and linked in the same way as any other channel exit for the platform concerned, except that DCE headers need to be accessed at compile time, and the DCE libraries, together with any recommended associated libraries, need to be accessed at link time. Refer to the documentation for the DCE product for the platform you are using, to find out about the DCE and associated libraries.
icc /DIBMOS2 /DINTEL80x86 /Fe amqsdsc0.dll /I \ c:\mqclient\tools\c\include /I \ c:\ibmcppw\include /I c:\opt\dcelocal\include\dce \ /W3 /Sa /Ge- /Gm+ amqsdsc0.c amqsdsc0.def dceos2.lib
Using the following definition file:
LIBRARY AMQSDSC0 PROTMODE DESCRIPTION 'DCE Security Exit' CODE SHARED LOADONCALL DATA NONSHARED MULTIPLE HEAPSIZE 4096 STACKSIZE 8192 EXPORTS DCE_SEC_SCY_CHANNELEXIT DCE_SEC_SRM_CHANNELEXIT
cc -I/opt/dce/share/include/dce \ -I/opt/mqm/inc -KPIC -c amqsdsc0.c
followed by:
ld -G -L/opt/dce/share/usr/lib -ldce amqsdsc0.o -o srm
cc -D_HPUX_SOURCE -Dhpux -DICOL -D_REENTRANT \ -Dsigaction=cma_sigaction +ESlit +DA1.0 -c +z \ amqsdsc0.c -I /opt/mqm/include -I /opt/dce/include/dce \ -Aa && ld -o amqsdsc0 amqsdsc0.o -z +b : -b +I MQStart \ -ldce -lmqm_r -lndbm -lM -lc_r
c:\msdevstd\bin\cl /DAMQ_PC /VERBOSE /LD /MT \ /Ic:\msdevstd\include /ID:\MQCLIENT\TOOLS\C\INCLUDE \ /IC:\OPT\DIGITAL\DCE\INCLUDE\DCE amqsdsc0.c \ -link /DLL /EXPORT:DCE_SEC_SCY_CHANNELEXIT \ /EXPORT:DCE_SEC_SRM_CHANNELEXIT /STACK:8192 libdce.lib \ advapi32.lib libcmt.lib
xlC_r -c /usr/mqm/samp/amqsdsc0.c -I/usr/include/dce ld -e MQStart -bnoquiet -o amqsdsc0 amqsdsc0.o \ -L/usr/lib/dce -T512 -H512 -ldce -bE:amqsdsc0.exp \ -lpthreads -lc_r -liconv -ls
On WebSphere MQ for Windows, the exit dll name must be amqrdsc0.dll or amqsdsc0.dll.