This is another post in the series of “One Minute MVS” which aims to give the basics you need to be able to get started with a topic.
The IBM documentation says: ICSF provides support for
- The ANSI Data Encryption Algorithm (DES) and Advanced Encryption Standard (AES) encryption and decryption
- DES key management and transport
- AES key management and transport
- Financial services including PINs, payment card industry transactions and ATMs
- Public key operations including key generation, digital signatures and wrapping symmetric keys for transport
- MAC and hash generation
- Acceleration of handshake and frame encryption for SSL
- PKCS #11 API
which has too many buzz words for me.
The manual Getting Started with z/OS Data Set Encryption is a very useful book.
My interpretation of what ICSF is:
ICSF…
- Can create and store Public and Private certificates (as used in SSL and TLS). RACF can store its certificates in ICSF.
- Can store symmetric keys used to encrypt data – such as data sets. Note: if you are using TLS the actual encryption of data over the network is done with a symmetric key.
- Mange the hardware, tamper proof, keystores provided with z hardware. (You have to access the physical z machine to enter the master cryptographic keys).
- To check credit card PIN number and other checks.
- You can configure ICSF in a group of datasets, and switch to a different set.
ICSF facilities
ICSF has
- A callable services API to allow you to call ICSF services from a program. There is a header file /usr/include/csfbext.h and SYS1.SIEAHDR.H which defines the function parameters.
- Some ISPF panels to help you mange the ICSF entities.
- Some batch command interfaces.
ICSF is not very usable
I found that ICSF was not very usable. For example
- The ISPF panels are not intuitive. You can update the ICSF datasets in batch. You then have to refresh the in-memory copy.
- For example, to refresh the CKDS data set and list it, using the ISPF panels for ICSF
- 2 KDS MANAGEMENT -> 1 CKDS MANAGEMENT -> 1 CKDS OPERATIONS -> 2 REFRESH – Activate an updated CKDS.
- Then PF3, 3 times.
- To list the contents
- 5 UTILITY -> 5 CKDS KEYS -> 1 List and manage all records
- I would have had a page for KDS, and had a refresh option, and a list option on the same page.
- For example, to refresh the CKDS data set and list it, using the ISPF panels for ICSF
- I expected to be able to use ICSF using commands. It looks like I have to write programs to use the API! Some REXX programs are available for a subset of the function.
- There is a lack of consistency. Two utilities doing similar things one has PARM=’REFESH,name’ the other has PARM=’name,REFRESH’. The utility for PKDS is CSFPUTIL. The utility for CKDS is CSFEUTIL.
It feels like ICSF has not yet been finished, more of an “Here are some API’s – good luck as you are on your own”, than a guide for the new user.
I’m writing some C programs to do some basic definitions, and pass parameters. I should not need to do this.
ICSF concepts
There are asymmetric keys such as private key and its public key. If you encrypt some text with a public key you need the private key to decrypt it. If you encrypt with the private key – you need the public key to decrypt it.
There are symmetric keys where the same key is used at each end. For example encrypt: change A to s, B to !; decrypt change s to A, ! to B.
Asymmetric keys are usually used in negotiating or sending a symmetric key to the remote end.
Symmetric keys are usually used to encrypt the payload. It is good practice to change the symmetric key periodically to make it harder for someone to break the cipher.
ICSF has
- PKDS (Public Key Data Set) for storing Private and Public Asymmetric keys.
- CKDS (Cryptographic Key Data Set) which is used to store Symmetric keys
- TKDS (Token Key Data Set). When you are using keys stored in the hardware cryptographic facility, you have a token to reference the data.
The data in these key data sets, may be encrypted, for example by the hardware cryptographic facility. You can configure ICSF so your keys are encrypted, and in normal operation they are not available in clear text, as they are encrypted by the tamper proof hardware, and are used within the hardware, where they are decrypted and used.
Keys can be in one of several state
- Active. The key can be used to process data. It is within its start and end dates (if present)
- Archive. The key cannot be used to process data. For example you have backed up an encrypted data set to tape. If you delete the key, the data cannot be processed. If they key is archived then it cannot be used. If you need to access the backed up dataset, you can change the status to Active for the duration of the work.
- Inactive – A key which has not been archived, and is outside of the start and end dates (if present).
- Pre-active – I cannot find what this is. It is mentioned in the ISPF panels.
Configuration
You can configure which ICSF data sets are current using, and other parameters via SYS1.PARMLIB(CSFPRMxx).
When you start the CSF procedure you specify the xx. For example in SYS1.PROCLIB concatenation member CSF,
//CSF PROC PRM=00
S CSF,PRM=CP
//CSF EXEC PGM=CSFINIT,PARM=&PRM,…..
You can use the SETICSF operator command to change some parameters for the duration of the CSF task.
You can use D ICSF, for example d ICSF,kds to give
CKDS CSF.SCSFCKDS FORMAT=KDSR SYSPLEX=N MKVPs=DES AES
PKDS CSF.SCSFPKDS FORMAT=VARIABLE SYSPLEX=N MKVPs=RSA ECC
No TKDS was provided.
To change use a different CSFPRMxx, you have to stop and restart CSF, specifying the CSFPRM suffix.
You need to plan your ICSF usage
You can set up data set encryption so when you create a data set, the data is automatically encrypted. You define a key and give it a label. If you delete the key, the data cannot be read. To be able to process the dataset you need RACF access to the dataset, and RACF access to the key.
The label is associated with the data set (so it you send the dataset to a remote system, it will still have the same label).
Most organisations say you much change your password periodically, typically every month. For similar reasons organisations say you should define a new key and use it, typically every month. This is called Key Rotation, where you roll over your key to a new value.
I could have a key with label ColinDSKey, and encrypt my data sets with it. I encrypt data set COLIN.AUG2021.LOG with this key. Next month if I create a new key and reuse the same label, I can encrypt the data set COLIN.SEPT2021.LOG and use the new key. However I will be unable to read COLIN.AUG2021.LOG, because ColinDSKey now has a new value.
I’ve seen presentations which say ” just re-encrypt all your datasets with the new key”. This sounds like a lot of work and a major disruption.
Another approach is to change the key label, for example ColinAug2021DSKey. When I generate a new key, it has a label ColinSept2021DSKey. I configure datasets to use the new label. Datasets with the old label can still be used, as long as the key exists. You can tell ICSF to archive the label (and key), so it cannot be used. If it is needed you make the key active, use the data set, and re archive the key.
To set the label for a data set, you can
- Specify it in JCL. So you may have to change your JCL every month, or use a symbolic such as the month and year.
// SET KEY=’OUTAESKEY’
//S4 EXEC PGM=IKJEFT01,REGION=0M
//SYSTSPRT DD DSN=IBMUSER.ENC,DISP=(MOD,CATLG),SPACE=(CYL,(1,1)),
// DSKEYLBL=&KEY,DSNTYPE=EXTREQ,DCB=(LRECL=132,BLKSIZE=3200)
//SYSTSIN DD *
LU *
/*
Use SMS and have rules to generate the label depending on your profile and the name of the data set.
Define a RACF profile for example ADDSD ‘PROTECT.*’ UACC(NONE) DFP(DATAKEY(AES2)) says for all datasets with a HLQ of PROTECT, then use key AES2.
When a dataset is allocated you get a message
IGD17150I DATA SET PROTECT.ENC IS ELIGIBLE FOR ACCESS METHOD ENCRYPTION. KEY LABEL IS (AES5)
You also need to think about encrypting your databases, which is another jump in complexity. As an old text book said “We’ll leave this as an exercise for the reader”.
To make the planning just a little! more complex; If you send an encrypted data set to another z/OS system, it will have the same label as when it was originally created, so you need the keys sent (securely) to the remote system for the data set to be processed, and coordinate naming conventions.
As the section header says You need to plan your ICSF usage. ICSF and data set encryption needs a lot of planning.
ColinPaice 
To be clear, the ISPF panels are not intended to provide access to all functionality. ICSF is first and foremost, a collection of APIs. We have added some dialogs and utilities to provide some helpful functions but never intend to make them a way to access the real power of ICSF.
To correct a few things:
ICSF stores keys not certificates (in general).
Physical access is not required to maintain the master keys.
The best way to update the CKDS, PKDS, or TKDS is using the callable services (for which you do not need a manual refresh afterward).
We provide APIs for all the functionality available in the panels (and MUCH more), such as refreshing datasets, changing the master keys across the entire sysplex, listing (and filtering) keys by label and attributes. With the coordinated operations, many of the steps are combined AND accessible via a callable service or a panel.
I will grant that ICSF is not finished. It will never be. However, it’s not for the reasons you state. It’s because there are constantly new technologies. ICSF is a set of APIs, so the utilities are utilitarian, never intended to cover every possible function.
Key rotation is a hot topic. While I see the usefulness of password rotation (intended for a human to remember), I see less of a need for dataset keys. Given the difficulty of reencryption, a very good way would be to periodically create a new label (and new key) and then update the covering profile with the new key label. This will ensure that newly created datasets will use a new key label (and key).
LikeLike
Eric,
Thank for your comments. Thanks for the updates… I’ll amend the post to reflect the comments.
If IBM is pushing encryption of all data sets. The only way I can see of doing this is to use ICSF to define the keys etc. Many people will be administrators and sysprogs who want to run commands to define certificates so the data sets can be encrypted. These people may never have written a C program. You cannot expect them to have to use the APIs, they expect a command interface. I dont think there are the commands available to define the keys for datasets or most scenarios. I haven’t looked at other areas.
Key rotation – I agree. In another (in progress) post, I say you might consider changing the key and label every month, and have the year and month as part of the key. I think with TLS channels on MQ, there is a recommendation to renew the TLS key every 1MB, or 100MB. I dont know what a good figure would be for data sets – every 1000 data sets perhaps?
Colin
LikeLike
We provide instructions and samples in our pubs on how to do create the keys. We also have tooling (like EKMF) to automate this process on top of the samples.
Key rotation is extremely dependent on the customer environment. There is no one-size-fits-all answer. There is nothing inherently wrong with using the same key for many different datasets, given how the dataset encryption is performed (XTS mode) vs the streaming modes used in TLS (GCM, as an example).
LikeLike
Hi,
The samples in the pubs are very simple. I was able to create a key so I could encrypt a dataset.
I tried to make a key so I could send a data set to another z/OS and have it readable. I could find no sample for this. I could not get it to work.
I had to edit the csfkeys files to get the hex string to use on the remote site.
I could not find any commands to use PKI to encrypt the key to send it across.
I wrote about Key Rotation to give some basic information on the concepts. I do not know if/when you should rotate your keys. All I know is that with MQSeries channels (sending data over TLS) you can specify when the TLS session creates a new session key. TLS provides this capability, so somewhere “the experts” must think this is important.
LikeLike