I’ve spent some time (weeks) exploring ICSF with the overall mission of sending an encrypted data set between two sites. Looking back it was like the saying when you’re up to your neck in alligators, it’s hard to remember that your initial objective was to drain the swamp.

I’ve explored many parts of ICSF. One area that confused me for a while was the use of Key Encrypting Keys, or Exporter and Importer keys, also known as transport keys. I’ll explain my current thoughts on it – bearing in mind these may not be 100% accurate.

If I want to encrypt data on one system, send the encrypted data to another system, and decrypt it on that system; the sender system needs encryption key, and the receiving system needs the decryption key.

Typically the data encryption is done using a symmetric key, where the same key is used to encrypt as decrypt. You can also use asymmetric keys where you encrypt with one key, but need a different key to decrypt it.

The first challenge is how to securely get the keys onto the systems.

• You cannot just email the symmetric key to the remote site, because bad people monitoring your email will be able to get the symmetric key.
• You could print the key, and sent it through the mail system, courier, or carrier pigeon to the remote site. This still means that bad guys could get the key (using a telephoto lens through a window, through the security cameras, or catch the pigeon).
• A secure way using a technique called Diffi-Hellman can be used to create the same symmetric key at each end. It uses private/public keys and an agreed seed. No sensitive data is sent between the two systems.

When setting up ICSF to use cross system, you need to set up keys for both A to B, and for B to A. You can use the same keys and seed for both, but the keys will be different.

If you are setting up several independent systems you will need keys A to B, B to A, A to C, C to A, B to C and C to B etc.

Setting up keys

You can set up a CIPHER key for encrypting data, and you can set up a MAC key for checking that what was sent is the same as what was received. (You hash the data, then encrypt the hashed value. Send the hash along with the data. If both ends do it, they should get the same answer!)

Decrypting and re-encypting

The keys are stored on disk in an encrypted format. The key for this is within the cryptographic hardware. If you want to send a key to another system, you need to encrypt it.

ICSF has a function in the hardware which says “here is some data encrypted with the hardware key, decrypt it, and re-encrypt it with this other key”. It has a matching function “here is some encrypted data, decrypt it, and re-encypt it with the hardware key”. This way the clear text of the key is never seen. To extract a key, you need to provide a key to re-encrypt it.

How to send the key to the remote system?

You have several choices depending on the level of security your enterprise has.

ICSF has a function to export a symmetric key using

• an RSA public key. At the remote end you need the private key to be able to decrypt it. This needs an RSA key size of at least 2048.
• an exporter key. At the remote end you need the matching importer key to decrypt it. Under the covers this is a symmetric (AES) key. The AES technique is faster, and “stronger” than RSA (it takes longer to break it). An AES 256 key is considered stronger than an RSA 4096 key.

I think of exporter and importer keys as a generalised public key and private key. The concept may be the same, but the implementation is very different.

The question “should I use RSA or Exporter/Importer” comes down to how secure do you want to be. If you export a key once a week the costs are small.

These keys used to encrypt keys, are known as key encrypting keys, and you often see KEK in the documentation.

What are the advantages of using an exporter and an importer key?

If you are using a symmetric key to encrypt your data, why is there exporter and importer keys, and not just one key?

If a purely symmetric key was used as a key encryption key, this means that if you are allowed to encrypt with it – you can decrypt with it. This then means you can decrypt other people’s data which used the same key.

By having a one key for encryption and another key for decryption you can isolate the authorities. If I have access to the exporter key, although I extract it and send it to my evil colleague at the remote end, they cannot use it to decrypt the data. If I have access to a symmetric key generated with Diffi-Hellman, the same key is used at each end, and so I could extract it and send it to my evil colleague who could use it.

Setting up my first importer or exporter key.

Use a pair of matching ECC public and private keys. The key type (eg Brain Pool) and key size must match. You use CSNBKTB2 to define a skeleton of type importer or exporter (or cipher). You then pass the skeleton into CSNDEDH along with the private and public keys. You can then use CSNBKRC2 to add it to the local CKDS.

You can do this at the remote end, just switch the public and private, and the importer to exporter. You do not need to send a key between the two systems.

Once you have defined your first exporter and importer key there is an alternative way of creating transport keys, using CSNBKGN2.

Alternative way of defining more transport keys.

There are three scenarios to consider when setting up transport keys between two systems.

• On system A create an exporter key for system A, and create an importer key system for system B. The importer key will need to be encrypted as it need to be send to the system B. The system A (local) exporter key can then use the key to export a (cipher or MAC) key. Then write this key to a file and send it to the other system. At system B, use the importer key to import this data into the system B’s key store.
• Do it from the “other end”. On system B create an importer key for system B, and create an exporter key for system A. This exporter key will need to be encrypted as it needs to be send to system A. Then write this key to a file and send it to the other system. At system A import it. System A can then use the new key to export a (cipher or MAC) key from that system, write it a file, and send it to system B which can import it.
• Define them on another system. On system C create an exporter key for system A, and an importer key for system B. These both need to be encrypted (and use different keys to encrypt each one). Send the encrypted keys to system A and system B. They can import the key, and send keys from system A to System B.

You use CSNBKGN2 to do this. I’ll only cover the first two cases.

You need to specify one of

• keytype1 = “IMPORTER”, keytype 2 = “EXPORTER” or
• keytype1 = “EXPORTER”, keytype 2 = “IMPORTER”

Use RULE = “OPEX ” where

• OP means store the first key in the local (OPerational) key store.
• EX means keytype 2 is to be exported. You have to specify an AES exporter key in the field key_encrypting_key_identifier_2.

Note. To export the key you already need an AES exporter key! This means you cannot create your first transport key with this method.

The output of this function is

1. a key which you can add to the local key store using CSNBKRC2,
2. a key which you can write to a file and send it to the remote system.

At the remote system you use CSNDSYI2 and the Importer key to import the data and re-encrypt it with the local key. Then use CSNBKRC2 to add it to the CKDS.

Which technique is better?

I think using a pair of matching ECC public and private keys and Diffie-Hellman is simpler, as it does not involve sending a file between systems. As this activity is done infrequently it may not matter.

Using DH many not be as secure as the alternative.

How many transport keys do I need?

You could create a new transport key every week if you wanted to. It is only used to send a data key to a remote system, so transient. When you have created a cipher key to encrypt and decrypt your data you need to keep this as long as you need access to the data. Once you recreate it – you are unable to read data sets with the previous key.

Depending on your security requirements you might want to have more than one transport key for data isolation. For example test data and production data have different keys.

You could use Enterprise Key Management Foundation (EKMF) from IBM to manage your keys

I’ve put some code on GITHUB which has C and REXX code which have a simpler interface to ICSF. The code examples hide a lot of the complexity.

For example to generate an AES CIPHER key the high level C code is

// build the skeleton for C=CIPHER ( could be E for exporter or I for IMporter
//  It returns the skeleton and its length 
rc = skeletonAES("C",& pToken,& lToken); 
if ( rc != 0 ) return rc; 

// Generate the key - passing the skeleton and returning the Token
// input the skeleton 
// output the token 
rc = GENAES2(pToken,&lToken); 
if ( rc != 0 ) return rc; 

// Add this to the CKDS                                                        
rc = addCKDS(pKey,pToken       ,lToken,pReplace); 
if ( rc != 0 ) return rc; 

printf("GENAES %s successful\n",pKey); 
return rc; 

To export an AES key

// Pass in the name of the AES key pKey
// the name of the encryption key (AES EXPORT or PKI) pKek
// Get back the blob  of data
rc =exportAES (pKey,pKek,&pData, &lData); 
 if (rc > 0 ) return rc; 
Write the blob to a file specified by dd
 rc = writeKey("dd:TOKEN",pData,lData); 

It gives in //SYSPRINT

Exists: CSNBKRR2 read AESDHE CKDS rc 0 rs 0 No error found

KEY:AESDHE:INTERNAL SYMMETRI EXPORTER CANAES

Exists: CSNBKRR2 read PKDS2 CKDS rc 8 rs 10012 Key not found
Exists: CSNDKRR read PKDS2 PKDS rc 0 rs 0 No error found .

KEK:PKDS2:INTERNAL PKA RSAPRIV 1024MEAO

RSA ¬AES:Rule:AES PKOAEP2 SHA-256 AES AESKW AES

ExpAESK:CSNDSYX rc 8 rs 2055 The RSA public key is too small to encrypt the DES key

Where…

• Exists: CSNBKRR2 read AESDHE CKDS rc 0 rs 0 No error found
  • It used the ICSF CSNBKRR2 to check AESDHE is in the CKDS
• KEY:AESDHE:INTERNAL SYMMETRI EXPORTER CANAES
  • It reports some info on the key. It is a Symmetric (AES) Exporter and can do AES processing
• Exists: CSNBKRR2 read PKDS2 CKDS rc 8 rs 10012 Key not found
  • This is ok — it looks in the CKDS first – but as this is a PKI – it will not be found
• Exists: CSNDKRR read PKDS2 PKDS rc 0 rs 0 No error found .
  • It is found in the PKDS
• KEK:PKDS2:INTERNAL PKA RSAPRIV 1024MEAO
  • This gives info about the Key Encryption Key. It is RSA and has a private key. The key size is 1024
• RSA ¬AES:Rule:AES PKOAEP2 SHA-256 AES AESKW AES
  • This is the rule used
• ExpAESK:CSNDSYX rc 8 rs 2055 The RSA public key is too small to encrypt the DES key
  • The size of the PKI key was too small.
  • As well as giving the return code and reason code, it gives the reason for some of the reason codes.
  • When I repeated this with a RSA key with a large enough key – it worked successfully.

There are also some macros such as

• isRSAPRIV… is this token (blob of data) an RSA private key?
• isEXPORTER … has this token been defined as an EXPORTER key?

I use these to check keys being used for operations to check that keys are valid for the ICSF operations.

The git hub code is work in progress. As I find problems I’m fixing them, but overall it should you what you can do with it.

As part of my scenario of encrypting a file and sending the encrypted file to another z/OS system, I struggled to understand why the documentation referred to transportation keys, key encryption keys (KEKs), import keys and export keys.

I found the subject very unclear. As I currently see it (and I’ve changed my view several times). You need the matching key on each system. If this is a symmetric key, it is the same key. If you are using PKI, they keys are asymmetric.

How do you get symmetric keys on both systems. I see there are two ways

1. Generate the same key on both systems This can be done using private and public keys, and a technique called Diffie-Hellman.
2. Generate a key on one system, and send it securely to the other system. For this you need to securely package the symmetric keys while they are in transit.

I was able to perform the setup and transfer a file securely to another system without the need for these additional keys. What was I missing?

The discussion about transport keys is for the second example where keys are sent over the network. You can use a CIPHER key to encrypt the key. It comes down to can I do it ? Yes. Should I do it ? No (well, maybe not, it depends on the scale of risk).

Within an IT environment the userid administration should be a different team to the systems programmers. This is to prevent any conflict of interest, fraud, and errors. The system programmers cannot give themselves access to sensitive data. In my small company (with just me in it) I have to do sysprog and userid administration.

IBM has similar guidelines for implementing cryptography. For example

• Separation of the roles and responsibilities. The people who create keys are different from the people who give access to the keys, and from the people who use the keys.
• Separation of encryption keys based on what they are used for. A key for encrypting datasets should not be used for encrypting a key to send to a remote system. If a data set encryption key is made public, the key-encryption-key should still be secure.

I could provide isolation of keys by having two keys, one is authorised only for data set encryption and the other authorised only for key encryption, but this separation may not be enough.

Creating exporter/importer using the API

I spent a couple of days trying to create an importer/exporter pair. I found one way of doing it – there may be other (more obscure) ways. It uses Diff-Hellman to create the same key on two sites without transferring sensitive material. I describe it here. It requires each side to have its own private key, and the public key of the other side.

There are three parts

• Generate a skeleton
• Use the skeleton, private key and public key to generate the Diffi-Hellman key
• store it in the key store

Exporter:Generate a skeleton

I used CSNBKTB2 with rules ‘AES ‘||’INTERNAL’||’EXPORTER’.

Exporter:Generate the DH Key

I have a “helper” rexx function which has parameters, private key name, public key name, the completed skeleton.

It used CSNDEDH with

• rule_array = ‘DERIV01 ‘||’KEY-AES ‘
• party_identifier (a string both sides agree) = ‘COLINS-id’
• KEK_key_identifier_length = 0. This is used when the private key is not stored in the PKDS, but passed in encrypted. I think of this as acting as a proxy. “Here is the private key to use – but it has been encrypted with the KEK which is in your local key store”. Setting the length to zero says the private key>is< in the local key store. Definitely an advanced topic!
• Name of side A’s private key in the PKDS
• Name of side B’s public key (from the other side) in the PKDS
• key_bit_length = 256.

It returns a blob encrypted with the local master key.

Exporter:addckds

This is another rexx helper. It takes the name of the key to generate, the encrypted blob, and “replace=Y|N”

This uses

• CSNBKRC2 to add to the CKDS
• if it gets record found, and needs to delete it,
  • it invokes delckds which uses CSNBKRD to delete it
  • it tries the add again

Importer ( on the remote system)

The steps are the same, except

• I used CSNBKTB2 with rules ‘AES ‘||’INTERNAL’||’IMPORTER’.
• Generate the DH key, you use the other keys, side B’s private, and side A’s public.

To export a key using exporter/importer

If you are using an AES exporter key to encrypt the data you need to use CSNDSYX with

• The name of the key you want to export
• The label of the AES exporter key
• rule_array = ‘AES ‘||’AESKW ‘

It returns a blob which you can write to a data set.

To import the key using exporter/importer

read the data into a buffer

Use CSNDSYI2 with

• rule_array = ‘AES ‘||’AESKW ‘
• the name of the importer key

It returns a blob of data.

Use the helper addckds passing the new label name, the blob of data, and replace=yes|no.

• This uses CSNBKRC2 to add the record, with rule_array = ”
• If the record exists and replace=yes then
  • use delckds with CSNBKRD and rule_array = ‘LABEL-DL’
  • re-add it

To export a key using PKI public/private keys

If you are using an PKI cipher key to encrypt the data you need to use CSNDSYX with

• The name of the key you want to export
• The label of the PKI public key
• rule_array = ‘AES ‘||’PKOAEP2 ‘

To import the key using pki private key

read the data into a buffer

Use CSNDSYI2 with

• rule_array = ‘AES ‘||’PKOAEP2 ‘, matching the exporter
• the name of the private key

It returns a blob of data.

Use the helper addckds passing the new label name, the blob of data, and replace=yes|no.

• This uses CSNBKRC2 to add the record, with rule_array = ”
• If the record exists and replace=yes then
  • use delckds with CSNBKRD and rule_array = ‘LABEL-DL’
  • re-add it

ICSF provides APIs and commands to manage cryptographic keys. For example to encrypt a datasets you need to define the key that will be used.

You can use Rexx to use the API’s and make your own commands.

There are some Rexx samples provided with ICSF, and there are others on the internet if you search for the API function and Rexx. These tend to be a large Rexx exec written to do one function.

You can use the power of Rexx to allow significant reuses of these execs, by having one Rexx exec to generate a key, another Rexx exec to add it to the keystore, another Rexx exec to export it, and another Rexx exec to import it.

Background

Rexx Address linkpgm facility

With TSO Rexx there is the “address linkpgm” command environment. This allows you to call z/OS functions with Rexx parameters.

For example

rc = 0
y=”Mystring”
z= 16
address linkpgm “ZOSPROG myrc Y Z”

generates the standard low level request

call ZOSPROG(addr(myrc),addr(y),addr(z));

It returns a variable ‘RC’ for example -3 if the program is not found, or the return code from the program.

Be careful not to specify ‘RC’ as a parameter as it may override it.

If does what you tell it. If you are expecting a string to be returned, then the variable you give it must be big enough to hold the data, it cannot allocate a bigger string.

If you want to create a variable of a fixed size you can use

token         = copies(’00’x,3500);

If you are passing a number or hex string, you have to convert it to the internal value.

For example on input

myInt = ‘00000000’x
mylen = C2D(length(“ABCDEFG”),4) /* the 4 says make field 4 (int) wide */

on output, convert the hex return code to a readable hex code

myrc = c2x(myrc)

To create an internal format length you can use either of

lToken = ‘00001964’x /* 6500 */
lToken = d2c(6500,4); /* of size 4*/

Passing parameters to external Rexx programs

You can call external Rexx programs and get a returned data. For example

with the program mycode

parse arg a,b
return 0 “COLINS”||A b||”xxx”

and call it using

zz = mycode(“AA”,”B”)
say zz
parse var zz rc x y
say rc
say x
say y

gives

0 COLINSAA Bxxx
0
COLINSAA
Bxxx

Using this you can have an external function which generates an AES key, which returns the return code, reason code and the data.

Using hex strings

Many of the ICSF functions return a hex structure. You can convert this from internal using the Rexx function c2x. This takes a string and creates the hex version of it. When you want to use it in another ICSF function you convert it back again using x2c().

x = ‘ABC’
y = c2x(x)
say ‘y:’y /* gives y:C1C2C3 */

When an ICSF function returns data, you can convert it to the hex string, and return it to the caller.

Using lengths

If a hex length has been returned, you can convert it to a Rexx number using C2D

x = ‘00000000c’x
say ‘x:’c2d(x) /* prints x:12 */

Converting from Rexx to internal format

x = 14
y = d2c(x,4) /* a 4 byte field */
say ‘x:’c2x(y) /* display in hex gives x:0000000E */

Using ICSF from Rexx

Using the program

/*********************************************/ 
/* Generate a 256-bit AES DATA key to export */ 
/*********************************************/ 
rc = genAES() /* this returns several bits of data*/
say "CPBKGN " rc 

parse var rc myrc myrs key 
if myrc <> 0 then return rc 
                                                                         
/********************************************/ 
/* Store the AES DATA key in the CKDS       */ 
/********************************************/ 
/* just return code */ 
rc= addCKDS("REXXLABEL",key) 
say "CPBkrc2" rc 
return 0 

And GENAES

say "In GenAES" 
parse arg a  /* no parameters passed in */ 
/********************************************/ 
/* Generate a 256-bit AES DATA key to export*/ 
/********************************************/ 
key_form               = 'OP  ' 
key_length             = 'KEYLN32 ' 
key_type_1             = 'AESDATA ' 
key_type_2             = '' 
kek_id_1               = COPIES('00'x,64) 
kek_id_2               = '' 
generated_key_id_1 = COPIES('00'x,64) 
generated_key_id_2 = '' 
                                                                   
myrc             = 'FFFFFFFF'x 
myrs              = 'FFFFFFFF'x 
exit_length = d2c(0,4)
exit_data       = '' 
ADDRESS linkpgm "CSNBKGN", 
   'myrc'               'myrs'          , 
   'exit_data_length'   'exit_data'     , 
   'key_form'           'key_length'    , 
   'key_type_1'         'key_type_2'    , 
   'kek_id_1'           'kek_id_2'      , 
   'generated_key_id_1' 'generated_key_id_2' 
 
myrc = c2d(myrc)
myrs = c2d(myrs)                                                                 
IF (myc <> 0 ) THEN 
  DO 
    SAY 'KGN Failed   (rc='myrc' rs='myrs')' 
    Return  myrc myrs 
  END 
                                                                  
Return  myrc myrs c2x(generated_key_id_1)
                                                                         

ADDCKDS

/* -------------------------------------------*/ 
/*  Add CKDS : label and data                 */ 
/* CSNBKRC2 - Key Record Create2              */ 
/* -------------------------------------------*/ 
parse arg label, token 
say "CPBKRC2 " label token 
myrc = 'FFFFFFFF'x 
myrs = 'FFFFFFFF'x 
exit_length =d2c(0,4)
exit_data = '' 
rule_count = d2c(0,4)
rule_array = '' 
token_length = d2c(64,4)
token =x2c(token) 
LEFT(data,64) /* Make sure string length = 64 */ 
ADDRESS LINKPGM "CSNBKRC2", 
   'myrc'          'myrs'            , 
   'exit_length'   'exit_data'       , 
   'rule_count'    'rule_array'      , 
   'label'         'token_length'   , 
   'token'                                                              
myrc = c2d(myrc)
myrs = c2d(myrs)                                                                 
IF (myrc <> 0 ) THEN 
    /* print the return code and description text */
    SAY 'KRC2 Failed   (rc='myrc' rs='myrs')',
             cprs(myrc,myrs)
    RETURN  myrc myrs 
  END 
                                                                 
RETURN   myrc myrs 

and the printable reason code

/* exec to give back reason code string from passed value */ 
parse arg rc,rs 

v.= "Not listed" rs 
v.762="The key values structure for CSNDPKB has a field in error"||, 
            "A length or format is not correct" 
v.2012="The rule_array_count parameter contains a" ||, 
           " number that is not valid." 
v.2016="Rule Array wrong" 
v.2040="Wrong key type.   For example PKI when Importer was expected" 
v.2054="RSA:OAEP optional encoding parameters failed validation" 
v.2089="The algorithm does not match the algorithm"||, 
           " of the key identifier" 
v.10012="Key not found" 
....
return v.rs 

Notes:

I converted from a string to a hex representation of the string when passing data around because the hex data could have a blanks in it. Using the Rexx parse var x a b c parses on blank delimited words, and imbedded blanks could cause a mis-parse.