IBM Crypto Education Community - Group home

Archiving key tokens in ICSF


Authors: Gregg Arquero, John Craig

There may be instances due to compliance requirements or internal processes where a key should be rotated out of active use. In some cases, it is not fully known all the places where that key may have been used to encrypt, sign, or MAC data and deleting the key would result in either data loss or the inability to verify the authenticity of the data. Key Archiving is a useful mechanism for removing a key from active use without deleting it. In the previous article, we mentioned that NIST was planning to deprecate the use of the three-key TDEA algorithm at the end of 2023 but will still permit its use for decrypting legacy data. This is a prime example of when key archiving would be appropriate. 

Before you can start archiving keys, you must ensure that your Key Data Sets (KDS) are in KDSR or KDSRL format. You can check the format of your existing key data sets with the D ICSF,KDS operator command.

For example:

SY1 d icsf,kds

SY1 CSFM668I 11.17.00 ICSF KDS 792



DES MKVP date=Unknown

AES MKVP date=Unknown



RSA MKVP date=Unknown

ECC MKVP date=Unknown



P11 MKVP date=Unknown

To convert your existing non-KDSR KDS over to KDSR format, you can use either coordinated conversion utility or the Coordinated KDS Administion (CSFCRC and CSFCRC6) callable service. Once your KDS is in KDSR or KDSRL format, you are ready to start archiving keys.

There are two ways to archive a key. The first method is with the CKDS Keys Utility. Navigate to the key record to be archived and toggle the archived flag setting. In the first image below, the ‘Archived flag’ setting is changed to ‘TRUE’ and action 1, modify a field with a new value, is performed. In the second image, we can see the state of the key record has been changed to ‘Archived'.

Image 1: CKDS Keys Utility, toggle archived flag setting

Image 2: CKDS Keys Utility, after archived flag has been modified

The second method is with Key Data Set Metadata Write (CSFKDMW and CSFKDMW6) callable service. With this service you can programmatically add, delete, or modify metadata of a set of records in the active CKDS, PKDS, or TKDS. This REXX sample shows how to update the archive flag for CKDS records.

Once you’ve archived your keys, the CSF.KDS.KEY.ARCHIVE.DATA.DECRYPT XFACILIT class profile can be defined to allow archived keys to be used for decrypting existing legacy data. When defined, service requests for data encryption with an archived key will fail and return RC 8 / RSN D5E. Service requests for data decryption will succeed and an SMF 82 audit record is logged. This control would enable compliance with NIST’s guidance on TDEA in which encryption of new data would be disallowed and decryption of legacy data would be allowed.

Now that you've archived your legacy keys, you can begin planning the transition of your legacy encrypted data from DES to AES. In the next article, we will cover which ICSF services can reencrypt your data without it ever appearing in the clear.