[z/OS]

Using GSKit trace for problems related to certificates and keys when using AMS on z/OS

Use this topic to understand how to turn on and turn off IBM® Global Security Kit (GSKit) tracing when using AMS on z/OS®.

Introduction

In the *AMSD procedure for the AMS address space, and in sample job CSQ40CFG that runs program csq0util, there is an ENVARS DD card that can be used to set environment variables. A sample AMS environment variables file called CSQ40ENV is provided which includes details of how to turn on and turn off GSKit trace. Samples can be found in the IBM MQ hlq.SCSQPROC PDS library.

If you set GSK trace environment variables in the ENVARS DD card in the *AMSD procedure, variables are set from the point that the AMS address space is started (that is, as part of queue manager start-up if AMS has been configured). Variables either turn on, or turn off, tracing of all gsk_* calls issued by the AMS address space.

If you set GSK trace environment variables in the ENVARS DD card in a csq40cfg job, variables are set for the duration of the csq40cfg job. Variables either turn on, or turn off, tracing of all gsk_* calls issued during the processing of AMS commands, to define and display AMS policies for example.

Turning on GSKit trace

GSKit on the AMS address space

To turn on GSKit trace for the AMS address space, carry out the following procedure:
  1. Define a csq40env file with: 
    
GSK_TRACE_FILE=/u/<username>/AMStrace/gsktrace/gskssl.%.trc
GSK_TRACE=0xff
    on the ENVARS DD card in the *AMSD procedure for the AMS address space. For example:
    //ENVARS   DD DSN=USERID.JCL(CSQ40ENV),DISP=SHR
  2. Start your queue manager, channel initiator, and AMS address spaces.
    You see the environment variable settings in the job log for the AMS address space. For example:
    -4.09.18 STC13921  CSQ06091 !MQ07 CSQ0DSRV IBM MQ AMS for z/OS starting V9.2.3, level GA
-4.09.18 STC13921  CSQ06191 !MQ07 CSQ0DSRV AMSPROD=ADVANCEDVUE, recording product usage for MQ z/OS Adv VUE product id 5555AV9
-4.09.18 STC13921  CSQ06331 !MQ07 CSQ0DSRV AMS environment variables values:
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV _CEE_ENVFILE_S=DD:ENVVARS
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV _AMS_MSG_LEVEL=*.V
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV _AMS_MSG_FOLDING=NO
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV _AMS_INIT_THREADS=20
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV _AMS_MAX_THREADS=100
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV TZ=ESTESDT
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV GSK_TRACE_FILE=/u/<username>/AMStrace/gsktrace/gskssl.%.trc
-4.09.18 STC13921  CSQ06341 !MQ07 CSQ0DSRV GSK_TRACE=0xff
-4.09.21 STC13921  CSQ06531 !MQ07 CSQ0DLCL CRL checking disabled
-4.09.21 STC13921  CSQ06021 !MQ07 CSQ0DCNS AMS initialization complete

    The gsk_* calls issued by the AMS address space to protect or unprotect IBM MQ messages at put and get time respectively, are traced. A trace file is created when the AMS address space is started, to trace all gsk_* calls subsequently performed by the address space. The use of the % character in the name of the trace file ensures that trace files are named by Unix Systems Services (USS) process identifiers.

  3. Issue the following command to list the trace files produced:
    /u/<username>/AMStrace/gsktrace:>ls
    For example, you see files like: 
    gskssl.84017302.trc
  4. To format and view the trace file, issue the following command in USS: 
    /u/<username>/AMStrace/gsktrace:>gsktrace gskssl.84017302.trc
    which produces output similar to the following:
    07/01/2022-10:36:41 Thd-0 INFO gsk_svc_init(): System SSL Version 4, Release 4, Service level OA60573
07/01/2022-10:36:41 Thd-0 INFO gsk_svc_init(): LE runtime level 0x42040000, 31-bit addressing mode
07/01/2022-10:36:41 Thd-0 INFO gsk_svc_init(): STDOUT handle=-1, STDERR handle=-1, TRACE handle=0
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): Using variant character table for code set IBM-1047
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): Using local code page IBM-1047
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): Using ISO8859-1 for TELETEX string
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): 64-bit encryption enabled
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): 128-bit encryption enabled
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): 168-bit encryption enabled
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): 256-bit encryption enabled
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Crypto assist supports strong encryption
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): FIPS mode level 1101
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): SHA-1 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): SHA-224 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): SHA-256 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): SHA-384 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): SHA-512 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): DES crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): DES3 crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): AES 128-bit crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): AES 256-bit crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): AES-GCM crypto assist is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Cryptographic accelerator is not available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Cryptographic coprocessor is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Public key hardware support is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Max RSA key sizes in hardware - signature 4096, encryption 4096, verification 4096
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): Maximum RSA token size 3500
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): ECC clear key support is available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): ECC secure key support is available. Maximum key size 521
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): TKDS is available for the storage of persistent PKCS #11 objects
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): ICSF Secure key PKCS #11 support is not available
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): ICSF FIPS compatibility mode
07/01/2022-10:36:41 Thd-0 INFO crypto_init(): ICSF FMID is HCR77D1
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): Job name CSQ40CFG, Process 05020096
07/01/2022-10:36:41 Thd-0 INFO gsk_dll_init_once(): GSKSRVR communication area at 00000000
07/01/2022-10:36:41 Thd-0 ENTRY gsk_dn_to_name(): ---> DN: CN=USER,O=IBM,C=UK
07/01/2022-10:36:41 Thd-0 EXIT gsk_dn_to_name(): <--- Exit status 0x00000000 (0)
07/01/2022-10:36:46 Thd-0 ENTRY gsk_dn_to_name(): ---> DN: CN=USER1,O=IBM,C=UK
07/01/2022-10:36:46 Thd-0 EXIT gsk_dn_to_name(): <--- Exit status 0x00000000 (0)
07/01/2022-10:36:46 Thd-0 ENTRY gsk_dn_to_name(): ---> DN: CN=USER,O=IBM,C=UK
07/01/2022-10:36:46 Thd-0 EXIT gsk_dn_to_name(): <--- Exit status 0x00000000 (0)

GSKit for a csq40cfg job
To turn on GSKit trace for a csq40cfg job, set the ENVARS DD card as in the following example:
//CSQ40CFG JOB (ACCOUNT),'DEFAULT JOBCARD',CLASS=C,
//         MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//* Job to define and display an AMS policy on a queue. The policy
//* name is the same as the queue name.
//* Make sure column numbers are not included as otherwise they can
//* interfere with the data in SYSIN.
/*JOBPARM SYSAFF=MVnn
//CSQ40CFG EXEC PGM=CSQ0UTIL,
//         PARM='ENVAR("_CEE_ENVFILE_S=DD:ENVARS") /'
//STEPLIB  DD DSN=hlq.SCSQANLE,DISP=SHR
//         DD DSN=hlq.SCSQAUTH,DISP=SHR
//ENVARS   DD DSN=USERID.JCL(CSQ40ENV),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
setmqspl -m MQ01 -p BANK.RQ
         -r CN=USERID,O=IBM,C=UK -e AES256
dspmqspl -m MQ01 -p BANK.RQ
/*
The csq40cfg job does not give any indication of whether GSKit trace has been enabled or not. However, you can check if trace is enabled or not by looking at the settings in the environment variables file specified for the job, or by checking if a trace file was created for the process under which the csq40cfg job ran.

Turning off GSKit trace

GSKit on the AMS address space

To turn off GSKit trace for the AMS address space, carry out the following procedure:
  1. Stop the queue manager address space. This stops both the channel initiator and the AMS address spaces.
  2. Modify your csq40env file as follows:
    GSK_TRACE_FILE=/u/<username>/AMStrace/gsktrace/gskssl.%.trc
GSK_TRACE=0x00
  3. Restart your queue manager, channel initiator and AMS address spaces.
  4. Check the environment variable settings in the job log for the AMS address space to ensure that GSKit trace has been turned off.

GSKit for a csq40cfg job

To turn off GSKit trace for a csq40cfg job, carry out the following procedure:
  1. Modify your csq40env file as follows:
    GSK_TRACE_FILE=/u/<username>/AMStrace/gsktrace/gskssl.%.trc
GSK_TRACE=0x00
  2. Submit your csq40cfg job and check that no trace file is produced.
Notes:
  • In the environment files, coding GSK_TRACE=0xff turns trace on, and coding GSK_TRACE=0x00 turns trace off.
  • Include the % character in the trace file name to ensure that trace file names produced for different USS processes, that issue gsk_* calls, include the process identifier, and hence are kept separate.