All I ever wanted to know about ICSF and data set encryption keys

z/OS systems have cryptographic processors, which can be used to offload expensive cryptographic operations. You can configure z/OS so if you generate a cryptographic key, you do not see the actual, clear text key (so it cannot easily be stolen). This is done by the cryptographic processors having a cryptographic key themselves, and any keys they emit, are encrypted with this hardware key. When you use your cryptographic key, it is passed to the cryptographic processors, which then decrypts the data using the hardware key, then uses your real cryptographic key.

ICSF provides an interface to do cryptography, use the cryptography processors and to mange cryptographic keys. Most z/OS user will ICSF capabilities without knowing about it.

ICSF works at the level of symmetric and asymmetric keys. You cannot use it to generate digital certificate, do TLS handshakes, nor do data set encryption (but data set encryption uses ICSF keys).

ICSF provides

• An ISPF interface to mange keys. You can list, define, delete etc keys through the panels
• A batch program CSFKGUP which can be used to so some of the key management. This acts on a data set. You need to tell ICSF to refresh the in-memory contents from the data set.
• An extensive set of API’s if you want to write your own application, for example to generate a key, or to encrypt some data. It is relatively easy to write Rexx programs to use the APIS. These APIs work on the active ICSF data sets. To use different data sets you need to change the ICSF configuration.

Having spent a few weeks trying to use it I feel “how to” information is missing. I tried implementing data set encryption across disconnected system and found ICSF is missing some functions, for example batch program to export and import keys, and a batch program to securely generate shared keys on different systems.

In this blog post, I’ve tried to fill in the holes in the documentation, and provide the missing batch utility programs.

I’ve written blogs posts on

• What are the ICSF bits?
• Using ICSF within a single image or sysplex.
• Using ICSF in a multi system environment.
• Setting up ICSF on z/OS.
• Generating ICSF keys using Diffie-Hellman.
• Using ICSF API function CSNBKGN2 to generate keys.
• What ICSF APIs do I need to use for AES CIPHER keys.
• Testing multi system ICSF on a single system.
• Setting up ICSF security for commands and APIs.
• Setting up ICSF security for access to keys.

I’ve put my utilities and sample code on Github.