Maintaining the ICSF environment
With ICSF installed and configured for data set encryption, it is important to maintain the ICSF environment. This process includes several tasks, such as verifying the master keys, verifying the ICSF installation options, ensuring the CKDS has sufficient space, and validating the CKDS keys.
This chapter includes the following topics:
8.1 Viewing master key information
Master key information can be verified at ICSF initialization, during a master key rotation, and any time a crypto express adapter is enabled. You can check the status and state of a master key by using the ICSF utility panels and z/OS operator commands.
8.1.1 ICSF Coprocessor Management panel
You can obtain information about your crypto express adapter configuration and usage by using the ICSF ISPF panels. The primary panel indicates the crypto domain that is in use (84), as shown in Example 8-1.
Example 8-1 ICSF ISPF primary panel
OPTION ===> 1
System Name: SC60 Crypto Domain: 84
Enter the number of the desired option.
1 COPROCESSOR MGMT - Management of Cryptographic Coprocessors
Select option 1 COPROCESSOR MGMT to see the results, as shown in Example 8-2.
Example 8-2 Option 1 COPROCESSOR MGMT selection results
Select the cryptographic features to be processed and press ENTER.
Action characters are: A, D, E, K, R, S, and V. See the help panel for details.
CRYPTO SERIAL
FEATURE NUMBER STATUS AES DES ECC RSA P11
------- -------- -------------------- --- --- --- --- ---
6C00 DV785304 Active A A A A
6A01 N/A Active
Selecting COPROCESSOR MGMT displays the state of your crypto adapters. The “A” stands for “active” (which is expected). When key data sets are not initialized, the state of the crypto adapter is marked “I” for “ignored”.
For more information about activating a master key, see 4.3.5, “Loading the AES master key” on page 75.
Enter s on the line next to a cryptographic feature to see more information about its status (see Example 8-3).
Example 8-3 Status of a crypto adapter
REGISTER STATUS COPROCESSOR 6C00
More: +
Crypto Serial Number : DV785304
Status : ACTIVE
PCI-HSM Compliance Mode : INACTIVE
Compliance Migration Mode : INACTIVE
AES Master Key
New Master Key register : EMPTY
Verification pattern :
Old Master Key register : EMPTY
Verification pattern :
Current Master Key register : VALID
Verification pattern : 49232659E5B39664
As shown in Example 8-3, the Current Master Key register is VALID and the Status is ACTIVE.
8.1.2 Display ICSF operator command (D ICSF,MKS and D ICSF,CARDS)
On systems that are running ICSF FMID HCR77B1 or later, and z/OS V2R1 or later, you can use Display ICSF operator commands to obtain master key information and crypto express adapter status.
The D ICSF,MKS command and the status of the master key registers is shown in Example 8-4.
Example 8-4 D ICSF,MKS command and results
D ICSF,MKS
CSFM668I 13.38.20 ICSF MKS 566
SYSNAME: SC60 DOMAIN: 084 CPC Name: CETUS
FEATURE SERIAL# STATUS AES DES ECC RSA P11
6C00 DV785304 Active A A A A
The CCA feature device number (6C00), its serial number (DV785304), its status (active), and the master keys that are loaded (AES for our purpose) are shown in Example 8-4.
Command D ICSF,CARDS provides more information (see Example 8-5).
Example 8-5 D ICSF, CARDS command and results
D ICSF,CARDS
CSFM668I 13.40.58 ICSF CARDS 568
ACTIVE DOMAIN = 084
CRYPTO EXPRESS6 COPROCESSOR 6C00
STATUS=Active SERIAL#=DV785304 LEVEL=6.0.6z
REQUESTS=0000001185 ACTIVE=0000
CRYPTO EXPRESS6 ACCELERATOR 6A01
STATUS=Active
REQUESTS=0000000005 ACTIVE=0000
The active domain (84), the number of requests that are sent to the adapter since ICSF initialization (1185 for the device), and the firmware level of the device (for example, 6.0.6z) also are shown in Example 8-5 on page 145.
8.2 Viewing ICSF options
ICSF installation options can be verified by using the ICSF utility panels and MVS operator commands.
8.2.1 ICSF OPSTAT utility panel
You can display your ICSF configuration options by using the ICSF ISPF panels (see Example 8-6).
Example 8-6 ICSF selecting Option 3
HCR77C1 -------------- Integrated Cryptographic Service Facility ----
OPTION ===> 3.1
System Name: SC74 Crypto Domain: 3
Enter the number of the desired option.
1 COPROCESSOR MGMT - Management of Cryptographic Coprocessors
2 KDS MANAGEMENT - Master key set or change, KDS Processing
3 OPSTAT - Installation options
4 ADMINCNTL - Administrative Control Functions
5 UTILITY - ICSF Utilities
6 PPINIT - Pass Phrase Master Key/KDS Initialization
7 TKE - TKE PKA Direct Key Load
8 KGUP - Key Generator Utility processes
9 UDX MGMT - Management of User-Defined Extensions
------------------------ ICSF - Key Data Set Management ------------
Select option 3.1 OPSTAT to see the results, as shown in Example 8-7.
Example 8-7 iCSF configuration options
---------------------- ICSF - Installation Option Display -- Row 1 to 23 of 33
COMMAND ===> SCROLL ===> PAGE
Active CKDS: PLEX75.SHARED.SCSFCKDS
Active PKDS: PLEX75.SHARED.SCSFPKDS
Active TKDS: PLEX75.SHARED.SCSFTKDS
OPTION CURRENT VALUE
------ -------------
AUDITKEYLIFECKDS Audit CCA symmetric key lifecycle events TOKEN(N),LABEL(N)
AUDITKEYLIFEPKDS Audit CCA asymmetric key lifecycle events TOKEN(N),LABEL(N)
AUDITKEYLIFETKDS Audit PKCS #11 key lifecycle events TOKO(N),SESSO(N)
AUDITKEYUSGCKDS Audit CCA symmetric key usage events TOK(N),LAB(N),
INT(001/00.00.00)
AUDITKEYUSGPKDS Audit CCA asymmetric key usage events TOK(N),LAB(N),
INT(001/00.00.00)
AUDITPKCS11USG Audit PKCS #11 usage events TOKO(N),SESSO(N),
NOKEY(N),
INT(001/00.00.00)
CHECKAUTH RACF check authorized callers NO
CICSAUDIT Audit CICS client identity NO
COMPAT Allow CUSP/PCF compatibility NO
COMPLIANCEWARN Compliance Warn mode NOT SPECIFIED
CTRACE CTRACE parmlib used at ICSF startup CTICSF00
DEFAULTWRAP Default symmetric key wrapping - internal ORIGINAL
DEFAULTWRAP Default symmetric key wrapping - external ORIGINAL
DOMAIN Current domain index or usage domain index 3
FIPSMODE Operate PKCS #11 in FIPS 140-2 mode NO,FAIL(NO)
KDSREFDAYS Number of days between reference updates 1
KEYARCHMSG JOBLOG message for archived key use NO
MASTERKCVLEN Length of master key verification patterns ALL
MAXSESSOBJECTS Max non-auth pgm PKCS #11 session objects 65535
F1=HELP F2=SPLIT F3=END F4=RETURN F5=RFIND F6=RCHANGE
F7=UP F8=DOWN F9=SWAP F10=LEFT F11=RIGHT F12=RETRIEVE
8.2.2 Display ICSF operator command (D ICSF,OPT)
On systems that are running ICSF FMID HCR77B1 or later, and running z/OS V2R1 or later, you can use the Display ICSF (D ICSF,OPT) command to display ICSF options.
The D ICSF,OPT command and the ICSF options are shown in Example 8-8.
Example 8-8 Display ICSF options
D ICSF,OPT
CSFM668I 11.21.40 ICSF OPTIONS 108
SYSNAME = SC74 ICSF LEVEL = HCR77C1
LATEST ICSF CODE CHANGE = 04/03/18
Refdate update interval in Days/HH.MM.SS = 001/00.00.00
Refdate update period in Days/HH.MM.SS = 000/01.00.00
MASTERKCVLEN = display ALL digits
AUDITKEYLIFECKDS: Audit CCA symmetric key lifecycle events
SYSNAME LABEL TOKEN
SC74 No No
AUDITKEYLIFEPKDS: Audit CCA asymmetric key lifecycle events
SYSNAME LABEL TOKEN
SC74 No No
AUDITKEYLIFETKDS: Audit PKCS #11 key lifecycle events
SYSNAME TOKOBJ SESSOBJ
SC74 No No
AUDITKEYUSGCKDS: Audit CCA symmetric key usage events
SYSNAME LABEL TOKEN Interval Days/HH.MM.SS
SC74 No No 001/00.00.00
AUDITKEYUSGPKDS: Audit CCA asymmetric key usage events
SYSNAME LABEL TOKEN Interval Days/HH.MM.SS
SC74 No No 001/00.00.00
AUDITPKCS11USG: Audit PKCS #11 usage events
SYSNAME TOKOBJ SESSOBJ NOKEY Interval Days/HH.MM.SS
SC74 No No No 001/00.00.00
     STATS:
     SC74 NONE
     COMPLIANCEWARN: Compliance warning events
     SC74 NOT SPECIFIED STATS:
8.3 Refreshing the CKDS
ICSF references an in-storage copy of the CKDS for key label lookup. However, when utilities, such as KGUP or IDCAMS, are used to read and write directly to the key data sets, changes are made to the CKDS that is stored on disk rather than the in-storage copy. ICSF does not recognize the changes that were made to disk unless the CKDS is refreshed such that the in-storage copy of the CKDS is updated.
 
Note: No refresh is required for keys that are generated by the ICSF panel or callable services.
8.3.1 Refreshing a CKDS shared in a sysplex
If you update the CKDS on disk and are sharing the CKDS in a sysplex, use the Coordinated CKDS Refresh panel utility to refresh the local CKDS and alert all members of the sysplex that are sharing the CKDS to refresh their CKDS. Coordinated CKDS Refresh can be run on a single system.
While the coordinated refresh is in progress, all active systems in the sysplex that are sharing the active KDS or the new KDS are affected. Updates also are suspended. For more information about rejecting update requests, see “Disabling CKDS Updates” on page 153 and “Re-enable CKDS Updates” on page 155.
Complete the following steps to perform a coordinated CKDS refresh:
1. From the ICSF utility panels, select option 2 KDS management (see Example 8-9).
Example 8-9 ICSF selecting Option 2
HCR77C1 -------------- Integrated Cryptographic Service Facility ----
OPTION ===> 2
System Name: SC74 Crypto Domain: 3
Enter the number of the desired option.
1 COPROCESSOR MGMT - Management of Cryptographic Coprocessors
2 KDS MANAGEMENT - Master key set or change, KDS Processing
3 OPSTAT - Installation options
4 ADMINCNTL - Administrative Control Functions
5 UTILITY - ICSF Utilities
6 PPINIT - Pass Phrase Master Key/KDS Initialization
7 TKE - TKE PKA Direct Key Load
8 KGUP - Key Generator Utility processes
9 UDX MGMT - Management of User-Defined Extensions
------------------------ ICSF - Key Data Set Management ------------
2. Select option 1 CKDS management (see Example 8-10).
Example 8-10 ICSF Key Data Set Management with Option 1
------------------------ ICSF - Key Data Set Management ------------
OPTION ===> 1
Enter the number of the desired option.
1 CKDS MANAGEMENT - Perform Cryptographic Key Data Set (CKDS)
functions including master key management
3. Select option 4 COORDINATED CKDS REFRESH (see Example 8-11).
Example 8-11 ICSF CKDS Management Option 4
---------------------------- ICSF - CKDS Management ---------------------------
OPTION ===> 4
Enter the number of the desired option.
1 CKDS OPERATIONS - Initialize a CKDS, activate a different CKDS,
(Refresh), or update the header of a CKDS and make
it active
2 REENCIPHER CKDS - Reencipher the CKDS prior to changing a symmetric
master key
3 CHANGE SYM MK - Change a symmetric master key and activate the
reenciphered CKDS
4 COORDINATED CKDS REFRESH - Perform a coordinated CKDS refresh
You see a panel that is similar to the panel that is shown in Example 8-12.
Example 8-12 ICSF - Coordinated KDS Refresh
------------------------ ICSF - Coordinated KDS Refresh --------------------
COMMAND ===>
To perform a coordinated KDS refresh to a new KDS, enter the KDS names
below and optionally select the rename option. To perform a coordinated KDS
refresh of the active KDS, simply press enter without entering anything on
this panel.
KDS Type ===> CKDS
Active KDS ===> 'PLEX75.SHARED.SCSFCKDS'
New KDS ===> 'PLEX75.SHARED.LARGER.SCSFCKDS'
Rename Active to Archived and New to Active (Y/N) ===> y
Archived KDS ===> 'PLEX75.SHARED.SMALL.SCSFCKDS'
In the new KDS field, specify the name of the new KDS to which you want to refresh.
In the archived KDS field, specify the data set name to which you want the active KDS renamed. If the rename option is specified, the active KDS is renamed to the archived KDS name and the new KDS is renamed to the active KDS name. This action removes the necessity to modify the ICSF startup options because the data set remains the same.
 
Note: The archived KDS name cannot be the same name as the active KDS name or new KDS name.
4. Press Enter to view a confirmation panel (see Example 8-13).
Example 8-13 Confirmation panel
--------------- ICSF - Coordinated KDS Refresh Confirmation --------------
Are you sure you want to perform a Coordinated KDS Refresh
from 'PLEX75.SHARED.SCSFCKDS'
to 'PLEX75.SHARED.LARGER.SCSFCKDS'?
Command ===> _ Enter Y to confirm
5. Enter Y to confirm the action.
The Refresh successful message in the upper right corner displays (see Example 8-14).
Example 8-14 Refresh successful message
------------------------ ICSF - Coordinated KDS Refresh --- REFRESH SUCCESSFUL
COMMAND ===>
To perform a coordinated KDS refresh to a new KDS, enter the KDS names
below and optionally select the rename option. To perform a coordinated KDS
refresh of the active KDS, simply press enter without entering anything on
this panel.
KDS Type ===> CKDS
Active KDS ===> 'PLEX75.SHARED.SCSFCKDS'
New KDS ===> 'PLEX75.SHARED.LARGER.SCSFCKDS'
Rename Active to Archived and New to Active (Y/N) ===> Y
Archived KDS ===> 'PLEX75.SHARED.SMALL.SCSFCKDS'
If you review the SYSLOG or OPERLOG, you see a sequence of messages that were sent by ICSF. These messages confirm the successful run of the coordinated refresh (see Example 8-15).
Example 8-15 Messages confirming success
CSFM653I CKDS LOADED 9 RECORDS WITH AVERAGE SIZE 253
CSFM622I COORDINATED REFRESH PROGRESS: NEW IN-STORAGE KDS CONSTRUCTED.
CSFM622I COORDINATED REFRESH PROGRESS: MKVPS VERIFIED BETWEEN CURRENT ACTIVE AND TARGET DATA SETS.
CSFM618I CKDS DATA SET PLEX75.SHARED.SCSFCKDS RENAMED TO PLEX75.SHARED .SMALL.SCSFCKDS
CSFM618I CKDS DATA SET PLEX75.SHARED.SCSFCKDS.DATA RENAMED TO PLEX75.SHARED.SMALL.SCSFCKDS.DATA
CSFM618I CKDS DATA SET PLEX75.SHARED.SCSFCKDS.INDEX RENAMED TO
PLEX75.SHARED.SMALL.SCSFCKDS.INDEX
CSFM618I CKDS DATA SET PLEX75.SHARED.LARGER.SCSFCKDS RENAMED TO
PLEX75.SHARED.SCSFCKDS
CSFM618I CKDS DATA SET PLEX75.SHARED.LARGER.SCSFCKDS.DATA RENAMED TO
PLEX75.SHARED.SCSFCKDS.DATA
CSFM618I CKDS DATA SET PLEX75.SHARED.LARGER.SCSFCKDS.INDEX RENAMED TO
PLEX75.SHARED.SCSFCKDS.INDEX
CSFM622I COORDINATED REFRESH PROGRESS: DATA SET RENAMING COMPLETE.
IEF196I IEF237I 9788 ALLOCATED TO SYS00006
CSFM653I CKDS LOADED 9 RECORDS WITH AVERAGE SIZE 253
IEF196I CSFM653I CKDS LOADED 9 RECORDS WITH AVERAGE SIZE 253
IEF196I IGD104I PLEX75.SHARED.SCSFCKDS RETAINED,
IEF196I DDNAME=SYS00006
CSFM622I COORDINATED REFRESH PROGRESS: NEW IN-STORAGE KDS LOADED ON
REMOTE SYSTEMS.
CSFM622I COORDINATED REFRESH PROGRESS: OPERATION TERMINATION IS
TEMPORARILY INHIBITED.
CSFM622I COORDINATED REFRESH PROGRESS: ALL FINAL CKDS DSN REFERENCES
UPDATED.
CSFM622I COORDINATED REFRESH PROGRESS: SWITCHED THE ACTIVE CKDS HASH
TABLE TO NEW.
CSFM622I COORDINATED REFRESH PROGRESS: OPERATION TERMINATION IS NOW
REENABLED.
CSFM622I COORDINATED REFRESH PROGRESS: COMPLETING CORE WORK.
CSFM622I COORDINATED REFRESH PROGRESS: ALL FINAL CKDS DSN REFERENCES
UPDATED.
IEF196I CSFM622I COORDINATED REFRESH PROGRESS: ALL FINAL CKDS DSN
IEF196I REFERENCES UPDATED.
CSFM622I COORDINATED REFRESH PROGRESS: SWITCHED THE ACTIVE CKDS HASH
TABLE TO NEW.
IEF196I CSFM622I COORDINATED REFRESH PROGRESS: SWITCHED THE ACTIVE CKDS
IEF196I HASH TABLE TO NEW.
CSFM617I COORDINATED REFRESH ACTION COMPLETED SUCCESSFULLY.
CSFU006I REFRESH FEEDBACK: RC=00000000 RS=00000000 SUPRC=00000000 SUPRS=00000000 FLAGS=00000000.
8.3.2 Refreshing a single CKDS
To update the CKDS on disk, use one of the following methods:
Use the Refresh option on the Key Administration panel to replace the in-storage copy with the disk copy.
Start a utility program to refresh the CKDS.
Refresh by using CSFEUTIL JCL
A JCL sample to refresh the in-storage copy of CKDS by using ICSF utility program CSFEUTIL is shown in Example 8-16.
Example 8-16 Refresh in-storage copy of CKDS by using ICSF utility program CSFEUTIL
//STEP20 EXEC PGM=CSFEUTIL,
// PARM='SYS1.SC60NEW.SCSFCKDS,REFRESH'
The messages from successful refresh by using CSFEUTIL are shown in Example 8-17.
Example 8-17 Messages from successful refresh
CSFM653I CKDS LOADED 12 RECORDS WITH AVERAGE SIZE 249
CSFU002I CSFEUTIL COMPLETED, RETURN CODE = 0, REASON CODE = 0.
Refresh from the KGUP panels
From the ICSF Primary menu, select Option 8 KGUP (Key Generator Utility processes) → Option 4 Refresh (Activate an existing cryptographic key data set) to refresh the in-storage copy of the CKDS.
The refresh in-storage CKDS panel is shown in Figure 8-1.
Figure 8-1 ICSF Refresh in-storage CKDS
Press Enter to perform the refresh. A successful refresh results in message CSFM653I, as shown in Example 8-18).
Example 8-18 Message CSFM653I
CSFM653I CKDS LOADED 10 RECORDS WITH AVERAGE SIZE 252
The Refresh in-storage CKDS panel displays a message to indicate a successful refresh, as shown in Figure 8-2.
Figure 8-2 ICSF Refresh Successful message
Refresh by using the ICSF utility panels
Refresh can also be performed from Option 2.1;1.2 from the ICSF Primary menu. The following options are available:
Option 2 KDS MANAGEMENT: Master key set or change, KDS Processing
Option 1 CKDS MANAGEMENT: Perform Cryptographic Key Data Set (CKDS) functions, including master key management
Option 1 CKDS OPERATIONS: Initialize a CKDS, activate a different CKDS, (Refresh), or update the header of a CKDS and make it active
Option 2 REFRESH: Activate an updated CKDS
8.4 Increasing the CKDS size
You might want to increase the size of your CKDS if your current CKDS is out of space or you determine that you need a larger CKDS.
 
Note: This method cannot be used to change the CKDS format (for example, non-KDSR to KDSR).
The process to increase the CKDS size includes the following steps:
1. Disabling CKDS updates.
2. Allocating a new, larger CKDS.
3. Copying data from the existing CKDS to the new CKDS.
4. Verifying a successful copy.
5. Refreshing ICSF with the new CKDS.
6. Reenabling CKDS updates.
Determining the current CKDS space allocation
Issue the LISTCAT ENTRIES(<CKDSNAME>) ALL command to see space allocation values for the CKDS (see Example 8-19). Next, compare the HI-A-RBA (where “A” is allocated) with the HI-U-RBA (where “U” is used) to determine whether the CKDS must be enlarged.
Example 8-19 Results of the LISTCAT ENT(<CKDSNAME>) ALL
ALLOCATION
SPACE-TYPE---------TRACK HI-A-RBA----------221184
SPACE-PRI--------------4 HI-U-RBA-----------55296
SPACE-SEC--------------1
Disabling CKDS Updates
Updates to the CKDS should be disabled before the CKDS is enlarged. This update ensures that changes are not made to the CKDS while the copy in is process.
The easiest way to disable updates to the CKDS is to use the SETICSF DISABLE,CKDS,SYSPLEX=YES operator command. The use of this command disables updates to the CKDS across all members of the sysplex.
Allocating a new, larger CKDS
Determine how large to allocate your new CKDS by using the formula that is described in 3.4.3, “Using the Common Record Format (KDSR) cryptographic key data set” on page 38.
Allocate the CKDS based on the sample as described in 4.3.2, “Creating a Common Record Format (KDSR) CKDS” on page 70. Update the primary and secondary values in the RECORDS field based on your calculations.
Copying the CKDS to the new CKDS
Use the IDCAMS utility to copy the data from the current active CKDS into a new, larger CKDS, similar to the JCL that is shown in Example 8-20.
Example 8-20 REPRO data from active CKDS to larger CKDS
// EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
REPRO -
INDATASET(PLEX75.SHARED.SCSFCKDS) -
OUTDATASET(PLEX75.SHARED.LARGER.SCSFCKDS)
Verifying the contents
Use the IDCAMS utility to list the number of records in the current CKDS. The JCL is shown in Example 8-21.
Example 8-21 REPRO to list keys
//JS010 EXEC PGM=IDCAMS
//CKDS DD DISP=SHR,DSN=PLEX75.SHARED.SCSFCKDS
//SYSPRINT DD SYSOUT=*
//OUTPUT DD SYSOUT=*,LRECL=2048
//SYSIN DD *,LRECL=80
REPRO INFILE(CKDS) OUTFILE(OUTPUT)
The results of the REPRO command, which includes nine records that consist of eight cryptographic key records and one header record, is shown in Example 8-22.
Example 8-22 Results of REPRO
REPRO INFILE(CKDS) OUTFILE(OUTPUT)
IDCAMS SYSTEM SERVICES TIME: 16:36:56
REPRO INFILE(CKDS) OUTFILE(OUTPUT)
IDC0005I NUMBER OF RECORDS PROCESSED WAS 9
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0
20170731
ICSF.SECRET.AES256.KEY001 DATA
LABEL.01.CLEAR DATA
LABEL.01.TEST DATA
LABEL.02.TEST DATA
LABEL.05.CLEAR DATA
LABEL.06.TEST DATA
SAMPLE.DERIVED.AES.IMPORTER.KEY IMPORTER
SAMPLE.RECEIVED.AES.DATA.KEY DATA
Use the IDCAMS utility to list the number of records in the new, larger CKDS. The JCL is shown in Example 8-23.
Example 8-23 Printing REPRO
//JS010 EXEC PGM=IDCAMS
//CKDS DD DISP=SHR,DSN=PLEX75.SHARED.LARGER.SCSFCKDS
//SYSPRINT DD SYSOUT=*
//OUTPUT DD SYSOUT=*,LRECL=2048
//SYSIN DD *,LRECL=80
REPRO INFILE(CKDS) OUTFILE(OUTPUT)
Verify that the new, larger CKDS contains the same number of records and labels as the original data set.
Refreshing ICSF
After the new CKDS is verified, ICSF must be refreshed to process the new CKDS. For more information, see 8.3, “Refreshing the CKDS” on page 148.
Re-enable CKDS Updates
After the CKDS is refreshed, CKDS updates can be reenabled.
Issue the SETICSF ENABLE,CKDS,SYSPLEX=YES operator command to disable updates to the CKDS across all members of the sysplex.
8.5 Validating CKDS keys
If a CKDS exists, you can check the key tokens for format errors.
Select ICSF option 2.1.7 CKDS KEY CHECK (see Figure 8-3).
---------------------------- ICSF - CKDS Management ---------------------------
OPTION ===> 7
Enter the number of the desired option.
1 CKDS OPERATIONS - Initialize a CKDS, activate a different CKDS,
(Refresh), or update the header of a CKDS and make
it active
2 REENCIPHER CKDS - Reencipher the CKDS prior to changing a symmetric
master key
3 CHANGE SYM MK - Change a symmetric master key and activate the
reenciphered CKDS
4 COORDINATED CKDS REFRESH - Perform a coordinated CKDS refresh
5 COORDINATED CKDS CHANGE MK - Perform a coordinated CKDS change master key
6 COORDINATED CKDS CONVERSION - Convert the CKDS to use KDSR record format
7 CKDS KEY CHECK - Check key tokens in the active CKDS for format errors
 
Figure 8-3 ICSF CKDS Management with Option 7 selected
The message “CHECK SUCCESSFUL” is displayed in the upper right corner if no error was detected, as shown in Figure 8-4.
---------------------------- ICSF - CKDS Management --------- CHECK SUCCESSFUL
OPTION ===>
Enter the number of the desired option.
1 CKDS OPERATIONS - Initialize a CKDS, activate a different CKDS,
 
Figure 8-4 ICSF CKDS Management with Check Successful message
8.6 Verifying the CKDS format
On systems that are running ICSF FMID HCR77B1 or later, and z/OS V2R1 or later, you can use z/OS command D ICSF,KDS to obtain more information about your KDS status (see Example 8-24).
Example 8-24 Use of the D ICSF,KDS command
D ICSF,KDS
CSFM668I 13.36.58 ICSF KDS 551
CKDS SYS1.SC60NEW.SCSFCKDS
FORMAT=KDSR SYSPLEX=N MKVPs=DES AES
PKDS SYS1.SC60NEW.SCSFPKDS
FORMAT=KDSR SYSPLEX=N MKVPs=RSA ECC
No TKDS was provided.
The system displays (message CSFM668I) the following information about the active key data sets (KDS) on the system or sysplex:
The data set name for each active KDS (CKDS, PKDS, and TKDS).
The format of the KDS (for example, KDSR is the recommended format to use). The following values are available:
 – KDSR
 – FIXED
 – VARIABLE
The communication level that is in place for the KDS (for example, 3). This information is displayed in a sysplex environment only.
Whether the KDS is being shared in a sysplex group (for example, Y/N).
The MKVPs that were started in the KDS (for example, DES AES). The following values are available:
 – DES, AES, or both for CKDS
 – RSA, ECC, or both for PKDS
 – P11, RCS, or both for TKDS
8.7 Dumping CKDS contents
You can use the IDCAMS utility to dump the contents of the CKDS to a sequential file.
 
Note: If clear keys are in your CKDS, the clear keys are made available in the dumped data set. If you secure (encrypted) keys are in your CKDS, the keys remain encrypted in the dumped data set. Protected keys are not applicable to the CKDS because they are stored in ICSF protected memory only.
After you allocate your sequential file (for example, PLEX75.SHARED.SCSFCKDS.DUMP), run JCL similar to the JCL that is shown in Example 8-25.
Example 8-25 REPRO to list keys
//JS010 EXEC PGM=IDCAMS
//CKDS DD DISP=SHR,DSN=PLEX75.SHARED.SCSFCKDS
//SYSPRINT DD SYSOUT=*
//OUTPUT DD DISP=OLD,DSN=PLEX75.SHARED.SCSFCKDS.DUMP
//SYSIN DD *,LRECL=80
REPRO INFILE(CKDS) OUTFILE(OUTPUT)
The results of running the REPRO command, which includes nine records that consist of eight cryptographic key records and one header record, is shown in Example 8-26.
Example 8-26 Results of REPRO
20170731
ICSF.SECRET.AES256.KEY001 DATA
LABEL.01.CLEAR DATA
LABEL.01.TEST DATA
LABEL.02.TEST DATA
LABEL.05.CLEAR DATA
LABEL.06.TEST DATA
SAMPLE.DERIVED.AES.IMPORTER.KEY IMPORTER
SAMPLE.RECEIVED.AES.DATA.KEY DATA
 
Note: Clear keys are never returned from the CKDS by way of any of the ICSF callable services. Only secure (encrypted) keys are returned. This result is by design to prevent disclosure of clear key material.
Another option to list the records in a CKDS is to run a REXX script from TSO. For more information about a REXX script, see this page of the IBM developerWorks website.
8.8 Browsing the CKDS
On systems that are running ICSF FMID HCR77C1 or later, you can browse the contents of the CKDS by completing the following steps:
1. Select Option 5 (see Figure 8-5).
HCR77C1 -------------- Integrated Cryptographic Service Facility ------
OPTION ===> 5
System Name: SC74 Crypto Domain: 3
Enter the number of the desired option.
1 COPROCESSOR MGMT - Management of Cryptographic Coprocessors
2 KDS MANAGEMENT - Master key set or change, KDS Processing
3 OPSTAT - Installation options
4 ADMINCNTL - Administrative Control Functions
5 UTILITY - ICSF Utilities
Figure 8-5 ICSF panel selection Option 5
2. Select Option 5 CKDS keys (see Figure 8-6).
------------------------------- ICSF - Utilities -----------------
OPTION ===> 5
Enter the number of the desired option.
1 ENCODE - Encode data
2 DECODE - Decode data
3 RANDOM - Generate a random number
4 CHECKSUM - Generate a checksum and verification and
hash pattern
5 CKDS KEYS - Manage keys in the CKDS
6 PKDS KEYS - Manage keys in the PKDS
7 PKCS11 TOKEN - Management of PKCS11 tokens
 
Figure 8-6 ICSF Utilities
You can generate any list that you want: full or partial record labels, use wildcard characters, or use option 1 List and manage all records (see Figure 8-7).
 
Tip: Ensure that you have READ access to CSFBRCK CL(CSFSERV).
------------------------------- ICSF - CKDS KEYS ----------------------------
OPTION ===> 1
Active CKDS: SYS1.SC60NEW.SCSFCKDS Keys: 19
Enter the number of the desired option.
1 List and manage all records
2 List and manage records with label key type leave blank for
 
Figure 8-7 CKDS KEYS panel to list keys
A list that is similar to the list that is shown in our environment in Figure 8-8 is displayed.
---------------------------- ICSF - CKDS KEYS List --------- Row 1 to 12 of 1
COMMAND ===> SCROLL ===> PAG
Active CKDS: SYS1.SC60NEW.SCSFCKDS Keys: 12
Action characters: A, D, K, M, P, R See the help panel for details.
Status characters: - Active A Archived I Inactive
Select the records to be processed and press ENTER
When the list is incomplete and you want to see more labels, press ENTER
Press END to return to the previous menu
A S Label Displaying 1 to 12 of 12 Key Type
-----------------------------------------------------------------------------
_ - AAAA.FIRST.KEY DATA
_ - DATASET.ENCRYPTKEY.001 DATA
_ - DATASET.PE01.TEST DATA
_ A DATASET.PE03.AC01 DATA
_ - KEYLABEL.ANDY.COU1 DATA
_ - KEYLABEL.THOMAS.LIU DATA
_ - NOSTANDARD.NAMING.CONVENTION DATA
_ - PE01.TEST DATA
_ I PE01.TEST.ACCESS.KEY DATA
_ A PE01.TEST.KEY DATA
_ - PE03.SECURE.KEY DATA
_ - SC60.TL.AES.EXPORTER.KEY EXPORTER
 
Figure 8-8 CKDS Keys list
3. When the list is incomplete and you want to see more labels (see Figure 8-9 on page 160), press Enter. Press End to return to the previous menu.
The following Status characters can be displayed in the 'S' column:
 – - Active
 – A Archived
 – I Inactive
Any other character (-) means that the key label is active.
 
Note: Ensure that data set encryption keys are always defined as DATA keys.
The following action characters are available:
 – K: Display information about the record metadata and the key attributes
 – M: Display record metadata
 – D: Delete the record from the CKDS
 – A: Archive the record (marks the record as archived)
 – R: Recall the record (marks an archived record as available for use)
 – P: Prohibit archive (marks the record so that it cannot be archived)
 
Note: The ability to archive, recall, and prohibit archive require the KDSR CKDS format.
4. Select option K to display information about the record metadata and the key attributes.
You can also verify that the keys are secured keys and protected by the AES master key (not clear keys). If the key is not encrypted, the Key Attributes field displays the message “Key value is not encrypted”, as shown in Figure 8-9.
------------------- ICSF - CKDS Key Attributes and Metadata -------------------
COMMAND ===> SCROLL ===> PAGE
Active CKDS: SYS1.SC60NEW.SCSFCKDS
Label: DATASET.PE03.AC01 DATA
Record status: Active (Archived, Active, Pre-active, Deactivated)
Select an action:
1 Modify one or more fields with the new values specified
2 Delete the record
-------------------------------------------------------------------------------
More: -
Key Attributes Key value is not encrypted
Algorithm: AES Key type: DATA
Length (bits): 256 Key check value: 16124C ENC-ZERO
Key Usage: ENCIPHER DECIPHER
 
Figure 8-9 CKDS Key Attributes and Metadata panel
5. Select option M to display record metadata (see Figure 8-10).
Active CKDS: SYS1.SC60NEW.SCSFCKDS
Label: DATASET.PE03.AC01 DATA
Record status: Active (Archived, Active, Pre-active, Deactivated)
Select an action:
1 Modify one or more fields with the new values specified
2 Delete the record
-------------------------------------------------------------------------------
YYYYMMDD YYYYMMDD
Record creation date: 20171120
Update date: 00000000
Cryptoperiod start date: 00000000 New value:
Cryptoperiod end date: 00000000 New value:
Date the record was last used: 20171120 New value:
Service called when last used: CSFSAE
Date the record was recalled: 00000000
Date the record was archived: 00000000
Archived flag: FALSE New value:
Prohibit archive flag: FALSE New value:
 
Figure 8-10 Modifying the metadata
The following metadata information is available:
Date the record was last used: 20171120
Service called when last used: CSFSAE
Some of the metadata values can be modified. To modify a value, enter a new value in the provided field. A value of all zeros can be used to remove a date field.
..................Content has been hidden....................

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