Performing a coordinated change master key

The coordinated change master key function simplifies the procedure for changing the master keys that are used by the CKDS and PKDS. Coordinated change master key may be performed on a single instance of ICSF, on a single-system sysplex, or on a multi-system sysplex.

A coordinated KDS change master key can be done by writing an application to invoke the Coordinated KDS Administration (CSFCRC) callable service. See z/OS Cryptographic Services ICSF Application Programmer's Guide for the description of the service.

Symmetric master keys

To perform a coordinated CKDS change master key, all members of the sysplex (including sysplex members that are not configured with the same active CKDS) must be at the ICSF FMID HCR7790 level or later.

Before performing a coordinated refresh, you should consider temporarily disallowing dynamic CKDS updates on all sysplex members for the CKDS you are processing. For information on disabling dynamic CKDS updates, see Steps for enabling and disabling Dynamic CKDS/PKDS access controls.

Asymmetric master keys

To perform a coordinated PKDS change master key, all members of the sysplex (including sysplex members that are not configured with the same active CKDS) must be at the ICSF FMID HCR77A0 level or later.

Before performing a coordinated refresh, you should consider temporarily disallowing dynamic PKDS updates on all sysplex members for the PKDS you are processing. For information on disabling dynamic CKDS updates, see Steps for enabling and disabling Dynamic CKDS/PKDS access controls

For the RSA master key, you need to use a TKE workstation to enter the new master key if any of your systems are IBM z9 or IBM z10 servers or an IBM z196 or IBM z114 servers where all CEX3 coprocessors have licensed internal code older than September 2011. The ICSF Master Key Entry panels will automatically set new RSA master key loaded on coprocessors running on these systems. Coordinated change master key can only be performed when new master keys are loaded in the new master key register.

Usage notes

Reenciphering a large KDS (millions of records) may cause a temporary internal suspension of KDS update requests running in parallel. If you cannot tolerate a temporary suspension in your CKDS or PKDS workload and would prefer that update requests are failed instead of suspended, you should disallow dynamic CKDS or PKDS access prior to performing the coordinated KDS change master key.
This procedure is only for reenciphering the active KDS. It is not for reenciphering archived or backup KDS copies that are not currently active.
If you have a combination of cryptographic coprocessors installed in a sysplex environment, the ICSF instance configured with the cryptographic coprocessor containing the highest level of licensed internal code must initiate the coordinated change master key. If the coordinated change master key is not initiated by the ICSF instance containing the highest level of licensed internal code, the operation will fail.

Steps to performing a coordinated KDS master key change

Before beginning this procedure, you must:

Enter the key parts of the new master key that you want to replace the current master key into all coprocessors on your system. For information about how to do this procedure, see Entering master key parts. The new master key register must be full when you change the master key.
Create a new VSAM data set that will be used by coordinated change master key to place the reenciphered KDS entries. This data set must be allocated and empty and must contain the same data set attributes as the active KDS you are performing the coordinated change master key on. For more information about defining a CKDS or PKDS, see z/OS Cryptographic Services ICSF System Programmer's Guide.

Optionally, you may:

Create an additional VSAM data set to serve as a backup of the new, reenciphered, KDS. This data set must be allocated and empty and must contain the same data set attributes as the active KDS you are performing the coordinated change master key on.
If you are planning to use the archive option, which is described next, determine a VSAM data set name to use for the archived KDS data set. This data set must not be allocated and must not exist on the system. For more information about defining a CKDS or PKDS, see z/OS Cryptographic Services ICSF System Programmer's Guide.

To reencipher the KDS and change the master key:

Enter option 2, KDS MANAGEMENT, on the ICSF Primary Menu panel to access the Master key set or change, KDS processing panel.
The CSFMKM10 — Key Data Set Management panel is displayed.
- Enter option 1 for CKDS MK Management and the CKDS Management panel appears: CSFMKM20 — CKDS Management panel
- Enter option 2 for PKDS MK Management and the PKDS Management panel appears: CSFMKM30 — PKDS Management panel
Enter option 5 for COORDINATED CKDS CHANGE MK option on the CKDS or the PKDS Management menu panel and the Coordinated KDS Change master key panel appears:
```
 CSFCRC20 ----------- ICSF - Coordinated KDS change master key ------------------
                                                                               
To perform a coordinated KDS change master key, enter the KDS names below 
and optionally select the rename option.                                       
                                                                               
    KDS Type ===> CKDS                                                         
                                                                               
  Active KDS ===> 'CSF.CKDS'                                       
                                                                               
     New KDS ===>                                                              
                                                                               
          Rename Active to Archived and New to Active (Y/N) ===> N             
                                                                               
          Archived KDS ===>                                                    
                                                                               
          Create a backup of the reenciphered KDS (Y/N) ===> N                 
                                                                               
          Backup KDS ===>                                                      
                                                                               
Press ENTER to perform a coordinated KDS change master key.                    
Press END to exit to the previous menu.                                        
```
In this example, CKDS was selected to perform the coordinated change master key. The KDS type is displayed in the KDS Type field. The active KDS is displayed in the Active KDS field.
1. Enter the name of the new KDS in the New KDS field. This must be an empty and allocated VSAM data set containing the same data set attributes as the active KDS. The reenciphered keys are placed into this new data set to create the new KDS.
2. Decide whether you want to have the new KDS renamed to the match the name of the current active KDS. Having the new KDS renamed to match the name of the current active KDS simplifies KDS administration because you will not need to update the ICSF Options Data Set with the name of the new data set after the coordinated change master key completes.
  - If you would like to have the new KDS renamed to match the name of the current active KDS:
    1. Type Y in the Rename Active to Archived and the New to Active ( Y / N ) field.
    2. Enter the name under which the currently active KDS will be archived in the Archived KDS field. This must be a VSAM data set name that is not allocated and does not exist on the system.
  - If you do not want to have the new KDS renamed to match the name of the current active KDS, type N in the Rename Active to Archived and the New to Active ( Y / N ) field. Remember to change the name of the KDS in the Installation Options Data Set as described in the z/OS Cryptographic Services ICSF System Programmer's Guide. The KDS name must be changed in each cluster member's Installation Options Data Set after the coordinated KDS change master key function completes successfully. If the Installation Options Data Set is updated with a new KDS name and the coordinated change master key function fails, ICSF might be configured with an invalid KDS the next time it is restarted.
3. Decide if you want to also create a backup copy of the newly enciphered KDS. This is an empty and allocated VSAM data set containing the same data set attributes as the active KDS. The reenciphered keys are placed into this data set to create the backup KDS.
Press ENTER to begin the coordinated change master key.
A confirmation panel will be displayed, prompting you to verify that you want to continue with the coordinated change master key. Verify that the information on this confirmation panel is correct. If it is, type Y in the confirmation field provided and press ENTER.
The coordinated change master key function will be executed. This function will verify that all ICSF instances sharing the same active KDS are configured with the same New Master Key registers values. Additionally, it will verify that the KDS names specified for input are valid and are compatible with each other. The disk copy of the active KDS will be reenciphered under the new master keys to create the new KDS on disk and will create an in-storage copy of that new KDS. In a sysplex environment, the in-storage copy of the new KDS will be created for all ICSF instances that share the KDS.

The D ICSF,KDS and D ICSF,MKVPS commands display the date when the MKVP values were stored in the key data set. A benefit of using coordinated change master key is that the SMF record type 82 subtype 49 records written for the promotion of the new master keys report the same time stamp in the SMF time of event tag-length-value as displayed on the D ICSF commands. When the SMF records are formatted using the supplied formatting sample CSFSMFR, the record of the promotion of master keys for a master key change event can be found by searching on the MKVP date displayed on the D ICSF command. For examples, see Examples relating the MKVP date on D ICSF,MKVPS and D ICSF,KDS to the SMF Subtype 49 record in z/OS Cryptographic Services ICSF System Programmer's Guide.
Verify the dialog results and correct any indicated failures or unexpected results.