SupportPac MS0C:

MQSeries Security Channel Exits using Entrust/PKI®

Author

Benjamin Y. Goldshlager
IBM
US Global Services
Banking Finance and Insurance
 
 
 

This document describes IBM MQSeries SupportPac MS0C: MQSeries Security Channel Exits using Entrust/PKI.  The channel exit is based on the Entrust® Public Key Infrastructure (PKI).
 

Acknowledgments

It is a great pleasure for me to acknowledge the assistance and contributions of the following individuals:
 

Change History

Date Version Description
21st May 1999 1.0 Initial Release
 

Overview

This section provides a general overview of the MQSeries channel exits and functions provided by this SupportPac.

This SupportPac provides MQSeries with security services between two adjacent queue managers across an untrusted network.

In general, security can be addressed at many different levels in the messaging environment.  These security levels are identified as the application, middleware, operating system, network, and link levels.  In most cases, system and network security requirements must be satisfied by features and services at multiple levels.  Besides improved coverage of system requirements, use of multiple layers may reduce vulnerability to single-point security weaknesses or failures.

The mechanism used by MQSeries to transfer messages between two adjacent queue managers, or between a client and a queue manager is called a channel.  The SupportPac provides security services at the middleware level; more specifically, it integrates with the MQSeries channels as channel exit programs. These channel exit programs are based on the well defined open standard security application interface (GSS-API).  The GSS-API services are provided by the EntrustSession toolkit, which runs in the Entrust/PKI environment. Entrust is a company that provides Certificates and Key management services. For more information about the company and its products, visit  http://www.entrust.com.

This SupportPac provides the following security services:

NOTES:
  1. The scope of the function is between MQSeries Queue Managers and excludes support for MQSeries Clients. The security exit should work to authenticate a client connection, although this has not been tested. Message exits do not exist for client channels.
  2. These exits are supported only on Micosoft Windows NT and Sun Solaris. The code may run on other operating systems, but these have not been tested.

What are channel exit programs?

Channel exit programs are called at defined places in the processing carried out by MCA programs, or more commonly referred to as the channels or movers.  In general, the purpose of these exits is to augment the channel processing, for example, provide security and auditing services.

Some of these user exit programs work in complementary pairs.  For example, if a user exit program is called by the sending MCA to encrypt the messages for transmission, the complementary process must be functioning at the receiving end to reverse the process.

What do the SupportPac channel exit programs do?

The SupportPac provides channel exit modules which can be used for the security exit and the message exit on MQSeries for Windows NT V5 or MQSeries for Sun Solaris V5. The exit can also be used at the send/receive exit point, but this is not recommended.  The exit programs utilize the Entrust public-key infrastructure (PKI) to provide security services and encryption facilities, including channel mutual-authentication, message integrity, and message privacy.

The SupportPac utilizes the Generic Security Services (GSS-API) provided in the EntrustSession Toolkit.  GSS-API is a well defined open standard security application interface based on RFC1508, RFC1509, and RFC2078.  This exit uses GSS-API version 2.0.  These Entrust-based exits follow the same basic design as the example channel exits supplied with the MQSeries product which use the GSS-API within a DCE framework (see amqsdsc0.c in the samples directory).  A pair of security exits is used to authenticate the queue managers at each end of an MQSeries channel as it starts. Once the channel has been established, then a message exit is used to sign or protect individual messages or data segments flowing across the channel. Much of the behavior of the exits can be easily configured.

The programs are supplied in source format.  Once the SupportPac libraries are built, they can be fully utilized in a  production environment.  These libraries can also be modified to suit specific local needs.

The module has two entry points:

Supported Channels

Although the SupportPac is written to handle all types of channels, only channels between two queue managers are currently supported.

These exits cannot be used directly with cluster channels introduced with MQSeries V5.1 because they check that the peer queue manager name matches a configuration parameter; support of cluster channels could be provided by modifications to the INI file handling.

Client channels are also not supported.

Pre-requisites

These exits are supported on Microsoft Windows NT and on Sun Solaris only.  They are provided as source code only, so an appropriate C/C++ compiler is needed to build the modules.  For Sun Solaris, the SPARCompiler V4.0 was used; on Microsoft Windows NT, Microsoft Visual C++ V5.0 and Visual C++ V6.0 were used.  The EntrustSession Toolkit V4.0 is needed for each platform on which the exits are to be run.  MQSeries V5.0 or V5.1 is also required.  While it may be possible to use these exits on AIX or HP-UX, this has not been tested and is not supported.

The SupportPac does not supply the Entrust code itself - you have to obtain that elsewhere. It is assumed that you also already have a knowledgeable Entrust administrator. There are additional, optional, Entrust products which you may have installed: the Entrust/Client for Unix and the Entrust/Entelligence product on Microsoft Windows NT. These are not required for operation of the channel exits.

It is also assumed that you have a knowledgeable MQSeries administrator who knows how to configure and test channel definitions.

How do the SupportPac channel exit programs work?

The following section describes how the channel exits are used to establish mutual authentication between two queue mangers, and to provide message integrity and message privacy.

Processing overview

On startup, the MCAs exchange a startup dialog to synchronize processing. Then they switch to a data exchange that includes
the security exits; these must end successfully for the startup phase to complete and to allow messages to be transferred.

The security check phase is a loop, as shown in figure below.


 Security exit loop figure

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.

During the security loop, the local queue manager authenticates itself to the adjacent queue manager and in response the adjacent queue manager will authenticate itself to the local queue manager.  This is referred to as the mutual authentication security protocol.

It should be noted, however, that although the sender MCA on the local system requests the channel session, it is the partner MCA in the adjacent system that initiates the security session (gss_init_sec_context) by creating a security context.  Once the security context (token) is created, the receiver MCA on the adjacent system sends the security token to the sender MCA on the local system.  When the sender MCA receives the security token it uses it as an input to create a modified version of the token by using the accept (gss_accept_sec_context) function, and sends it back to the receiver MCA.  The receiver MCA then completes the mutual authentication by initiating the received token for a 2nd time (another call to gss_init_sec_context).  If the operation is successful, the receiver is assured it is communicating with the intended queue manager on the local system.

This flow can be repeated, if required by the underlying GSS mechanism being selected.  For example, the above sequence occurs when the selected token mechanism is spkm-2, however, if spkm-1 is selected, there will be 2 gss_init_sec_context calls and 2 gss_accept_sec_context calls used to complete the mutual authentication sequence.

The following is a high level depiction of the mutual authentication channel exit protocol.


 


 

Once the security context is successfully established between the two queue managers, then digital signatures and optionally data encryption (see Encryption Parameter) can then be applied to each message by the message exits.

The following figure is a high level depiction of the protocol for signing and encryption of messages in the message channel exits.

Message Exit - Pseudocode
 

The SupportPac code

There should be no need to change anything in the source code to get a working system.  Although a number of options can be set up in the header file (see mqsecche.h) all of these options can be overridden by changes to an ini file.  The code was derived from the DCE GSS-API samples provided with MQSeries V5 and it was originally intented that the same source could be used with both Entrust and DCE by setting an appropriate compile-time #define flag; however these exits were tested and will be supported only with the GSS_ENTRUST_API clauses enabled (see the Makefiles).

As well as the C code, an example INI file is provided for each operating system.  The documentation with the EntrustSession Toolkit contains information about the GSS-API and Entrust-specific function calls contained within the code.

Source Files

Makefile.NT Makefile used in building mqsecce.dll and mqseccem.dll
Makefile.Sun Makefile used in building mqsecces.so 
mqsecche.c Channel exit main entry routines source file
mqsecche.h Channel exit main entry routines header file
mqsecrtn.c Channel exit gss-api wrappers source file
mqsecrtn.h Channel exit gss-api wrappers header file
mqsecutl.c Channel exit general utilities source file
mqsecutl.h Channel exit general utilities header file
mqseccem.mc Channel exit EventLog message definition source file (NT only)

Sample Configuration Files

mqsecche.nt.ini ini file for Microsoft Windows NT
mqsecche.sun.ini ini file for Sun Solaris

Output Microsoft Windows NT Files

This section lists the libraries that are generated following the build.
 
mqsecce.dll MQSeries security channel exit dynamic load library
mqseccem.dll MQSeries security channel exit EventLog message format dynamic load library
mqseccem.reg Registry update information
mqsc.nt MQSC script to alter MQSeries channel definitions

Output Sun Solaris Files

This section lists the library that are generated following the build.
 
libmqsecces.so MQSeries security channel exit shared library
mqsc.sun MQSC script to alter MQSeries channel definitions

Implementation

To implement the SupportPac environment the following steps must be performed:
  1. Build and install the MQSecCE library
  2. For Microsoft Windows NT, install EventLog registry entries; for Sun Solaris, configure syslog
  3. Setup the Entrust environment
  4. Setup the exit's configuration files
  5. Define/Alter the channels
  6. Verify configuration

Building the MQSecCE library

Makefiles are supplied for both Sun Solaris and Microsoft Windows NT.  Edit the Makefile for your operating system to ensure that the location of both input and generated files and libraries are correctly defined.  The Makefiles also produce an MQSC script based on queue manager names which are set in the Makefile.  You should not need to change any of the compiler options, except perhaps to add a "-D DEBUG" if you want to generate additional debugging information when running the channel exits.

The Entrust libraries need to be somewhere that can be searched at runtime. On Sun Solaris, this is automatically setup by use of the LD_RUN_PATH environment variable within the Makefile.

Microsoft Windows NT

Run the following command in a DOS prompt:
nmake -f Makefile.NT clean all

Sun Solaris

Run the following command in a UNIX shell:
make -f Makefile.Sun clean all
The build process will create a shared libary (on Sun Solaris) or two DLLs (on Microsoft Windows NT).  It also creates a sample MQSC script (mqsc.sun or mqsc.nt), and copies files into the target directory specified in the Makefile. For Microsoft Windows NT, an additional file (mqseccem.reg) is created to assist in updating the registry. For the build process to successfully copy these files, you must have write access into the appropriate target directory. For example, you may need to be the mqm user on Sun Solaris.

Configuring the Event Log or syslog facility

The SupportPac is designed to integrate with any system management product that is able to monitor the native system log.  Monitoring these logs is usually achieved by configuring the system management alert agents to perform predefined actions based on given MQSecCE warning and/or error events that occur during the channel session.  These predefined actions can cause alerts to be sent to the main operator console, as well as, send text messages to support personnel pagers.

On Microsoft Windows NT, the MQSecCE messages/events are logged into the NT's Application EventLog under the source of MQSeries Security Channel Exit..

On Sun Solaris, messages are logged in the standard UNIX syslog.

Microsoft Windows NT - Event Log

As part of the build process, two files are created which assist in linking MQSecCE with the Microsoft Windows NT Event Log service. .A DLL (mqseccem.dll) contains information about error messages; a second file (mqseccem.reg) contains the registry entries needed to tell the Event Log service about these messages.

To register the DLL with the Event Log, use the regedit command. One of the items under the Registry menu item is 'Import Registry File'. From this item, select the generated mqseccem.reg file and merge it with the current registry. This creates entries in the

My computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\
tree.  The registry should now look like the picture below. The updated registry is automatically saved when you exit the regedit application.

Sun Solaris - syslog

Information is sent to the syslog daemon using the LOG_AUTH syslog facility, which is designed to be used by all security subsystems on Sun Solaris.  The syslog daemon can be configured to route MQSecCE messages to a specific log file by manipulating the /etc/syslog.conf file. Refer to the man pages for more information on how to configure the syslog.conf file.

Setup the Entrust Environment

For each queue manager in the network, an Entrust "user" has to be configured.  This is normally a two-stage process.  First define the user, and secondly create the Entrust User Profile (.epf) file.  Full information on how this is done is outside the scope of these instructions; refer to your Entrust documentation.

When defining the user, the Entrust Admin tool requires both a "first name" and a "surname" which will be part of the Distinguished Name.  Other fields such as email and serial number are not needed here.  You should use some naming convention for the queue manager DN - one suggestion is that the "first name" should always be set to MQSeries and the surname is the queue manager name.  The example INI file shipped with this SupportPac follows this scheme. Remember that the DN field is case-sensitive.

Once the user has been defined, then the epf file needs to be created.  The full method for doing this is described in Entrust manuals, and involves use of either the Entrust/Entelligence program (on Microsoft Windows NT) or the Entrust/Client program (on Sun Solaris).  This is where the password for the user id is set up.  You will need the password at a later stage of configuration and the epf file is also used later.

Configure MQSecCE INI file

There are several initialization and configuration files that need to be set up to enable these exits to work.  The principal file, the MQSecCE INI file,  is that named in the Exit Data fields of the channel definition.  This file contains information about the local queue manager, the peer queue manager which is going to be authenticated, and control information pointing at other files and saying how the session is going to be protected.

The TARGET_NAME field contains the MQSeries Queue Manager name which is at the other end of the channel; the TARGET_DN_NAME holds the Distinguished Name that was created within Entrust that corresponds to that Queue Manager.  The DN is case-sensitive and space-sensitive, and must match the remote Queue Manager DN for the session to be established.  Because the INI file contains the name of the partner Queue Manager, a different INI file is required for each channel communicating to a different Queue Manager, even if the rest of the attributes are the same.  A potential enhancement would be to allow wildcards within the matching process or to allow multiple targets to be defined in the INI file; this could assist with support for cluster channels.

The rest of the attributes are self-explanatory, with examples of the syntax contained within the example INI file.  If you take the default values, the only fields which you must alter are the TARGET_NAME, TARGET_DN_NAME and the KEYTAB_FILE.

The administrator is not precluded from using the same ini file with multiple channels between two queue managers.  It is, however, recommended that each channel be defined with its own ini file.  This gives the administrator better control of parameters that apply to a particular channel.  You may want, for example, to have different debug logfiles so logic flow can be easily traced on the channel, or set encryption on messages taking one route but not the other.  Furthermore, one ini file can be defined for the security exit and another for the message exit.  The administrator can use this to specify that only the message exit is to be traced, for example.

MQSecCE INI File Parameters

Parameters suffixed with '*' are required parameters, although some may have default values, these values must be valid.  For example, there must be a keytab file in the c:\winnt\profiles\mqm directory if the default valued of KEYTAB_FILE is used.

ENTRUST_EPF_FILE*

Entrust's User Profile File.
Example:
ENTRUST_EPF_FILE=d:\Local\Entrust\Profiles\THIS.QMGR.epf

TARGET_NAME*

Authorized target Queue Manager Name. Specifies the name of the partner Queue Manager that this Queue Manager channel will communicate with.
Example:
TARGET_NAME = THAT.QMGR

TARGET_DN_NAME*

The following field specifies the Distinguished Name (DN) used by the TARGET_NAME Queue Manager.  The value of the DN is case and space sensitive.  Leading blanks before DN are ignored.
Example:
TARGET_DN_NAME=cn=MQSeries CSQ1

Note that the 'cn=' is part of the DN

KEYTAB_FILE*

Keytab file name - File used to hold the secret key of this Queue Manager.

$$$$$ WARNING $$$$$$
$$$$$ WARNING $$$$$$
$$$$$ WARNING $$$$$$

This file MUST be accessible ONLY by this Queue Manager's id.  On Microsoft Windows NT, it is strongly recommended that the keytab file is located in NTFS and be accessed by user 'mqm'.  On Sun Solaris, it is also strongly recommended that the file has only 'r/w' permission for user 'mqm'.  The Microsoft Windows NT keytab file name defaults to 'c:\winnt\profiles\mqm\keytab', and the UNIX keytab file name defaults to '/u/mqm/.keytab'.

Example:
KEYTAB_FILE=c:\winnt\profiles\mqm\keytab

ENTRUST_INI_FILE*

Entrust's INI file.  Default to 'c:\winnt\entrust.ini'.
Example:
ENTRUST_INI_FILE=c:\Program Files\Entrust\entrust.ini

DEBUG_FILE

Debug output file - defaults to the LOG_FILE. Microsoft Windows NT log file name defaults to "c:\temp\mqsecche.log". Sun Solaris log file name defaults to "/tmp/mqsecche.log".
This parameter applies to both the SECURITY and the MESSAGE exits.
Example:
DEBUG_FILE=d:\local\dll\this.log

DEBUG_OPTIONS

Debug options.
  • NONE        - No debug message (default)
  • CONSOLE - Direct debug messages to console
  • FILE            - Direct debug messages to file (see DEBUG_FILE value)
    • FILE and CONSOLE options can both be selected.  Use comma as an option delimiter.

    This parameter applies to both the SECURITY and the MESSAGE exits.

    Example:
    DEBUG_OPTIONS=CONSOLE, FILE

    DEBUG_MAX_APP_DATA

    Debug maximum application data display.  Use this option to specify the maximum length of the application data to display during the debug session.  This option applies exclusively to the send/receive/message exits

    Default debug application message length is 20 bytes.  Valid values are 0-1000000 (min = 0 bytes, max = 1 million bytes).

    Example:
    DEBUG_MAX_APP_DATA=25

    SECURITY_MECHANISM

    Context Security mechanism.  Default to gss_mech_spkm2, which implements SPKM-2.  Use gss_mech_spkm1 for the SPKM-1 mechanism.  This parameter applies to the receiver side of the channel.

    Example:

    SECURITY_MECHANISM=gss_mech_spkm2

    SYMMETRIC_KEY_EXCHANGE_PROTOCOL

    Symmetric Key exchange protocol used.  Only applicable for Entrust.  The following are valid values:

    Example:

    SYMMETRIC_KEY_EXCHANGE_PROTOCOL = SPKM_KEY_ESTB_PROTOCOL_RSA

    SECURITY_CONTEXT_LIFE_TIME

    The desired lifetime (in seconds) that the security context is to remain valid. The default value is taken from the DefaultContext_time_req entry in the Entrust initialization file.   Unless modified by the administrator this default is set at 3600 seconds (1 hr).

    This parameter is set by the RECEIVER channel exit only, which dictates the context lifetime between itself and the SEND channel exit side.  The SEND channel can not decide the lifetime of the security context.
     

    Example:

    SECURITY_CONTEXT_LIFE_TIME=0

    ENCRYPTION

    Specifies whether message privacy is performed. The default is no message encryption is to be performed. The exit must be defined to the channel via the MQ ALTER CHANNEL command.  If the exit is defined and this flag is set to N, only the signature will be be applied to the messages.  Signature is always applied by this message exit.

    This parameter applies to the MESSAGE exit only.

    Example:

    ENCRYPTION=Y

    Other Configuration Files

    These configuration files are all pointed at from within the MQSecCE ini file. Remember that on Sun Solaris and Microsoft Windows NT the end-of-line marker is different - you will need to ensure you are using an editor which understands the convention for the operating system. On Sun Solaris, the dos2unix and unix2dos commands can be used to convert between the two formats.

    The keytab file

    The MQSecCE INI file points at a keytab file. This file contains a single line, the password associated with the queue manager. Because the password is stored in this file in cleartext, it must be protected with appropriate operating system privileges. Only the userid running the channel program (the mqm userid) needs read access to this file; all other permissions should be removed.

    The Entrust INI file

    The entrust.ini file is also needed. It should have been installed on your machine when Entrust was configured; it shows how to get to the Entrust directories and server programs. Distribution of this file may also be part of your site's procedure when allocating new userids along with the EPF file.

    The EPF file

    The Entrust User Profile contains details of the user and associated keys. How the file is created is beyond the scope of this document, but once created it needs to be placed somewhere that the channel program can read  it.  On Sun Solaris, the file must also have write permissions for the mqm userid (there appears to be no good reason for this, but without such access the Entrust processing fails).  From the EPF file, a set of related files are automatically created by Entrust when the authentication procedures take place.

    MQSeries Channel Setup

    This section describes the commands to define the channel exits to MQSeries.  Use the DEFINE CHANNEL command if the channel has not been previously defined, otherwise, use the ALTER CHANNEL command.  Refer to the MQSeries Command References SC33-1369 for more details.

    Define the channels between two queue managers in the normal way, without any exits specified.  It is a good idea to try to PING  the channels in both directions before introducing the security component just to check that the definitions and communications path are fully operational.

    Once the channels are defined, then you can alter the definition to include the Entrust exits.

    On all channels you will need to set the Security Exit module to point at the compiled module and, unless you are using the hardcoded default, the Security Exit Data field to point at the ini file (see below).  You can also choose whether to use Message exits or Send/Receive exits for protecting the user data flows between machines.  It is recommended that you use Message Exits because using Send/Receive exits may not work with larger messages (eg 32K).  When compiling the exits, an MQSC script was also created.  This script contains ALTER CHANNEL commands needed to enable the channels to use the security exits.  The script is based on a common configuration with the names of sender and receiver channels the same as the two queue managers.  If you are using different channel types or have a different naming convention then use the script as an example for your own ALTER CHANNEL commands; if you use the same naming convention then you can pass the script directly into the runmqsc command.

    runmqsc < mqsc.sun
    Assuming queue managers called 'met' and 'klein', the following script is generated for the 'met' queue manager:
    alter chl('met') +
        chltype(rcvr) +
        scyexit('/var/mqm/exits/libmqsecces.so(GSS_SEC_SCY_CHANNELEXIT)') +
        scydata('/var/mqm/exits/met.ini') +
        msgexit('/var/mqm/exits/libmqsecces.so(GSS_SEC_SRM_CHANNELEXIT)') +
        msgdata('/var/mqm/exits/met.ini')

    alter chl('klein') +
        chltype(sdr) +
        scyexit('/var/mqm/exits/libmqsecces.so(GSS_SEC_SCY_CHANNELEXIT)') +
        scydata('/var/mqm/exits/met.ini') +
        msgexit('/var/mqm/exits/libmqsecces.so(GSS_SEC_SRM_CHANNELEXIT)') +
        msgdata('/var/mqm/exits/met.ini')

    The channel attributes which are set by this script are the SecurityExit, SecurityData, MessageExit and MessageData values.  The exits are named as entrypoints in  the newly-compiled library; the data fields point at an INI file.  For each pair of connected queue managers, the same exit code is used but a different INI file will be required.  The contents of the INI file were described in the previous section.

    Note:  The SCYDATA and MSGDATA parameter maximum length is restricted to 32 characters. The administrator needs to ensure that the length of the ini file specification does not exceed this restriction.

    Installation Verification

    As suggested earlier, the first stage should be to check that the PING CHANNEL command works without the Entrust exits invoked.  If that fails, then normal MQSeries diagnostic techniques need to be used.

    Next, once all of the code has been built, the configuration done and the INI files modified, it's time to test the system with the exits.  Start by simply trying to ping the channels in each direction (use the PING CHANNEL command in runmqsc).  If the console debug option is specified (it is in the sample ini files) then the tracing will be displayed on the console during initialization and termination of the channel ping sequence.  You should see the exit get loaded and lots of data flying by as it calls Entrust.  While it may take some time, 30-60 seconds was not uncommon, eventually the PING CHANNEL command should give "AMQ8020: Ping MQSeries channel complete."  This tests the security exit but does not test the message exit.  If the PING CHANNEL fails, then move onto the Problem Determination phase.

    To test the message exit, define a remote queue with a target on the partner queue manager.  Put a message to the queue and watch it appear on the other side of the channel.  If this works, then you are all set.

    Problem Determination

    When configuring the exits for the first time, make sure that the DEBUG_OPTIONS entry in the INI file is set to write both to CONSOLE and to FILE.  Then, the PING CHANNEL command will cause messages to be written to the screen and also logged to a file.  On the remote queue manager, these messages will also be written to a file.  If the PING command fails, then there should be useful information to determine what has gone wrong.  You may also wish to use the "-D DEBUG" flag when compiling the module for additional debug information..

    Typical errors include not being able to find one of the INI or other configuration files, not being able to open the EPF file in read/write mode on Sun Solaris and not respecting the case-sensitive nature of the Distinguished Name fields. Check that the configuration files have the correct format for end-of-line markers on each operating system.

    Once in production, then turn off the DEBUG_OPTIONS in the INI file (this only takes effect after the channel exit is next initialized).  Informational and warning messages will continue to be written to an operating system log.  On Sun Solaris, this is written to syslog as a LOG_AUTH event; on Microsoft Windows NT it is written to the Application Event log.

    Microsoft Windows NT Event Log Entries

    There are three possible types of events/messages that the SupportPac produces (see table below).  Besides event specifics, messages also contain common information fields, such as, hostname, queue manager name, channel name, date, and time.   In addition, error and warning messages contain the source file, source file line number, and routine where the message was originally issued.
     
    Event/Message Prefix Description Channel Session Affect
    MQSECCE (I) Information message No affect
    MQSECCE (W) Warning message  Channel session is continued
    MQSECCE (E) Error message Channel session will be terminated.
    Informational messages containing startup and shutdown of the channel exit are always logged.  Any errors/warnings from either Entrust, native operating systems, and MQSeries are passed as character strings and/or integer return codes in the MQSecCE's message (see Event Samples).  Consult appropriate manuals for more information on how to resolve these errors.

    Event Examples

    An example of startup and shutdown informational events as reported by the SupportPac on Micosoft Windows NT:


     
     

    An example of GSS-API warning event as reported by the SupportPac on Microsoft Windows NT:

    Glossary

    Authentication

    Authentication proves that a resource or user is what or who it claims to be.  Solid authentication defends a system against the security risk of impersonation, in which a sender or receiver uses a false identity to access a system.  Traditionally, systems have used passwords and user names for authentication; digital certificates provide a more secure method of authentication.  Mutual authentication requires both the source and the target to authenticate themselves to one another before a secured session can be started between them.

    Certificate Authority

    A Certificate Authority (CA) is a trusted party that creates and issues digital certificates to users and systems.  The trust in the CA is the foundation of trust in the certificate as a valid credential. A CA uses its private key to create a "digital signature" on a certificate that it issues to validate the certificate's origin.

    Several businesses provide commercial Certificate Authority services for Internet users.  However, organizations can use Digital Certificate Manager to create their own Certificate Authority to issue digital certificates to systems and users within an intranet.

    Digital Certificate

    A certificate is a digitally signed statement from one entity (person, company, etc.), saying that the public key of some other entity has some particular value. If you trust the signature on the certificate, you trust that the association in the certificate between the specified public key, and that the other entity is authentic.

    Digital Signature

    A digital signature is a string of bits that is computed from some message data (the data being "signed") and the private key of an entity. The signature can be used to verify that the data came from the entity and was not modified in transit.  Like a handwritten signature, a digital signature has many useful characteristics:

    Distinguished Name (DN)

    A distinguished name is the name of the person or server to whom a Certificate Authority (CA) issues a digital certificate.  The certificate provides this name to indicate certificate ownership.  Depending on the policy of the CA that issues a certificate, the distinguished name can include other information.  The distinguished name includes this information:

    Entrust Profile File (EPF)

    Entrust PKI uses this file to store the user's encryption key pair and signing key pair (in an encrypted form).  This is in addition to other Entrust information specific to that user.   The Entrust administrator must first authorize new users before they can acquire this file.  Once authorized, users can utilize either the Entrust/Client or the Entrust/Entelligence products to create the Entrust Profile File.

    Entrust INI File

    This file contains run-time initialization parameters that are used by Entrust products such as the Entrust/Client and EntrustSession toolkit libraries.  It should have been installed on the system when Entrust was configured; it contains information needed to access Entrust directories and server programs.  Distribution of this file may also be part of the local site's procedure when allocating new userids and the EPF files.

    Encryption

    Encryption is the process of taking data (called clear text) and a cryptographic key and producing ciphertext, which is data meaningless to anybody who does not know the key.

    GSS-API

    The Generic Security Service Application Programming Interface (GSS-API) defined in two Internet Requests For Comments (RFCs). RFC 1508 and RFC 2078, Generic Security Service Application Program Interface, defines an API that provides security services.  The definition of the API is not tied to any particular programming language or mechanism by which security is achieved; it simply defines the protocol and the functions needed to realize the protocol in an application.  A C implementation of the GSS-API is defined in RFC 1509, “Generic Security Service: C-bindings”.

    Keytab

    This file contains a single line, the password associated with the queue manager that allows the security channel exit to retrieve its user certificate, including access to its private key.  Because the password is stored in this file in cleartext, it must be protected with appropriate operating system privileges. Only the userid running the channel program (the mqm userid) needs read access to this file; all other permissions should be removed.

    Message channel agents

    A message channel agent (MCA) is a program that controls the sending and receiving of messages.  There is one message channel agent at each end of a channel. One MCA takes messages from the transmission queue and puts them on the communication link. The other MCA receives messages and delivers them to the remote queue manager.

    A message channel agent is called a caller MCA if it initiated the communication or, otherwise, is called a responder MCA.  A caller MCA may be associated with a sender, server (fully qualified), or requester channel.  A responder MCA, may be associated with any type of message channel.

    Message Integrity

    Verification that no modifications were made to the message data while in-transit  In the context of the channel exit, it means that the receiving queue manager is assured that the message received from the sending queue manager has not been tampered.  It is important to note that modification to the message is not prevented by the security exit, but rather that the receiving queue manager will detect if the message was tampered with while in-transit.

    Message Privacy

    See encryption.

    Message Signature

    See digital signature.

    Private Key

    A private key is a number that is supposed to be known only to a particular entity.  That is, private keys are always meant to be kept secret. They can be used to generate digital signatures.  A private key is always associated with a single public key.

    Public Key

    A public key is a number associated with a particular entity (for example, an individual or an organization).  A public key is intended to be known to everyone who needs to have trusted interactions with that entity.  A public key is always associated with a single private key, and can be used to verify digital signatures generated using that private key.

    Public Key Infrastructure (PKI)

    Public Key Infrastructure is a technology grouping based on Digital Certificate use and management.  Basic functions are Signing and Encryption.  PKI consists of the following components:

    Security Context

    The exchange of protected messages takes place within a security context.  A security context is established by the communicating parties at the beginning of a secure communications session and discarded at the end of the session.  One can think of a security context as the information shared by the participants in a secure communications session that accomplishes these tasks:

    Simple Protocol Key Management (SPKM)

    SPKM is the mechanism by which the GSS-API is implemented.  This mechanism provides authentication, key establishment, data integrity, and data confidentiality in an on-line distributed application environment using a public-key infrastructure.  The protocol is defined in RFC 2025.  The SPKM offers two types of protocols, spkm-1 and spkm-2.

    SPKM-1

    SPKM-1 uses random numbers for replay detection during context establishment in "Two-way Authentication", when performing unilateral authentication of the target to the initiator and uses "Three-way Authentication", when mutual authentication is requested by the initiator.

    SPKM-2

    SPKM-2 uses timestamps for replay detection during context establishment in "One-way Authentication", when performing unilateral authentication of the initiator to the target and uses "Two-way Authentication", when mutual authentication is requested by the initiator.

    The use of timestamps by this mechanism requires both machines to have their system clocks synchronized within 3 minutes.

    Symmetric Key exchange protocol

    When confidentiality of the communications session is required, the initiator and the target must share a symmetric key.  SPKM supports two ways of sharing a symmetric key during the establishment of a security context:

    TRADEMARKS

    IBM and MQSeries are trademarks of International Business Machines Corporation in the United States and/or other countries.

    Entrust is a registered trademark of Entrust Technologies Limited in Canada. All Entrust product names are trademarks of Entrust Technologies Limited.

    Windows NT is a trademark of Microsoft Corporation in the United States and/or other countries.

    Other company, product and service names may be trademarks or service marks of others.