I struggled for a while to understand the different parts of ICSF.

Definition of terms

You use a symmetric key for encrypting and decrypting data. You use the same key for encryption and decryption.

An asymmetric key has two parts. You encrypt with one, and decrypt with the other. If you encrypt with a key, you cannot use your key to decrypt it. You need the other part. You pick one part, and keep it secure – this is called the private key. The other part you can make this available to every one – the public key.

A certificate is a collecting of information. It contains a public key, and information about the owner of the certificate. I think of a certificate as a paper envelope in which you put the public key, they owner information, and other information, such as validity dates.

Hardware encryption. These days the calculations for encryption can be offloaded to special cryptographic hardware.

Cryptographic keys can be stored in hardware. The hardware can have a cryptographic key, which can be used to encrypt data before storing it in the hardware.

You can request the hardware to extract the data, and encrypt it with another key. This way the encryption key is never seen outside of the hardware.

ICSF provides an API to use z/OS hardware cryptographic functions, and some facilities to mange the keys.

ICSF

A symmetric key can have different algorithms. Typically RSA and AES. RSA came first, but AES is considered better as it takes more work to crack, and uses less resources when encrypting and decrypting data.

With ICSF, the symmetric keys are stored (encrypted) within the ICSF CKDS database. The keys are referenced to using tokens. You can have:

• A null token – used as place holder.
• A fixed length token, this is an old format token.
• A variable length token. As cryptography developed over time, all the information could not be stored in a fixed length, and so variable length tokens were introduced.

With ICSF, Asymmetric keys are called PKA (Public Key algorithms).

An asymmetric key can have different algorithms. Typically RSA, Elliptic Curve (EC), and various Crystal methods (these are based on complex calculations based on crystal lattices).

The asymmetric keys are stored (encrypted) within the ICSF PKDS databases. The keys are referenced to using tokens.

As with symmetric keys, the early asymmetric tokens were a fixed length. As cryptography developed, variable length tokens were introduced.

Symmetric ciphers in more depth

ICSF has two forms of symmetric cipher for encrypting user data

• DATA – I think of this as version 1. The key value can be extracted as cleartext – this is not very secure.
• CIPHER – I think this as version 2. The key value is always encrypted – either within ICSF, encrypted on the hardware, or with a transmission key.

Best practice is to use CIPHER instead of DATA. There is an older API function for generating the DATA keys, and a newer API function (CSNBKTB2) for the CIPHER keys. The newer function has more capability. For example, you can specify options that allow/prohibit exporting the key, and which encryption modes can be used, such as cipher block chaining(CBC).

• AES has one type of cipher: CIPHER. This can be used for data set encryption and in encrypt API (CSNBENC), and the decrypt API (CSNBDEC).
• DES has three types of cipher
  • DATA which can be used to encrypt and decrypt. This can be used for data set encryption and in encrypt API (CSNBENC), and the decrypt API (CSNBDEC).
  • ENCIPHER. This can be used in the encrypt data API (CSNBENC).
  • DECIPHER. This can be used in the decrypt data API (CSNBDEC).

• To use the ENCIPHER function you need a DATA, CIPHER or ENCIPHER key
• To use the DECIPHER function you need a DATA, CIPHER or DECIPHER key
• To use data set encryption you need DATA or CIPHER (because you need to do encryption and decryption).

Generating symmetric keys

You can use the ISPF panel interface.

For example, to create a symmetric key; from the ICSF main page select options:

• 5 UTILITY
• 5 CKDS KEYS – Manage keys in the CKDS
• 8 Generate AES CIPHER keys

You specify the name of the key, the AES key bit length, which encryption mode and if it can be exported from the hardware (XPRTCPAC).

The ISPF panels provide defaults. You can see the values by using the ISPF interface to display entries in the CKDS. For example

Key usage:ENCRYPT and DECRYPT, and ANY-MODE

Key management: gives XPRTCPAC and other keys. For example XPRT-AES says the key can be exported and encrypted using an AES Key Exporting Key.

Use the CSFKGUP batch interface.

The ICSF administrators guide gives details of the utility. It uses data sets (which may not be the active ones). You need to tell ICSF to refresh the in-memory information after the data sets have been updated.

For example

//IBMICSF  JOB 1,MSGCLASS=H 
//  SET CKDS=COLIN.SCSFCKDS 
//KGUP   EXEC PGM=CSFKGUP,PARM=('SSM') 
//CSFCKDS DD DISP=OLD,DSN=&CKDS 
//CSFIN DD *,LRECL=80 
...
//CSFDIAG DD SYSOUT=*,LRECL=133 
//CSFKEYS  DD DSN=COLIN.CSFKEYS,DISP=SHR 
//CSFSTMNT DD SYSOUT=*,LRECL=80 
//* REFRESH THE IN MEMORY DATA 
//REFRESH  EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH' 
// 

The statements in CSFIN are like

DELETE TYPE(CIPHER) LABEL(AESCIPHER) 
ADD TYPE(CIPHER  ) ALGORITHM(AES) LENGTH(32), 
 LAB(AESCIPHER) 

You can specify values for KEYUSAGE and KEYMGMT for example

KEYUSAGE(ANY-MODE) KEYMGMT(XPRTCPAC).

CSFKGUP seems to provide the same capability as the ISPF interface.

If you use CSFKGUP you need to issue a program to refresh the in memory information from the updated CKDS and TKDS data sets.

How is ICSF configured?

ICSF is started as a started task, so uses JCL in the SYS1.PROCLIB concatenation. I have member CSF in USER.Z31A.PROCLIB.

//CSF  PROC PRM=CP 
//CSF  EXEC PGM=CSFINIT,PARM=&PRM,REGION=0M,TIME=1440,MEMLIMIT=NOLIMIT 

The parameters are selected when the procedure is started. For example

S CSF,PRM=C2

The parameters come from member CSFPRMxx in the parmlib concatenation. My default parameters are in USER.Z31A.PARMLIB(CSFPRMCP)

CKDSN(COLIN.SCSFCKDS)                   
PKDSN(COLIN.SCSFPKDS)                   
TKDSN(COLIN.SCSFTKDS)                   
DOMAIN(0)                               
SSM(YES)                                
KEYARCHMSG(YES)                         

To use different data sets, you need to stop ICSF, and restart it with a different configuration member, specifying different data set names.

This blog post describes using ICSF within one system. This could be a sysplex if all systems use the same ICSF data sets. It gives some guidance on setting up your environment, and some implications of your decisions.

• Introduction
• Planning
• Creating keys
• Setting up data set encryption
• Afterthoughts

For some guidance on defining keys for Data Set Encryption see here(how many keys?). For a deep dive on key management which talks about changing the keys on the ICSF data sets (key rotation) see here.

Introduction

This section gives some general information about using ICSF, keys and data set encryption.

• You set up a symmetric key for data set encryption.
• You can specify which key a data set should use, when the data set is created.
  • You can configure a RACF profile to specify the key name in the DFP information.
    • When you allocate a data set which uses this RACF profile, the key is extracted from the DFP information and used.
  • The data set must be SMS-managed extended format. (You can configure this either in JCL, or with SMS options)
  • You can specify the keylabel in the JCL
  • You can specify in the SMS Data class. With SMS you configure ACS with statements like if the data set attributes are … then use data class xxxx, which in turn has a data set encryption key specified.
• The key name is stored with in the catalog along with other SMS information.
• If you change the label in the RACF profile, any new dataset which get created get the updated label, existing data sets are unchanged.
• If you delete and recreate a key for a label, any data set which used the old label becomes unreadable.
• You can unload and reload a key using my programs in EASYICSF on Github. ICSF does not provide this capability. When you define a key, you might unload it, and archive it away. Then, if the key gets deleted by accident, you can then recover by reloading it.
• Keys stored by ICSF are encrypted before they are stored in the ICSF data set. The master encryption key for these data sets can be stored in the cryptographic hardware. If someone steals the ICSF data sets, they cannot use them, unless they have the master key as well.
• You can get ICSF to use a new master password. It will take each entry in the ICSF data set, decrypt it with the old key, encrypt it with the new key, and store it back in (a new) data set. This is known as key rotation. (This is a strange use of the term rotation because there is no rotation, you just change the key.)
• If you want to use a new key for a data set. You have to copy the contents of the data set to a new data set set up with the new key. You then rename the data set. You cannot just change the key.
• You can specify a start and end date for a key. The start date can be today’s or any date in the future. The end date is after the value (this means you cannot specify an end date, so it can not be used today.)
• If you want to stop a key from being used, you can set an archive flag on it. (If you delete it, any data sets using this key cannot be processed). By default the application using an archived key will fail. You can configure ICSF so that use of an archived key will work, and you get a message for the key on the ICSF joblog, and a record in SMF.
• You can control who can use keys by a RACF profile in class CSFKEYS. If you use CSF.CSFKEYS.CONDITIONAL.ACCESS.CONTROL you can restrict what functions userids can execute – and so prevent most people from being able delete keys.
• Copying data sets
  • If you use DFDSS backup, the encrypted data is backed up. When you restore it, it allocates a data set with the same encryption label. The intermediate file is not encrypted. You can still read the intermediate file and see the meta data – but the original file contents are still encrypted.
  • If you use IEBGENER to copy the data, if the output data set does not have an encryption label, the output data set is encrypted with the same key label as the input.
  • To specify a key label you can specify DSKEYLBL in JCL and in the TSO ALLOC command.
  • In an application
    • you can specify the key label using SVC 99 (dynamic allocation).
    • you cannot specify it using the C function fopen(). You will need to specify it in JCL and use DD:name to refer to the data set.
  • If you use other program, such as a ISPF edit or a C program, to read the file and write the contents out, by default the output file is not encrypted. The application sees the clear text, and the output is in clear text unless you have specified a key label for the output data set.

Planning

You need to consider how many keys you need. For example, one for all your data sets, or one per business function such as online banking, or stocks and shares.

Keys for some files, such as a database will be long lived – as long as the data base exists, or until you copy it with a new key. The data set may have been archived to tape, and could be recalled years later.

You need to plan who has access to the data set. For a DB2 data base data set, people will not normally need access to it, as the access is managed by DB2. The DB2 system userid will need access. Storage managers, responsible for backing up the data sets do not need access to the key, and access the encrypted data without decryption.

If someone has access to an encrypted data set, you need to ensure that any data set they create which may have sensitive information in it is also encrypted. This may mean reviewing userids and what they are used for. For example if you have a data set ENC.DATASET1 which userid COLIN can access, do you need to ensure that any data set that userid COLIN can create is encrypted?. This may mean data sets are encrypted which do not contain sensitive information. If userid COLIN can also create data sets beginning with SYS2 – you need to consider if all SYS2.* datasets need to be encrypted.

You might define a userid COLINE which can only access the encrypted data sets, and can only created data sets prefixed with COLINE – and these are all encrypted. Userid COLINE does not have access to general data sets, such as SYS1.PARMLIB.

For short lived data sets you could change the key every few months.

You need to consider backups and disaster recovery, and how your remote sites will use the datasets. The remote sites will need the same keys for the data sets, as the primary site.

Changing keys

As a general rule, you do not want to delete a key unless you are sure that is is not needed (including any data sets that may have been archived off the system). If you want to generate new keys periodically you may want to use a naming convention such as PAYROLL2024NOV, then generate a new key PAYROLL2025NOV, and update your definitions (or SMS).

Using keys

You can specify the encryption key to be used in

1. The RACF profile used for the data set. The value is in the DFP segment.
2. The JCL DSKEYLBL parameter on the DD statement.
3. In the SMS data class used for the data set. This can be specified in the DATACLAS parameter on the DD statement, or selected via the ACS(Automatic Class Selection) routine.

The key is used when the data set is allocated(created).

If you change the RACF profile, the updated label will be used next time a data set is created.

If people specify the key either by application on JCL (the DSKEYLBL option on the DD statement), changing the key name will mean changing the applications and JCL to use the new key.

An ACS routine has logic like

if the data set names begins with … , and has properties …. then use the following volumes…, make it this size…, and use the Data Class … which has the Data Set Key Label…)

If you change the Data Set Key Label in the Data class, the next time the Data Class is used, it will use the updated key. This is much simpler than trying to change JCL.

It looks like it is easier to use the RACF profile or SMS if you will be changing the data set encryption key.

Creating keys

• You can use the ICSF utility CSFKGUP to generate keys. The syntax is like ADD TYPE(CIPHER) LABEL(COLINKEY)…
• You can use the ISPF interface to define keys. From the main panel, options 5 UTILITY -> 5 CKDS KEYS, option 7 or 8 to define a symmetric key.
• You can use ISPF to generate statements for CSFKGUP. From the main panel option 8 KGUP – Key Generator Utility processes. This simplifies selecting the options. For example if you select the action to maintain (add) an entry, if you specify algorithm DES, it will display the valid key types for DES (eg CIPHER, DATA, ENCIPHER…). If you select algorithm AES, it will display the valid key types for AES ( eg CIPHER, DATA, EXPORTER…). If you use this method, you may still have to edit the statements manually, because not all the required parameters are specified, see below.

For some keys you need to have a RACF profile defined for the label name. For example

RDEFINE CSFKEYS DES5 UACC(NONE) –
ICSF(SYMCPACFWRAP(YES) SYMCPACFRET(YES))

This seems to be a strange way of storing this information.

Setting up data set encryption

Best practices.

Use definition like

ADD ALGORITHM(AES) TYPE(CIPHER) KEYUSAGE(ANY-MODE) LENGTH(32), 
KEYMGT(XPRTCPAC)LABEL(COLINCIPHER2 ) 

Where

• ALGORITHM(AES) is better than ALGORITHM(DES). It is harder to crack, and uses less CPU.
• TYPE(CIPHER) is better than TYPE(DATA).
• KEYUSAGE(ANY-MODE) is needed for data set encryption with AES.
• LENGTH(32) is the longest and strongest AES key size.
• KEYMGT(XPRTCPAC) is needed for data set encryption.
• LABEL(COLINCIPHER2 ) you specify your label.

If you use the ISPF panels to generate the key, you can specify all of the parameters. If you use the ISPF interface and 8 KGUP – Key Generator Utility processes. This does not specify create KEYUSAGE and KEYMGT values, which will have to be entered manually.

Afterthoughts

You need to backup the ICSF data sets.

If you need to use a (restored) data set with a different name, you will need to restart ICSF with a different parmlib member containing the different names.

ICSF does not provide a way of copying between ICSF data sets, but you can use UNLOAD and RELOAD programs in my EASYICSF on Github which allows you to copy a key from one ICSF data set to an intermediate data set, then reload it into a different,or the same, ICSF data set.

You should have a process, which you have tested, for replacing keys which may be been exposed. This may cause a long (hours) outage, so you need to have JCL and definitions written before you need them.

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.