Finding cryptographic attributes
The purpose of this appendix is to introduce a process that can be used when creating your cryptographic inventory with the available tools. The output from this process helps you to make qualified choices in terms of protecting your programs and applications against future threats from quantum computer attacks, which are also known as a cryptographically relevant quantum computer (CRQC) attacks.
The suggested process requires manual analysis to discover which cryptographic algorithms, key lengths, and key labels are used in your programs and applications.
This appendix includes the following topics:
A.1 Tools for cryptographic inventory
The examples that are used in this appendix show how cryptographic attributes can be located for a COBOL program by using the following IBM Z tools:
•System Display and Search Facility (SDSF) Job Listing
This utility allows you to monitor, control, and view the output of jobs in the system. After submitting a job, it is common to use SDSF to review the output for successful completion, or to review and correct JCL errors.
•ICSF System Management Facility (SMF) records:
ICSF uses SMF record type 82 to record certain ICSF events. The following recorded information is important to our discussion:
 – Sub-type 31, which contains cryptographic statistics data for cryptographic engines (ENG), cryptographic services (SRV), and cryptographic algorithms (ALG) for a Logical Partition (LPAR)
 – Sub-types 40 – 42, which contains ICSF key lifecycle events.
 – Sub-types 44 – 46, which contains ICSF key usage events.
•IBM Application Discovery and Delivery Intelligence, which provides API call information from scanning COBOL applications.
•IBM Crypto Analytics Tool (CAT), which provides information about the cryptographic entities, including the key material and key data sets.
A.2 Investigation process
You can start the investigation process based on output from any of the four IBM tools, as shown in Figure A-1.
Figure A-1 Tools for cryptographic inventory
The investigation process and steps vary depending on the output from the tool with which you start. The different steps are described next.
A.2.1 Starting with application source code scan from IBM ADDI
If you are starting with application source code that was scanned by IBM ADDI and uses cryptography, complete the following steps:
1. Select the application source code from the ADDI scan that you want to investigate.
2. Identify the ProgramName in the ADDI scan of the application source code.
3. Determine the job or started task that runs the executable.
4. Create reports from ICSF SMF record type 82:
 – Tailor CSFSMFJ in SYS1.SAMPLIB to fit your environment.
 – Run CSFSMFJ.
5. Identify the ICSF services that are called by the job or started task and the related key material from the SMF records.
6. Review the key details from the CAT snapshot.
A.2.2 Starting with a policy check in the IBM CAT
If you ran a policy check in the IBM CAT component and now have a list of keys from your keystores that are deemed to be weak keys, complete the following steps:
1. Review the key details from the CAT policy scan in the snapshot.
2. Create reports from ICSF SMF record type 82 that reference the key details by key label or by key check value (KCV):
 – Tailor CSFSMFJ in SYS1.SAMPLIB to fit your environment
 – Run CSFSMFJ
3. Identify the ICSF service calls that relate to the key material from the SMF records.
4. Determine the job or started task from the ICSF SMF records.
5. Identify the executable from the job listing in SDSF and application source code.
6. Review the ADDI scanning of the application source code.
A.2.3 Starting with an application that you know
If you know the application that uses cryptographic functions, complete the following steps:
1. Select the application jobs or started tasks in the SDSF job listing.
2. Determine the application source code from the executable from the job.
3. Create reports from ICSF SMF record type 82:
 – Tailor CSFSMFJ in SYS1.SAMPLIB to fit your environment
 – Run CSFSMFJ
4. Identify the ICSF service calls that relate to key material from the ICSF SMF records.
5. Verify the ADDI scanning of the application source code.
6. Review the key details from the CAT snapshot.
A.2.4 Starting with SMF record type 82 reports
If you find SMF 82 subtype 31 records that indicate the use of weak cryptographic algorithms, complete the following steps:
1. Identify the jobs or started tasks and users, ICSF service calls, and key material from the SMF 82 records.
2. Find the jobs or started tasks from the SMF records in the SDSF job listing.
3. Identify the executable modules from the SDSF job listing.
4. Determine the application source code from the executable.
5. Verify the ADDI scanning of the application source code.
6. Review the key details from the CAT snapshot.
Regardless of the investigation process that you decide to use, all findings of the cryptographic usage and configuration in your environment must be documented in your cryptographic inventory, as described in “Establishing a cryptographic inventory” on page 58.
A.3 Process that was used
In this section, we provide examples of how to proceed with the investigation process by using an ADDI scanning of a set of source modules, as described in A.2.1, “Starting with application source code scan from IBM ADDI” on page 123. Examples of key usage events and a key lifecycle event are provided.
A.3.1 Examples of finding key usage events
In Figure A-2, we can see that a source module and a few sub modules were ADDI scanned. The program is called DKMSKSA (see the ProgramName column).
Figure A-2 Sample1: Source module
Next, we identify two cryptographic functions that are used by DKMSKSA and map them to the key material.
A call to APIName CSNBENC that is found in DKMSKSA shows the StartRow (8960 and 9202) of the call to CSNBENC.
The value that is shown in the StartRow column is the line number in DKMSKSA where CSNBENC is called.
To map the APIName from CCA to an ICSF service call from the ProgramName and APIDescription, we must take a short detour. In Figure A-3, we can see that the ICSF entry point name (CSFENC) corresponds to the CCA entry point name (CSNBENC).
Figure A-3 Resource names for CCA and ICSF entry points: Encipher
The CCA and ICSF entry point names tell you which cryptographic operations are being used.
The DKMSRKX source module also does a call to CSNDRKX (see Figure A-4). It can be seen that the CSNDRKX call is made from StartRow 395 in DKMSRKX (ProgramName).
Figure A-4 Sample 2: Source module
Once again to map the APIName from CCA to an ICSF service call from the ProgramName and APIDescription, we must take a short detour. In Figure A-5 we can see that the ICSF entry point name (CSNDRKX) corresponds to the CCA entry point name (CSFRKX).
Figure A-5 Resource names for CCA and ICSF entry points - Remote Key Export
For more information about resource names for CCA and ICSF entry points, see CCA and ICSF entry points, see ICSF Application Programmer’s Guide, SC14-7508.
Having identified the two ICSF service calls, we now proceed to the next step in the investigation process: identifying the executable module from the source module. This process requires that you understand the steps that are involved in building an executable from application source code and finding the name of the executable.
In our environment, we determined that the DKMSKSA includes the DKMSRKX source code.
Next, we identify the corresponding job execution from the SDSF job listing. At this point, application knowledge is needed in terms of which jobs are involved in executing DKMSKSA and how the program invocation is made. Figure A-6 shows a list of the jobs that execute the DKMSKSA program. The jobs executed on 25 May 2022 (05/25/2022) around 7:00 AM.
 
 
 
Figure A-6 Job listing
 
Important: The job execution time is needed to identify the relevant SMF records.
For our example, we identified the job IDs that are based on the DKMSKSA program in the JCL libraries. This task also is manual.
Using two jobs as examples for SMF record type 82 subtypes 31 and 44 correlation, we look at job IDs JOB07760 and JOB07761 from Figure A-6 on page 126.
By looking at the JCL library for the two members for DPEAPPD (JOB07760) and DPEADPE (JOB07761), we can determine from the SYSTSIN statement which program is to be run.
In Example A-1, we see job DPEAPPD runs program PANDEC.
Example A-1 JCL for DPEAPPD
//DPEAPPD JOB (9060-02292-01-33,LU2),'RUN PANDEC ',
// MSGCLASS=T,CLASS=G,MSGLEVEL=(1,1)
/*JOBPARM S=MVSF
//*------------------------------------------------------------------
//RUNAPI EXEC PGM=IKJEFT01,REGION=0M
//STEPLIB DD DISP=SHR,DSN=DPLMF.KSA0501X.LOAD
// DD DISP=SHR,DSN=DPLMF.KSA0501X.LOADD
// DD DSN=DB2FSYS.SDSNEXIT,DISP=SHR
// DD DSN=DB2FSYS.SDSNLOAD,DISP=SHR
//SYSTSIN DD *
DSN SYST(DB2F)
RUN PROGRAM(PANDEC) PLAN(KSA0501V)
END
In Example A-2, we see job DPEAPPE runs program PANENC.
Example A-2 JCL for DPEAPPE
//DPEAPPE JOB (9060-02292-01-33,LU2),'RUN PANENC ',
// MSGCLASS=T,CLASS=G,MSGLEVEL=(1,1)
/*JOBPARM S=MVSF
//*ABCDE-------------------------------------------------------------
//RUNAPI EXEC PGM=IKJEFT01,REGION=0M
//STEPLIB DD DISP=SHR,DSN=DPLMF.KSA0501X.LOAD
// DD DISP=SHR,DSN=DPLMF.KSA0501X.LOADD
// DD DSN=DB2FSYS.SDSNEXIT,DISP=SHR
// DD DSN=DB2FSYS.SDSNLOAD,DISP=SHR
//SYSTSIN DD *
DSN SYST(DB2F)
RUN PROGRAM(PANENC) PLAN(KSA0501V)
END
Both programs (PANDEC and PANENC) call the DKMSKSA program. Although the input parameters are different, this issue is irrelevant in the context of mapping the key material and ICSF services to DKMSKSA.
In Example A-3, we can see PANENC calls DKMSKSA.
Example A-3 PANENC calls DKMSKSA
BA-CALL-DKMSKSA SECTION.
*****************************************************************
* CALL DKMSKSA *
*****************************************************************
 
CALL DKMSKSA USING DAPI-KSA-V01
DISPLAY 'API RETURN-CODE = ' RETURN-CODE
We have two job IDs (JOB07760 and JOB07761) that run program DKMSKSA. Now, we need to identify the ICSF SMF record type 82 entries. We want to search for subtypes 31, 40 – 42, and 44 – 46 in the timeframe in which the job was run. In our environment, SMF records are collected in half-hour intervals.
In Example A-4, the SMF record interval on 05/25/2022 is 07:00:30 - 07:30:30 when JOB07760 (DEAPPD) user DPEAP was run.
Example A-4 SMF record type 82 subtype 31 (hex ‘001F’)
Subtype=001F Crypto Usage Statistics
Written periodically to record crypto usage counts
25 May 2022 7:30:30.11
TME... 00293EA3 DTE... 0122145F SID... MVSF SSI... 00000000 STY... 001F
INTVAL_START.. 05/25/2022 07:00:30.026731
INTVAL_END.... 05/25/2022 07:30:30.111713
USERID_AS..... DPEAP
USERID_TK.....
JOBID......... JOB07760
JOBNAME....... DPEAPPD
JOBNAME2......
PLEXNAME...... MVSFPLEX
DOMAIN........ 0
ENG...CARD...7C01/93AACJPJ... 5
ENG...CARD...7C03/93AACJN6... 5
ALG...DES112..... 10
SRV...CSFENC..... 10
In JOB07761 (DEAPPE), user DPEAP was run at the same time as JOB07760 (see Example A-5).
Example A-5 SMF record type 82 subtype 31 (hex ‘001F’)
Subtype=001F Crypto Usage Statistics
Written periodically to record crypto usage counts
25 May 2022 7:30:30.11
TME... 00293EA3 DTE... 0122145F SID... MVSF SSI... 00000000 STY... 001F
INTVAL_START.. 05/25/2022 07:00:30.026731
INTVAL_END.... 05/25/2022 07:30:30.111713
USERID_AS..... DPEAP
USERID_TK.....
JOBID......... JOB07761
JOBNAME....... DPEAPPE
JOBNAME2......
PLEXNAME...... MVSFPLEX
DOMAIN........ 0
ENG...CARD...7C01/93AACJPJ... 5
ENG...CARD...7C03/93AACJN6... 5
ALG...DES112..... 10
SRV...CSFENC..... 10
The information in the different subtypes varies. Subtypes 31 and 40 – 42 all contain job name and user ID; sub-types 44 – 46 are accumulated over user ID and key ID. For the ICSF service that is called CSFENC, we must find a subtype 44 (hex ‘002C’) that maps to CSFENC for user DPEAP over the relevant period.
The usage count in subtype 44 records might be lager than identified in the subtype 31 records. In Example A-6, we can see a record that has 20 calls to CSFENC for user DPEAP in the relevant period of our application. This result corresponds with the two usage statistics records in which the two jobs in Example A-4 and Example A-5 had 10 calls to CSFENC each.
In some calls that were made to ICSF, the key label might not be present; rather, the key fingerprint or key check value is present to help identify a key.
Example A-6 Subtype 44 key usage event
Subtype=002C CCA Symmetric Key Usage Event
Written for usage events related to symmetric CCA tokens
25 May 2022 11:02:46.08
TME... 003CADA0 DTE... 0122145F SID... MVSF SSI... 00000000 STY... 002C
STOD.. 05/25/2022 05:00:48.402960
ETOD.. 05/25/2022 11:02:45.849556
SRV... CSFENC
USGC.. 20
LBL... VDEKDESW3.00.500000.203704.IX0001 DATA
TOKFMT Fixed
KALG.. DES
KSEC.. Wrapped by MK
CV.... '00007D0003600081'x (DATA*)
TIV... 'C97A80A9'x
KFP... 010105D5B74D
ENCZ.. 'D5B74D'x
End User Identity...
USRI.. DPEAP
A key usage event record is available that relates to two job executions. The key label is identified as VDEKDESW3.00.500000.203704.IX0001. The key label and details can also be found in the IBM CAT GUI (see Figure A-7).
Figure A-7 Key label and details
A.3.2 Examples of finding key lifecycle events
Starting from the SDSF job listing that is shown in Figure A-6 on page 126, we use job ID JOB07756 as an example for cryptographic usage and key lifecycle events. For this example, we correlate SMF record type 82 subtypes 31 and 40.
JOB07756 is run by using the JCL member DPEAPDER (see Example A-7). Here, we find that program DKMSKSA calls DERKEYS.
Example A-7 JCL for DPEAPDER
//DPEAPDER JOB (9060-02292-01-33,LU2),'TEST DERKEYS',
// MSGCLASS=T,CLASS=G,MSGLEVEL=(1,1)
/*JOBPARM S=MVSF
//RUNAPI EXEC PGM=IKJEFT01,REGION=0M
//STEPLIB DD DISP=SHR,DSN=DPLMF.KSA0501X.LOAD
// DD DISP=SHR,DSN=DPLMF.KSA0501X.LOADD
// DD DSN=DB2FSYS.SDSNEXIT,DISP=SHR
// DD DSN=DB2FSYS.SDSNLOAD,DISP=SHR
//SYSTSIN DD *
DSN SYST(DB2F)
RUN PROGRAM(DERKEYS) PLAN(KSA0501V)
END
For JOB07756 (DEAPDER, user DPEAP), we see in Example A-8 that the record covers the interval of 05/25/2022, 07:00:30 - 07:30:30.
Example A-8 SMF record type 82 subtype 31 (hex ‘001F’)
Subtype=001F Crypto Usage Statistics
Written periodically to record crypto usage counts
25 May 2022 7:30:30.11
TME... 00293EA3 DTE... 0122145F SID... MVSF SSI... 00000000 STY... 001F
INTVAL_START.. 05/25/2022 07:00:30.026731
INTVAL_END.... 05/25/2022 07:30:30.111713
USERID_AS..... DPEAP
USERID_TK.....
JOBID......... JOB07756
JOBNAME....... DPEAPDER
JOBNAME2......
PLEXNAME...... MVSFPLEX
DOMAIN........ 0
ENG...CARD...7C01/93AACJPJ... 20
ENG...CARD...7C03/93AACJN6... 21
ENG...CPACF... 1
ALG...DES112..... 7
ALG...DES168..... 51
ALG...SHA1....... 1
SRV...CSFKTB..... 8
SRV...CSFOWH..... 1
SRV...CSFDKG..... 8
SRV...CSFRKX..... 17
Among the ICSF services called in this job, CSFRKX is called 17 times during the execution. CSFRKX triggers a key lifecycle event, in this case subtype 40 (hex ‘0028’) records are generated. These records are written shortly after the call occurs and is not an aggregated record as with the key usage event records. We can then search for a subtype 40 records in the timeframe of the job execution and for the job name DPEAPDER (see Example A-9).
Example A-9 SMF record type 82 subtype 40 (hex ‘0028’)
Subtype=0028 CCA Symmetric Key Lifecycle Event
Written for lifecycle events related to symmetric CCA tokens
25 May 2022 7:01:41.30
TME... 00269B52 DTE... 0122145F SID... MVSF SSI... 00000000 STY... 0028
KEV... Key Exported
SRV... CSFRKX
LBL... VZMKDES.00.3000 EXPORTER
KFP... 01010562C123
ENCZ.. '62C123'x
TOKFMT Fixed
KALG.. DES
KSEC.. Wrapped by MK
CV.... '00417E0003600081'x (EXPORTER/OKEYXLAT)
TIV... '384479E0'x
ICSF Server Identity...
USRI.. CSF00000
GRPN.. CC
JBN... CSF
RST... 7:35:21.23
RSD... 24 May 2022
SUID.. 4040404040404040
End User Identity...
USRI.. DPEAP
GRPN.. DP
JBN... DPEAPDER
RST... 7:01:41.18
RSD... 25 May 2022
SUID.. 4040404040404040
The key label in this case is identified as VZMKDES.00.3000 and can be found in IBM CAT, as shown in Figure A-8.
Figure A-8 IBM CAT - key label and details
A.3.3 Summary
We started with an ADDI scan of programs, DKMSKSA and DKMSRKX. Then, we identified two ICSF service calls, the jobs that performed them, and the cryptographic keys that were used in the ICSF service calls and key lifecycle events.
Searching through ICSF SMF records and SDSF job listings can be a significant undertaking and time consuming, depending on the use of cryptographic functions. A deep understanding of your JCL, applications, and programs is essential.
In addition, ICSF SMF records are not always written at the same time. In our environment, SMF type record 82 subtype 31 are written twice every hour (at top and bottom of the hour), and subtypes 40 – 42 are written as they occur. SMF record type 82 subtypes 44 – 46 are written at six-hour intervals, beginning at the time ICSF is started. The intervals at which the SMF records are written must be considered when identifying application and program use of ICSF service calls and their associated cryptographic material.
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset