MFW97003 Fix for MQSecure V300 GA CD.

Problem Description(s):
   
Build 04027 fixes:
------------------
Note: when installed, the "build string" in mqs_adm will display as follows:
SecSrv: 04027d  SecApi: 04027d  MQS_ADM Version 300 (04027d)

and the "build string" in the channel exit log will display as follows:
SecSrv: 04027d  SecExit: 04027d  MqsExit: 04027d 

1-11269705  PROBLEM_DESC: mqs_admc -s -r without an initialized database asks
                twice for the same information.
1-12303204  PROBLEM_DESC: No sample program for the Java API is provided.
1-16880307  PROBLEM_DESC: User program abends when using the Direct API call 
                MQS_Analyze() instead of MQS_AnalyzeMultiple() or 
                MQS_AnalyzeAll() on a message that was encrypted for multiple
                destinations via a wildcard in the destination id.
1-37264401  PROBLEM_DESC: Refresh Public Keys from LDAP crashes mqs_admc.
1-40825011  PROBLEM_DESC: User program calling Direct API for encryption 
                crashes.


Previous fixes:
---------------

Build 03258 fixes:
------------------

1-20721901  PROBLEM_DESC: Improved dbsrv diagnostics.
1-21422408  PROBLEM_DESC: Misleading msg "Invalid Userid (userid not found)" 
                when codepage conversion fails.
1-10430801  PROBLEM_DESC: mqs_adm -s creates an empty MQSS.USR file.
1-11269701  PROBLEM_DESC: mqs_adm -p creates an empty MQSS.USR file.
1-12247111  PROBLEM_DESC: mqs_adm -i -r refreshed key modulus size not correct.
1-6581T     PROBLEM_DESC: Export to LDAP fails when trying to export userids 
                previously exported but not present on LDAP.
N/A         PROBLEM_DESC: OCSP cache support.


Build 03078 fixes:
------------------

1-4XMWP     PROBLEM_DESC: 300 record limit in user key database.
1-19188905	PROBLEM_DESC: Support for multiple threads through single channel
    		    exit instance.
1-22478201	PROBLEM_DESC: MQSecure Java channels for MQSeries base classes for
                Java (MA88 support)
n/a         PROBLEM_DESC: HMAC signing performance improvement.
1-25966101	PROBLEM_DESC: Messages received in channel with msgexit/rcvexit
                fail when qmgr connected to both a qmgr from a platform with a 
                different CCSID and a qmgr with the same CCSID.

Release Level:
MFV300G1/MFV300M1

Corequisite Fixes:
None

Users Affected:

All users of MQSecure Version 300 with Windows 98.

Resolution:

Install this fix.

Operating System Versions that Fix Applies To:

Windows 98 (W9)

Modules Replaced:
_Date/Time______                _Size_ ___Module_______
bin:
02/02/2004  06:22p              32,768 DBDOWN.exe
02/02/2004  06:22p              77,824 DBSRV.exe
02/02/2004  06:22p             655,360 Kmfconv.exe
02/02/2004  06:22p              49,152 Mqdirecc.exe
02/02/2004  06:23p             749,568 Mqs_admc.exe
02/02/2004  06:23p              36,864 Mqs_opc.exe

dll:
02/02/2004  06:22p              45,056 MQSSAMP.dll
02/02/2004  06:22p              53,248 MQS_APIC.dll
02/02/2004  06:23p              32,768 mqs_japi.dll
02/02/2004  06:22p              53,248 SEC_API.dll
02/02/2004  06:22p              36,864 SEC_EXIT.dll
02/02/2004  06:22p           1,019,904 SEC_SRV.dll

exitlib:
02/02/2004  06:22p              94,208 mqsexitc.dll

java\lib\com\candle\mqsecure:
02/02/2004  06:23p               4,169 MQSecure.class
02/02/2004  06:23p                 512 MQSecureEnvironment.class

lib:
02/02/2004  06:22p               2,694 MQSSAMP.lib
02/02/2004  06:22p               2,946 MQS_APIC.lib
02/02/2004  06:22p               7,362 SEC_API.lib

samp:
05/12/2003  02:29p              54,632 MQDIRECT.C
04/15/2002  06:52p               8,751 MQDirect.java
06/02/2003  05:13p              25,058 MQS_DEFS.H
05/12/2003  02:30p              33,898 MQS_OP.C
03/03/2003  09:50a              12,929 SEC_API.H

Creation Date:

2 February, 2004

Installation Steps:
Note: In the following steps, &mqsdir = the directory where MQSecure was 
installed.

1. Make backup copies of all of the files listed above under the heading 
"Modules Replaced".

2. Stop any MQSecure applications, including MQSeries channels that are using
the MQSecure channel exits.

3. From a DOS prompt, enter the command "dbdown".

4. Copy the file MFW97003.EXE to the MQSecure directory.

5. Execute MFW97003 to explode the fix package and recreate the underlying 
directory structure.  Ensure the "Unzip to folder:" specifies the MQSecure 
directory (&mqsdir).

6. Copy Mqsexitc.dll from &mqsdir\EXITLIB to your ExitsDefaultPath directory.

7. If you wish to use the new features introduced by this FixPak, perform 
configuration described in the section at the end of this readme.

8. Restart channels stopped in step 2.


Fix Removal Steps:

1. Stop any MQSecure applications, including MQSeries channels that are using 
the MQSecure channel exits.

2. From a DOS prompt, enter the command "dbdown".

3. Copy the backup copies of the files listed above under the heading "Modules
Replaced" into the appropriate MQSecure directories.

4. Copy Mqsexitc.dll from &mqsdir\EXITLIB to your ExitsDefaultPath directory 
for all appropriate queue managers.

5. Undo any configuration changes made for new features.

6. Restart channels stopped in step 1.



New feature documentation:

Hash-based Message Authentication Code (HMAC)
==========================================

Introduction
==========

PathWAI Secure for Websphere MQ currently performs authentication of
messages based on RSA Encryption and Decryption of a SHA-1 (or MD5)
hash of the message payload.  This technique relies on comparatively
expensive CPU consumption inherent in asymmetric key cryptography.

Another approach to authentication involves the generation of a Message
Authentication Code, or MAC. By combining symmetric key cryptographic
techniques and SHA-1 hashing, a strong authentication scheme can be
implemented known as HMAC, or Hash-based Message Authentication Code.
The advantage of using this scheme over asymmetrically encrypted SHA-1
or MD5 hashes is better performance due to the relatively low resource
consumption required by the symmetrickey cryptography when the secret
key used as input to the HMAC process is reused. 

Implementing the support in PathWAI Secure uses an extension to the message
authentication specification environmental variable, channel exit command
codes, and API parameters, all or any of which may be utilized. Performance 
benefits are achieved through an initial communication of a 20 to 64 byte secret key, 
required as part of HMAC processing through an RSA Private key encrypted
message  between communicating platforms.  After the initial communication,
the secret key is reused to avoid expensive asymmetric cryptographic
operations i.e. the private key encryption of the SHA-1or MD5  hash and
corresponding decryption with the public key.


External Modifications
===================

Two areas of the product externals are affected:

1.  MQSECURE_SIGNING_ALGORITHM is an environmental variable used to
     specify the algorithm used for message authentication. 

     To force HMAC authentication for ALL PathWAI Secure MQ applications
     within the scope of the environmental variable it must be set as follows:

     MQSECURE_SIGNING_ALGORITHM=HMACSHA1

     The variable setting indicates that the HMAC generated for a message is 
     itself a SHA-1 hash.

2.  Individual channels can be set up to perform HMAC message authentication 
     through two new command codes specified in the channel exit definition 
     keyword parameters MSGDATA, SENDDATA, and RCVDATA or the equivalents
     using the Websphere for MQSeries console:

     Hnnnnn - H indicates that HMAC authentication is to be used for all messages 
                       sent through the channel. 
	    nnnnn is an integer specifying the number of times the secret key 
                       used in developing the HMAC representing a message is to be 
                       reused i.e. how  many messages will be sent through the channel
                       before a new secret key is generated

     Innnnn  - I indicates that a new HMAC secret key is to be generated after the 
                      number of seconds specified by nnnnn

    Examples showing specification on both sides of channel:
    =================================================

  	Sender: 			All messages passing through the
	MSGDATA(H10000)		channel will use HMAC authentication
 	Receiver:			and the secret key will be used 10,000
	MSGDATA(H)		times before generating of a new one.

	Sender: 			All messages passing through the
	SENDATA(HI1800)		channel will use HMAC authentication
 	Receiver:			and the secret key will be used for 
	RCVDATA(H)		1,800 seconds, or 30 minutes before
				generating a new one.

	Sender:			All messages passing through the
	MSGDATA(H5000I3600)	channel will use HMAC authentication
 	Receiver:			and the secret key will be used 5,000 
	MSGDATA(H)		times, or for 3,600 seconds before
				generating a new one.

				In this example, a new secret key will 
				be generated when the first of either
				of the regeneration specifications is
				satisfied.  At that point, both the number
				of reuses and the time of reuse will be
				set to their initial values.

	As with the existing authentication and encryption command codes, A and E,
 	on channel operations, note that the receiving channel specification command
 	code H must be specified in the MSGDATA and/or RCVDATA  keyword parameters
	if H is specified on the sending side, and in the same command code sequence if
	combined with E and/or A .  

	Specification of the H command code in the channel xxxDATA() keyword
 	parameters will override the specification in the MQSECURE_SIGNING_ALGORITHM
 	environmental variable setting i.e. a specification of RSA private key encrypted MD5
	hashes for authentication purposes will be overriden by HMAC authentication if the
	H command code is specified on channel exits.  This also applies to application-level
	use of HMAC authentication as shown in the following section.


Specification of HMAC authentication at the application level
===================================================

PathWAI Secure MQ provides APIs to apply End To End message security.  HMAC authentication 
can be specified for messages at the application level through setting HMAC secret key reuse 
values in the MQS_APICONTEXT structure.

The definition of the MQS_API structure follows:

typedef struct MQS_api_context                                       
  {                                                                 
   long     version;                                                
   long     debug;                                                   
   long     nKeyReusesMax;                                          
   long     KeyGenerationInterval;                                  
   long     nHMACKeyReusesMax;                                      
   long     HMACKeyGenerationInterval;                               
  } MQS_APICONTEXT, *PMQS_APICONTEXT;                               


Applications issue either the MQS_CreateAPIContext() or the S_MQCreateAPIContext() PathWAI
Secure MQ API call and pass an initialized MQS_APICONTEXT.  The following code shows
how HMAC authentication can be specified in an application.  Note that the example also
illustrates how symmetric key encryption may also be specified through this mechanism to
be used in conjunction with HMAC secret key reuse:


	#include <sec_api.h>
	
	#define NUM_ENCRYPTION_KEY_REUSES	500	
	#define ENCRYPTION_KEY_REUSE_INTERVAL	300  	
	#define NUM_HMAC_KEY_REUSES		10000	
	#define HMAC_KEY_REUSE_INTERVAL		1200  	


	MQS_APICONTEXT		apiContext={ 0, 0, 0, 0, 0, 0 };
	int			rCode=0;

	// Establish structure version for future compatibility 
	apiContext.version=MQS_APICONTEXT_VERSION_1;

	// Set symmetric encryption key reuse to 500 times and interval
	// for reuse to 5 minutes (300 seconds)
	apiContext.nKeyReusesMax=  NUM_ENCRYPTION_KEY_REUSES;
	apiContext. KeyGenerationInterval= ENCRYPTION_KEY_REUSE_INTERVAL;

	// Set HMAC secret key reuse to 10,000 times and interval
	// for reuse to 20 minutes (1200 seconds
	apiContext. nHMACKeyReusesMax= NUM_HMAC_KEY_REUSES;
	apiContext. HMACKeyGenerationInterval= HMAC_KEY_REUSE_INTERVAL;

	rCode=MQS_CreateAPIContext( &apiContext );


Using the Integrated API, all of the set up code would be the same except for the actual creation of the API context which would be as follows:

	#include <mqs_api.h>
	
	rCode=S_MQCreateAPIContext( &apiContext );