How do I ensure an easy hardware migration of my PPINIT-generated cryptographic master keys? (ICSF)

Steps

1. To generate a list of MKVPs from a provided passphrase, download the DHPPKEYS exec from the following link (https://www.ibm.com/support/pages/node/6354311) and enter your passphrase. Take note of the outputted MKVP for each master key type.  

2. Issue the following command to view your KDS header records. Note the CKDS contains a header record for DES and AES. The PKDS contains a header record for RSA and ECC. Identify the MKVP values: 

•  TSO PRINT IDS('your-current-ckds') COUNT(1) 
  • View offsets +6C for DES MKVP (8 bytes) and +7C for AES MKVP (8 bytes) 
• TSO PRINT IDS('your-current-pkds') COUNT(1) 
  • View offsets +7C for RSA MKVP(16 bytes) and +8C for ECC MKVP (8 bytes) 

Compare the MKVPs to the values derived in Step 1 from the DHPPKEYS exec.

Use the following doc links for more help identifying the MKVP for each Master Key type found in the CKDS and PKDS headers.

• CKDS Header Record Format (DES and AES Master Key Verification Pattern): 
  • http://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.csfb200/csf2b200177.htm 
• PKDS Header Record Format (RSA Hash Pattern and ECC Verification Pattern): 
  • http://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.csfb200/csf2b200184.htm 

3A. If none of your MKVPs match, the passphrase you are attempting to use is NOT the passphrase originally used to initialize the CKDS/PKDS pointed to from your ICSF options data set. Your active KDS names are identified in the ICSF Administrative Control Panel (Option 4).  

3B. If a subset of MKVPs match, but other MKVPs do not match, this likely indicates that you have manually added the nonmatching master keys outside of the PPINIT process. The master keys entered manually outside of PPINIT are NOT related to your PPINIT passphrase.

 4. Your remediation options would be to either:  

 4A. Find and use the correct passphrase, or 

4B. Supplement the matching master key parts derived from your passphrase (from DHPPKEYS output) with your known manually generated master key parts. Use master key part load instead of PPINIT to load all master keys onto the target hardware. Detailed steps:

•  On the new LPAR, load the DES, AES, RSA, and ECC master key parts by choosing E next to all crypto coprocessors listed in your Coprocessor Management Panel. 
•  ICSF panel option 2 “KDS Management” followed by option 4 “Set MK” activates your master keys. 
• Confirm in ICSF Coprocessor Management Panel (Option 1) that all 4 master key types now show an “A” for ACTIVE.  
• Further details can be found at this link: https://www.ibm.com/docs/en/zos/2.5.0?topic=mcmk-reentering-master-keys-when-they-have-been-cleared

Or,  

4C. Perform a master key change to a new set of master key values from an LPAR still actively using these KDSes.  Derive the new set of master key values by following the procedure outlined below.  

NOTE that PPINIT cannot be used during master key change.  

To accomplish step 4C, use the following steps: 

1. Allocate a new CKDS and PKDS.  

New CKDS: https://www.ibm.com/docs/en/zos/2.5.0?topic=ckds-steps-create 

New PKDS: https://www.ibm.com/docs/en/zos/2.5.0?topic=pkds-icsf-system-resource-planning 

2. Review the “Entering Master Key Parts” section (and subsections) of the ICSF Administrator’s Guide to generate new master key parts for all 4 master key types (DES, AES, RSA, and ECC): https://www.ibm.com/docs/en/zos/2.5.0?topic=keys-entering-master-key-parts 

3. Review the “Steps for reenciphering the CKDS and performing a local symmetric master key change” section of the ICSF Administrator’s Guide. Follow the instructions through step 5 within the link: https://www.ibm.com/docs/en/zos/2.5.0?topic=smkc-steps-reenciphering-ckds-performing-local-symmetric-master-key-change 

4. Review the “Steps for reenciphering the PKDS and performing a local asymmetric master key change” section of the ICSF Administrator’s Guide. Follow the instructions through step 5 within the link: https://www.ibm.com/docs/en/zos/2.5.0?topic=amkp-steps-reenciphering-pkds-performing-local-asymmetric-master-key-change 

5. Move those newly reenciphered data sets to the new LPAR, point to them from within the ICSF options data set, and start ICSF. Ignore CSFM137E error messages on ICSF startup. The failure messages are expected because we have not entered the matching master key parts.

6. On the new LPAR, enter the DES, AES, RSA, and ECC master key parts from Step 2. 

7. ICSF panel option 2 “KDS Management” followed by option 4 “Set MK” activates your master keys. 

8. Confirm in ICSF Coprocessor Management Panel (Option 1) that all 4 master key types now show an “A” for ACTIVE.