What are the ICSF bits?

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.