Using ICSF within a single image or sysplex discussed setting up ICSF in a single environment, where systems can share the ICSF datasets.
This blog post is when you have multiple systems which do not share the ICSF data sets.
You have some encrypted data sets which you have sent to your backup system. How do you get the ICSF keys to your backup site? I will focus on using AES CIPHER keys because AES is recommended over DES keys; and CIPHER keys are recommended over DATA keys.
The challenge of using ICSF in a multi system environment where the ICSF data sets are not shared, is setting up the first keys. This is not easy as ICSF does not provide all the functionality to do this.
If your systems have the same hardware key, you can unload and reload a key using my programs in EASYICSF on Github. You unload the key (encrypted with the hardware key) to a data set, send the data set to the remote system, and reload the key.
If your systems do not use the same hardware key, you can fairly easily set up the keys for use between systems if you can accept some clear text key value sharing.
If your systems do not use the same hardware key, the most secure way of setting up keys is where the key value is never in clear text, and so cannot be copied or used in an authorised way. This has many steps, and I’ll cover this in another blog post (Generating ICSF keys using Diffie-Hellman).
If you want to encrypt a key to send to a remote site, ICSF provides Key Encryption Key (KEK) technology. Once they KEK has been set up you can export a key from the local system, encrypting it with an exporter KEK. Send the encrypted data to the remote site, and use the matching KEK to import it. At no point is the clear text version of the key exposed. I think of a KEK as an asymmetric key for data. Having the exporter KEK does not mean you can decrypt the data.
You need to have an exporter key to get from system A to system B, and an exporter key to get from system B to system A. If you specify the key value yourself these could be the same. If you let the system generate the key value, they will be different.
Once you have keys set up, you can use ICSF Key Encryption Key (KEK) to send keys securely to another system. The key phrase is “Once you have set up…”.
How long are keys needed for ?
A cipher key used in data set encryption is needed for as long as the data set using it is needed, so potentially many years. Deleting the key means the data set cannot be read.
When you create a KEK, you create both the exporter and importer at the same time. You cannot generate one from the other. A KEK is only used when transferring keys between systems. You could have a new KEK every week, with no impact. You just need to ensure you have at least another KEK to encrypt it.
How many KEK’s do I need?
If you have three systems, Production, Backup and Disaster Recovery (DR). You could define an exporter key on production, and the same importer key on Backup and DR. This might be easy to implement, but I think I would feel more comfortable with different KEKs:
- Exporter on Production and Importer on Backup,
- Exporter on Production and Importer on DR,
- Backup to DR
and the opposite; Exporter on Backup and Importer on Production etc.
I included the system names in the data set used to store the key. When I initially used the same name for all definitions, such as ‘COLIN.EXPORTED.KEK’, I found I was getting into a muddle, and had the wrong key in it.
To export and import AES CIPHER keys see export a key from CKDS into a data set so it can be imported on another system and import a key from a data set into the CKDS on Github. You could just use unload and reload a key using my programs in EASYICSF on Github!
Overview to creating keys in a multi system environment
- If the hardware keys are the same on each system, you can use UNLOAD and RELOAD programs in my EASYICSF on Github which allows you to copy the hardware encrypted key from one ICSF data set to an intermediate data set, then reload it into an ICSF data set. See here.
- You can generate data set encryption keys on each system using a cut and paste of the JCL. This is not very secure because the key value is visible in clear text. See here.
- Define Key Encrypting Keys for sending keys encrypted between systems. See here for detailed instructions.
- On the sender system define a temporary exporter key specifying the key value in clear text.
- On the receiving system(s) define the matching importer key using the same key values (cut and paste) and a small edit.
- Define a permanent exporter key letting the system securely generate the key value, and specify the temporary KEK to encrypt the importer key.
- Send the encrypted permanent importer KEK to the remote system.
- On the receiver systems use the temporary importer KEK to import the permanent key
- Delete the temporary KEK from each system.
- You now have KEKs on your system, and the window where there was clear text visible was small.
- Locally generate a secure data set encryption key, and export it to the remote systems as needed. See here.
- You generate a data set encryption key.
- For each system you want to send this key to you export it, using the exporter KEK for that system.
- If you want to send the key at a later date, you just export the key using the appropriate KEK.
- Generating secure data set encryption keys, both local and encrypted with a KEK
- ICSF has a utility CSFKGUP which, in one request, can generate a key for use locally, and export it using an exporter KEK.
- This does not feel a very good solution to me.
- If you want to send the key to multiple systems, you need to use the same KEK for all systems.
- If, at a later date, you want to send the key to another system you have to export it (see above). It is easier just to export it anyway.
These may look relatively simple – but ICSF does not provide a utility to export and import the keys. You can write your own C or REXX program, or use the ones I have written. See export a key and import a key in EasyICSF on Gitub.
Detailed instructions
Use unload and reload.
This is based on unload and reload a key using my programs in EASYICSF on Github.
Unload
//IBMUNL JOB 'COLIN',CLASS=A,REGION=0M,COND=(4,LE) RESTART=RUN
//JOBLIB JCLLIB ORDER=(COLIN.ICSF.C,CBC.SCCNPRC)
//* COMPILE EXEC CCPROC,PROG=UNLOAD
//*
//*
// SET KEY='-key SECKEY2 '
// SET DB='-debug 8 '
// SET DB=' '
//RUN EXEC PGM=UNLOAD,REGION=0M,
// PARM='&KEY. &DB '
//STEPLIB DD DISP=SHR,DSN=COLIN.ICSFLOAD
//SYSPRINT DD SYSOUT=*,DCB=(LRECL=200)
//SYSOUT DD SYSOUT=*
//KEY DD DSN=COLIN.UNLOAD.AES,DISP=(OLD)
//* SPACE=(CYL,(1,1)),DCB=(LRECL=7000,RECFM=V)
Reload
//IBMRELOA JOB 'COLIN',CLASS=A,REGION=0M,COND=(4,LE) RESTART=RUN
//JOBLIB JCLLIB ORDER=(COLIN.ICSF.C,CBC.SCCNPRC)
//*OMPILE EXEC CCPROC,PROG=RELOAD
//*
//*
// SET DB='-debug 8 '
// SET KEY='-key SECKEY2 '
//RUN EXEC PGM=RELOAD,REGION=0M,
// PARM='&KEY. &DB '
//STEPLIB DD DISP=SHR,DSN=COLIN.ICSFLOAD
//SYSPRINT DD SYSOUT=*,DCB=(LRECL=200)
//SYSOUT DD SYSOUT=*
//KEY DD DSN=COLIN.UNLOAD.AES,DISP=(OLD)
An easy, not very secure method, for use in a proof of concept.
You can use JCL Like
//IBMICSF JOB 1,MSGCLASS=H
//STEP10 EXEC PGM=CSFKGUP
// SET CKDS=COLIN.SCSFCKDS
//CSFCKDS DD DISP=OLD,DSN=&CKDS
//CSFIN DD *,LRECL=80
ADD TYPE(CIPHER) ALGORITHM(AES),
KEYMGT(XPRTCPAC),
CLEAR,
KEY(0123456789ABCDEF,0123456789ABCDEF,
0123456789ABCDEF,0123456789ABCDEF),
LABEL(COLINCIPHERCLEAR ) ,
KEYUSAGE(ANY-MODE)
/*
//CSFDIAG DD SYSOUT=,LRECL=133 //CSFKEYS DD SYSOUT=,LRECL=1044
//CSFSTMNT DD SYSOUT=,LRECL=80 // REFRESH THE IN MEMORY DATA
//REFRESH EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH'
You run this on every system where you need the data set encryption key.
You need to specify for data se
- KEYMGT(XPRTCPAC),
- KEYUSAGE(ANY-MODE)
- KEY(….) You need to pick a set of random hexadecimal numbers.
You can run this job on all systems you need the data set encryption keys on, with no changes.
This is not secure because other people may be able to see the keys…
- You may have saved the JCL containing the key value (for future use) either in a data set or on paper
- If you ran this as a job, the values may be in the spool output. Depending on how you specified the output class.
- Copying the values to the remote system may get intercepted.
Defining KEKs
If you want to encrypt a key to send to a remote site ICSF provides Key Encryption Key (KEK) technology. Once the KEK has been set up you can export a key from the local system, encrypting it with an exporter KEK. Send the encrypted data to the remote site, and use the matching KEK to import it. At no point is the clear text version of the key exposed.
Generate a bootstrap KEK.
This bootstrap KEK is only used to set up a permanent KEK.
In a similar way to defining the data set encryption key above you can use
//IBMICSF JOB 1,MSGCLASS=H
//STEP10 EXEC PGM=CSFKGUP
// SET CKDS=COLIN.SCSFCKDS
//CSFCKDS DD DISP=OLD,DSN=&CKDS
//CSFIN DD *,LRECL=80
DELETE TYPE(EXPORTER) LABEL(TEMPATOB)
ADD LABEL(TEMPATOB)TYPE(EXPORTER) CLEAR ,
ALGORITHM(AES),
KEY(3123456789ABCDEF,0123456789ABCDEF)
/*
//CSFDIAG DD SYSOUT=*,LRECL=133
//* REFRESH THE IN MEMORY DATA
//REFRESH EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH'
On the remote system, use the same JCL except with TYPE(IMPORTER). You will, of course, use different hex values in the key to those I gave.
Generate the long term KEK.
//IBMICSF JOB 1,MSGCLASS=H
//STEP10 EXEC PGM=CSFKGUP
// SET CKDS=COLIN.SCSFCKDS
//CSFCKDS DD DISP=OLD,DSN=&CKDS
//* LENGTH(32) GENERATES A 256 BIT KEY
//CSFIN DD *,LRECL=80
ADD LABEL(ATOBPERM) TYPE(EXPORTER) ,
TRANSKEY(TEMPATOB) ,
ALGORITHM(AES) LENGTH(32)
/*
//CSFDIAG DD SYSOUT=*,LRECL=133
//CSFKEYS DD DSN=COLIN.CSFKEYS,DISP=OLD
//CSFSTMNT DD SYSOUT=*,LRECL=80
//* REFRESH THE IN MEMORY DATA
//REFRESH EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH'
This creates a key value, stores the exporter KEK in the local CKDS encrypted with the hardware keys. It encrypts the new importer KEK with the TEMPATOB KEK and stores it in the CSFKEYS dataset.
The layout of this CSFKEYS data set is:
- ATOBPERM the name of the object,
- IMPORTER you need this sort of key to import it,
- ATOB this is the KEK name used to encrypt it
- The key for ATOBPERM with the key value encrypted. This is a hexadecimal value.
Knowing the information in the CSFKEYS data set you can import the key into the CKDS on the remote system, using the TEMPATOB importer key.
ICSF does not provide a utility for this. You can write some REXX code, or you can use my programs. See import a key from a data set into the CKDS.
Delete the temporary KEK
You can use the JCL
//IBMICSF JOB 1,MSGCLASS=H
//STEP10 EXEC PGM=CSFKGUP
// SET CKDS=COLIN.SCSFCKDS
//CSFCKDS DD DISP=OLD,DSN=&CKDS
//CSFIN DD *,LRECL=80
DELETE TYPE(EXPORTER) LABEL(TEMPATOB)
/*
//CSFDIAG DD SYSOUT=*,LRECL=133
//CSFKEYS DD DUMMY
//CSFSTMNT DD DUMMY
//* REFRESH THE IN MEMORY DATA
//REFRESH EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH'
Locally generate a secure data set encryption key
If you do not have a data set encryption key, use JCL like
Securely generate data set encryption keys.
//IBMDSENC JOB 1,MSGCLASS=H
//STEP0 EXEC PGM=CSFKGUP
//*
// SET CKDS=COLIN.SCSFCKDS
//CSFCKDS DD DISP=OLD,DSN=&CKDS
//* LENGTH(32) GENERATES A 256 BIT KEY
//CSFIN DD *,LRECL=80
ADD TYPE(CIPHER) ALGORITHM(AES) LENGTH(32),
LABEL(DSENCRYPTION),
KEYMGT(XPRTCPAC),
KEYUSAGE(ANY-MODE)
/*
//CSFDIAG DD SYSOUT=*,LRECL=133
//CSFKEYS DD DUMMY
//CSFSTMNT DD DUMMY
//* REFRESH THE IN MEMORY DATA
//REFRESH EXEC PGM=CSFEUTIL,PARM='&CKDS,REFRESH'
//
You can then send the CSFKEYS data set to the remote site, and import it using the ATOBPERM importer key. See import a key from a data set into the CKDS on Github.
Using keys across systems
You can only use keys which are within their validity dates: crypto-period start date and
cypto-period end date.
When you import a key, meta data from the original site is not included, so you might need to specify start date, stop date, archive flags etc. See set meta data attributes on Github.
ColinPaice 