Callable Services for Dynamic CKDS Update

ICSF provides the dynamic CKDS update services that allow applications to directly manipulate both the DASD copy and in-storage copy of the current CKDS.

Note:

Applications using the dynamic CKDS update callable services can run concurrently with other operations that affect the CKDS, such as KGUP, CKDS conversion, REFRESH, and dynamic master key change. An operation can fail if it needs exclusive or shared access to the same DASD copy of the CKDS that is held shared or exclusive by another operation. ICSF provides serialization to prevent data loss from attempts at concurrent access, but your installation is responsible for the effective management of concurrent use of competing operations. Consult your system administrator or system programmer for your installation guidelines.

The syntax of the CKDS key record create, CKDS key record read, and CKDS key record write services is identical with the same services provided by the Transaction Security System security application programming interface. Key management applications that use these common interface verbs can run on both systems without change.

Additional versions of CKDS key record create, CKDS key record read, and CKDS key record write (introduced in HCR7780) must be used for variable-length key tokens. These are the CKDS Key Record Create2, CKDS Key Record Read2, and CKDS Key Record Write2 callable services. These services also support existing DES and AES tokens.

CKDS Key Record Create Callable Service (CSNBKRC and CSNEKRC)

This service accepts a key label and creates a null key record in both the DASD copy and in-storage copy of the CKDS. The record contains a key token set to binary zeros and is identified by the key label passed in the call statement. The key label must be unique.

Prior to updating a key record using either the dynamic CKDS update services or KGUP, that record must already exist in the CKDS. You can use either the CKDS key record create service, KGUP, or your key entry hardware to create the initial record in the CKDS.

CKDS Key Record Create2 Callable Service (CSNBKRC2 and CSNEKRC2)

This service accepts a key label and optionally, a symmetric key token, and creates a key record in both the DASD copy and in-storage copy of the CKDS. The record contains the supplied key token or a null key token and is identified by the key label passed in the call statement. The key label must be unique.

This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens.

CKDS Key Record Delete Callable Service (CSNBKRD and CSNEKRD)

This service accepts a unique key label and deletes the associated key record from both the in-storage and DASD copies of the CKDS. This service deletes the entire record, including the key label from the CKDS.

CKDS Key Record Read Callable Service (CSNBKRR and CSNEKRR)

This service copies an internal key token from the in-storage CKDS to the application storage, where it may be used directly in other cryptographic services. Key labels specified with this service must be unique.

CKDS Key Record Read2 Callable Service (CSNBKRR2 and CSNEKRR2)

This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens.

CKDS Key Record Write Callable Service (CSNBKRW and CSNEKRW)

This service accepts an internal key token and a label and writes the key token to the CKDS record identified by the key label. The key label must be unique. Application calls to this service write the key token to both the DASD copy and in-storage copy of the CKDS, so the record must already exist in both copies of the CKDS.

CKDS Key Record Write2 Callable Service (CSNBKRW2 and CSNEKRW2)

This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens.

Coordinated KDS Administration Callable Service (CSFCRC and CSFCRC6)

This service performs a dynamic CKDS refresh or a dynamic CKDS reencipher operation. This callable service performs the refresh or reencipher operation while allowing applications to update the CKDS. In a sysplex environment, this callable service enables an application to perform a coordinated sysplex-wide refresh or reencipher operation from a single ICSF instance.