ALERT: Some images may not load properly within the Knowledge Base Article. If you see a broken image, please right-click and select 'Open image in a new tab'. We apologize for this inconvenience.

IBM JES2 spool encryption (ADVANCED_FORMAT=ENABLED) may affect CA Dispatch 11.6 and 11.7

book

Article ID: 237662

calendar_today

Updated On:

Products

Dispatch Output Mgmt

Issue/Introduction

The CA Dispatch / CADZSAPn SAPI tasks may receive the following error:

CADD331E SAPx RPI1 allocation error (rc=144,err=0478,info=0000)

You may also see a $HASP1198 message in the CADZSAPn started task log similar to the following:

$HASP1198 CADZSAPn  Decryption failure                              
                    DSNAME=JSLID02.JS140TST.JOB06898.D0000109.?                
                    DDNAME=SYSUT2                                            
                    RET=00000008 RSN=00003E84 -- User is not authorized to key label 

This technical document describes how to handle JES2 spool encryption with the CA Dispatch 11.6 and 11.7 product.

Cause

IBM added a new JES2 spool encryption feature to z/OS 2.4, which allows encryption of datasets in the JES2 spool.

This functionality is delivered via IBM PTFs, which need to be applied to the system.

 

Check Whether There is JES2 Spool Encryption Support Installed

To verify whether support for JES2 spool encryption has been installed, check whether these IBM PTFs for the following APARs were applied:

  • OA58757
  • OA58699
  • OA58718
  • OA57466

Note: The most current information is available on the IBM website.

 

Determine the Current Status of JES2 Spool Encryption

The current status of JES2 spool encryption on the running system can be checked by using the following JES2 command:

$D SPOOLDEF

If JES2 spool encryption is active on the system, it is indicated in the command output as follows:

ADVANCED_FORMAT=ENABLED

If JES2 spool encryption is installed but not active on the system, it is indicated as follows:

ADVANCED_FORMAT=DISABLED

Note: If JES2 spool encryption is not installed on the system, the line with the ADVANCED_FORMAT value will not be produced in the command output.

 

JES2 Spool Encryption and Encryption Keys

With the JES2 spool encryption feature active, datasets in the JES2 spool can be encrypted using encryption keys. A specific dataset is encrypted using a single key and different datasets in the JES2 spool can be encrypted with different keys. Alternatively, a single key can be used to encrypt multiple datasets, or to encrypt all datasets in the JES2 spool. As not every dataset has to be encrypted, there may be both encrypted and unencrypted datasets in the JES2 spool.

- In order to decrypt and read an encrypted dataset, the user or task needs to have READ access to the encryption key that was used to encrypt the dataset.

- If this access is not provided, any attempt to allocate the dataset fails with a dynamic allocation 0478 error code (reason 0000).

Environment

CA Dispatch 11.6 and 11.7
z/OS 2.4
z/OS 2.5
JES2
ADVANCED_FORMAT=ENABLED
ENCRYPTION

Resolution

JES2 Spool Encryption and CA Dispatch

The CA Dispatch CADZSAPn SAPI task(s) must have READ access to all the encryption keys used to encrypt the datasets on the JES Spool. If READ access is not provided, the following problems will occur:

  1. The CA Dispatch CADZSAPn SAPI task(s) will be unable to collect the encrypted JES spool datasets for which READ access to the key is not granted.

  2. When the CA Dispatch CADZSAPn SAPI task(s) encounter an encrypted dataset for which they do not have access to the encryption key, the task will issue CADD331 an $HASP1198 messages and bypass the dataset (marking the dataset non-selectable to the SAPI task). The task will remain active and continue on to process any further selectable JES2 spool datasets (encrypted or unencrypted) from the JES Spool.

Identification and Resolution of CA Dispatch / CADZSAPn JES Spool Dataset Access Problems Due to Inaccessibility of the Encryption Keys

The CA Dispatch / CADZSAPn SAPI tasks can be checked to see if any problems were encountered while collecting the JES spool datasets, due to inaccessible encryption keys. Look for these error messages indicating a 0478 error code for dynamic allocation:
 
   CADD331E SAPY RPI1 allocation error (rc=144,err=0478,info=0000)

The JES Spool encryption key access problems are also indicated by IBM JES2 $HASP1198 message being produced in the started task log. The example below shows CA Dispatch / CADZSAPY SAPI task encountering a problem while decrypting a JES2 spool dataset, as it was not authorized to read the encryption key:
 
$HASP1198 CADZSAPY  Decryption failure                              
                    DSNAME=JSLID02.JS140TST.JOB06898.D0000109.?                
                    DDNAME=SYSUT2                                            
                    RET=00000008 RSN=00003E84 -- User is not authorized to key label  

Finally, the inaccessibility of the spool encryption keys is also indicated by the security subsystems. CA Top Secret and IBM RACF both generate messages in the started task log, stating that the task does not have the authority to read the required encryption keys. For CA ACF2, no message is produced, but ACFRPTRV report can be used to determine whether the requests from CA Dispatch / CADZSAPn SAPI tasks to read the encryption keys are being denied. 

 

When using CA Top Secret security, the following is an example of the error message produced:

   TSS7250W 136 J=CADZSAPn A=DISPATC TYPE=CSFKEYS RESOURCE=CSFKEY2
   TSS7251W Access Denied to CSFKEYS <CSFKEY2>

 

When using IBM RACF security, the following are examples of the error messages produced:

   ICH408I USER(CADZSAPn) GROUP(SYSSTC ) NAME(####################) CSFKEY2     +
     CL(CSFKEYS ) INSUFFICIENT ACCESS AUTHORITY ACCESS INTENT(READ ) ACCESS + 
     ALLOWED(NONE )

 

In case of using CA ACF2 security, this is the sample ACFRPTRV report indicating the request from CADZSAPY to read the QAJES.64BYTE.ICSFKEY.LABEL key was denied:

  CA ACF2 - ACFRPTRV - GENERALIZED RESOURCE LOG -                 PAGE    1      
  DATE 05/03/21 (21.123) TIME 19.27 ACFRPTRV REPORT ON VIO AND LOGS              
                                                                               
  REQUESTED RESOURCE                               REC  LOOKUP KEY                
  UID                      SOURCE   CPU  MODULE   DISP     DSP-MOD  KEY-MOD  SERV
      DATE     TIME     JNAME    LID      NAME                 PRE RMC INT PST FIN
  MLS     USER-SECLABEL RSRC-SECLABEL MODE   SRC     RRC      RSN                
                                                                               
  RSAF-QAJES.64BYTE.ICSFKEY.LABEL                 *VIO  RSAF-QAJES                
       JSLID01             STCINRDR XE40 ACF9CFAT NO-RULE     -     DIRECTRY READ
  21.123 05/03 19.27    CADZSAPY   JSLID01  TEST UIDS              0   0  20   0  16
  SAF RESOURCE CLASS CSFKEYS                                                      
                                                                               
  RESOURCE NAME: QAJES.64BYTE.ICSFKEY.LABEL                                      
  CRITERIA:      CRITERIA(SMS(DSENCRYPTION))    



(The 20 0 16 return code indicates No Rule Applies and Prevent Access.)

Note: The detailed information on using ACFRPTRV report is available in the CA ACF2 for z/OS Reports and Utilities Guide.

 

Grant CA Dispatch / CADZSAPn SAPI tasks Tasks READ Access to the Encryption Keys

Below, there are sample security commands to grant READ access to the spool encryption keys. To minimize the risk of encountering the situation and problems described earlier, it is strongly recommended that the CA Dispatch / CADZSAPn SAPI tasks be granted access to ALL the spool encryption keys.

CA Top Secret

If you use CA Top Secret mainframe security, you can use the following command to grant the CA Dispatch CADZSAPn SAPI task(s) READ access to the encryption keys:

  TSS PER(acid) CSFKEYS(csfkey1) SYMCPACFWRAP(YES)                +
    SYMCPACFRET(YES) CRITERIA(SMS(DSENCRYPTION))

where:

  • acidspecifies the accessor ID for the CA Dispatch CADZSAPn SAPI task(s)
  • csfkey1specifies the key label for the required encryption key

IBM RACF

If you use IBM RACF security, you can grant the CA Dispatch CADZSAPn SAPI tasks READ access to the encryption keys with the following command:

  PERMIT csfkey1 CLASS(CSFKEYS) ACCESS(READ) ID(name)

where:

  • csfkey1specifies the key label for the required encryption key
  • namespecifies the user ID(s) or group name(s) for the CA Dispatch / CADZSAPn SAPI task(s)

 

CA ACF2

If you use CA ACF2 mainframe security, you can use the following commands to grant the CA Dispatch / CADZSAPn SAPI tasks READ access to the encryption keys:

  COMPILE * STORE

  $KEY(csfkeys) TYPE(SAF)

  UID(*****userid1) SERVICE(READ) ALLOW

  F ACF2,REBUILD(SAF)

where:

  • csfkeys specifies the PROFILE record containing ICSF keys
  • userid1specifies the user ID of the CA Dispatch / CADZSAPn SAPI task(s)

 

If a situation such as the ones described above is encountered, use the security subsystem command described earlier in this article to grant the CA Dispatch / CADZSAPn SAPI tasks READ access to the required encryption keys. The tasks can then be restarted to resume their normal operation. Once the tasks are running, you can release the held spool datasets to allow them to be collected by the tasks.