As part of setting up data set encryption to send data sets between two sites. I wrote some programs to help securely send the symmetric key exchange between two systems using private and public keys.
Basis flow to get a symmetric key on two systems to allow data set encryption and decryption, using private key and public key.
The steps to allow me to send an encrypted dataset to a remote system, using PKI are as follows
- On the remote system generate a private/public key in the PKDS
- Extract the public key and send it to the local system
- Import the public key into the local PKDS
- On the local system, generate a symmetric AES key for encrypting data sets.
- Export the key, encrypt it using the public key, into a buffer.
- Write the buffer to a file
- Send the file to the remote system.
- Read the file, decrypt the buffer using the private key, re-encrypt with the local master key, store it in the local CKDS.
- Displayed the key at each end and compared the
- Use the symmetric key to decrypt a dataset.
The programs
I wrote some helper programs for example read a key from the CKDS returning the data; create an entry in the PKDS with a specified key and a blob of data containing the token.
Create a private public key
I could not find a batch utility to define a private key, but could use the ISPF panels.
I started writing my own program to do this…
I used API function CSNDPKB. I successfully created a Private/Public key using Elliptic Curve (ECC).
I could display this using the ISPF panels 5 UTILITY->6 PKDS KEYS → 1. This lists all of the keys. Use the line command K to display it. ( D is for delete!). It displays attributes like Algorithm: ECC, size 512, Sections: PRIVATE PUBLIC.
I later found out that ECC cannot be used to encrypt a symmetric AESkey. “Use the Symmetric Key Export callable service to transfer an application-supplied AES, DES or variable length symmetric key token key from encryption under a master key to encryption under an application supplied RSA public key or AES EXPORTER key. I could not find how to generate an EXPORTER key with public certificate.
I tried using CSNDPKB to create an RSA private key. You have to complete a “Key Value Structure”. I struggled to complete this for RSA because I needed to specify “prime number p”,and “prime number q”. Ive since found how to do this. I tried an alternate approach of using the ISPF panels.
On the remote system, I used the ISPF panels to create a PKI key. 5 UTILITY → 6 PKDS KEYS → 6 Generate PKA keys. I created a new RSA key with bit length 4096, as bit length 512 was too weak.
Having created my private/public key, I used the ISPF panels to export the public key to a data set, sent it to my local system and import it using the ISPF panels. This public key does not need to be sent securely.
- You can extract the contents of this file using RACDCERT ADD(‘COLIN.EXPORT.ECC1’) ID(COLIN). This gave me a key with
Certificate ID: 2QXD1tPJ1dPBwsXT8PDw8PDw8PFA Status: TRUST Start Date: 2021/08/29 09:42:44 End Date: 2041/08/29 09:42:44 Serial Number: >00< Issuer's Name: >CN=ECCB512Z< Subject's Name: >CN=ECCB512Z< Signing Algorithm: sha256ECDSA Key Type: Brainpool ECC Key Size: 512 Private Key: NO Ring Associations:
I had now had a private key at the remote end, and the public certificate at the local end.
I can encrypt at the local end using the public key, and decrypt it at the remote end using the private key.
Create the AES symmetric key on the local end.
I found I could not use AES type DATA, and so had to use AES type CIPHER.
If I used KGUP utility with
ADD TYPE(CIPHER ) ALGORITHM(AES) LENGTH(32) LAB(AESCIPHER)
This could not be used to encrypt because it gave IEC143I 213-85 RC=X’00000008′, RSN=X’0000085E’
85E (2142) The key usage attributes of the variable-length key token does not allow the requested operation. For example, the request might have been to encrypt data, but encryption is not allowed, or the request might have been to use the ECB cipher mode, but that mode is not allowed.
When I displayed through the ISPF panels (5.5.1) it it showed
Key Usage: ENCRYPT DECRYPT CBC
If I generated an AES key using the API, I found that ENCRYPT DECRYPT ANY-MODE worked, but I could not see how to set ANY-MODE using KGUP.
Program to generate an AES key
// build the skeleton. It is returned in pToken
rc = skeletonAES(&pToken,& lToken);
if ( rc != 0 ) return rc;
// input: the skeleton
// output: the token
rc = GENAES2(pToken,&lToken);
if ( rc != 0 ) return rc;
// add it to the CKDS
rc = doAdd2("C",pKey,pToken,lToken,pDelete);
if ( rc != 0 ) return rc;
return rc;
skeletonAES program
// this program allocates storage, uses it, and passes it back
// to the caller.
int skeletonAES(char ** pData, int * lData)
{
int rc;
int rs;
int zero = 0;
int rule_count = 4 ;
char8 rule[ 4] ={
"INTERNAL","AES ","CIPHER ", "ANY-MODE"
};
char * pRule = & rule[0][0];
int lKeyToken=725;
char * pKeyToken;
pKeyToken = (char *) malloc(lKeyToken);
CSNBKTB2(
&rc, /* return code */
&rs, /* reason code */
&zero, /* exit data length */
0, /* exit data[] */
&rule_count, /* rule array count */
pRule, /* rule array[] */
&zero, /* clear key bit length */
0, /* key value[] */
&zero, /* key name length */
0, /* key name[64] */
&zero, /* user assoc data length */
0, /* user associated data[] */
&zero, /* token data length */
0, /* token data[] */
&zero, /* service data length */
0, /* service data[] */
&lKeyToken, /* target key token length */
pKeyToken ); /* target key token[] */
if ( rc > 0)
{
printf("CSNBKTB2 rc %i rs %i %s\n",rc,rs,csfgetrc(rs));
return rc;
}
free (pData); // get rid of the passed in block
// return the length
*lData = lKeyToken;
//pass back the address of the token
*pData = pKeyToken;
printf("skeletonAES key length %i\n",lKeyToken);
// printHex(stdout,&keyToken,lKeyToken);
printAES((char *) pKeyToken,lKeyToken);
return 0;
}
Create program keygenerate
// this takes the data passed in, and uses it
// The length is updated.
int keyGenerate2( char * pData, int * lData)
{
int rc;
int rs;
int zero = 0;
int rule_count = 2;
// key type AES and used for OP (on this system
char8 rule[2] = {"AES ","OP "};
char * pRule = &rule[0][0];
int keyLength = 256 ;// AES 256 - why use any other?
char8 keyType1 = {"TOKEN "};
char8 keyType2 = {" "};
int i64 = 64;
int l725 = 725;
CSNBKGN2(
&rc , /* return code */
&rs , /* reason code */
&zero, /* exit data length */
0, /* exit data[] */
&rule_count, /* rule array count */
pRule, /* rule array[] */
&keyLength, /* clear key bit length */
(char *) &keyType1 , /* key type1[8] */
(char *) &keyType2 , /* key type2[8] */
&zero, /* key name1 length */
0, /* key name1[64] */
&zero, /* key name2 length */
0, /* key name2[64] */
&zero, /* user assoc data1 length */
0, /* user associated data1[] */
&zero, /* user assoc data2 length */
0, /* user associated data2[] */
&zero, /* KEK id1 length */
0, /* KEK id1[] */
&zero, /* KEK id2 length */
0, /* KEK id2[] */
&l725, /* output key id1 length */
(char *)pData, /* output key id1[] */
&zero , /* output key id2 length */
0 ); /* output key id2[] */
if ( rc > 0)
{
printf("CSNBKGN2 rc %i rs %i %s\n",rc,rs,csfgetrc(rs));
return rc;
}
*lData = l725;
// the same buffer is used,so no need to set pData
return rc;
}
Using these and my add2(…) functions I could create my AES for CIPHER with ANY-MODE. (See ANY-MODE above).
Export the AES key
To export the AES key, you need the name of the public key.
You need a different set of rules for a DATA key and a CIPHER key.
int lData; char * pData; rc =doExportAES (pKey,pPublic,pType,&pData, &lData); if (rc > 0 ) return rc; rc = writeKey(dd,pData,lData); if (rc > 0 ) return rc;
I created a routine which read the key, and one to write it to a file.
The parameters to doExportAES are
- dd name “dd:CERT would use //CERT .. in the JCL
- key is a char64 left justified key name in the CKDS
- pPublic a char 64 left justified name of the public key to use. It must exit in the PKDS.
- A pointer to the string to containing the data
- The length of the returned data.
int doExportAES (char * pKey, char * pPublic, char * pType,
char ** pData, int * lData)
{
int rc;
int rs;
int i64 = 64;
int zero = 0;
int rule_count = 3;
char8 rule_Cipher[3] =
{"AES ",
"PKOAEP2 ",
"SHA-256 "};
char * pRule = rule_Cipher[0][0];
int lOut = 900;
char * pOut;
pOut = (char * ) malloc(lOut);
printf("Source Key user %64.64s.\n",key );
printf("Transport key %64.64s.\n",encrypt);
CSNDSYX (
&rc, /* return code */
&rs , /* reason code */
&zero, /* exit data length */
0 , /* exit data[] */
&rule_count, /* rule array count */
pRule, /* rule array[] */
&i64 , /* source key length, */
pKey , /* source key */
&i64, /* RSA public key length */
pPublic, /* RSA public key token */
&lOut, /* exported key length */
pOut ); /* exported key */
if( rc > 0)
printf("CSNDSYX rc %i rs %i %s\n",rc,rs,csfgetrc(rs));
if (rc != 0) return rc;
// return the exported data
*pData = pOut; * lData = lOut; return 0; }
Import the certificate at the remote end
I created IMPAES
rc= read(dd,&pData,&lData); // returns a buffer from the file
printf("readCert rc %i data length %i\n",rc,lData );
if ( rc != 0) return 8;
rc = doImportAES(pKey,pPrivateKey,&pData,&lData);
if ( rc != 0) return 8;
printf("Returned buffer size %i\n",lData);
rc = doAdd2("C", pKey,pData,lData);
if ( rc != 0 ) return rc;
return 0;
read opens the ddname , and gets back the (binary) data in pData of length lData.
This get passed to doImportAES which uses the private key pointed to by pPrivateKey (a 64 char left justified string). This then returns the AES key (encrypted with the local key) which is then added using do ADD2.
DoImportAES.
/* --------------------------------------------------------------- *
/* Import public key *
/* --------------------------------------------------------------- *
int doImportAES (char * pKey, char * pDecryptKey,
char ** pData, int * lData)
{
int rc;
int rs;
int zero = 0;
int i64 = 64;
int rule_count = 2;
char8 rule_array[2] ;
memcpy(&rule_array[0],"AES ",8);
memcpy(&rule_array[1],"PKOAEP2 ",8);
int lOutput = 725 ;
char * pOutput = (char * ) malloc(lOutput);
if ( pOutput == 0)
{
printf("malloc for %i failed in IMPAES\n",lOutput);
}
printf("Key %64.64s.\n",pKey);
printf("Decrypt Key %64.64s.\n",pDecryptKey);
printf("lInput %i\n",*lData );
//printHex(stdout,* pData,32);
CSNDSYI2 (
&rc, /* return code */
&rs , /* reason code */
&zer /* exit data length */
0 , /* exit data[] */
&rule_count, /* rule array count */
(char *) &rule_array[0],/* rule array[] */
lData , /* length of input data */
* pData, /* input data */
&i64, /* cca DES token length, */
(char *) pDecryptKey , /* cca DES token[64] */
&i64, /* key name length */
(char *) pKey, /* key name[] */
&lOutput , /* Imported key length */
(char *) pOutput ); /* Imported key */
// if( rc > 0)
printf("CSNDSYI2 rc %i rs %i %s\n",rc,rs,csfgetrc(rs));
if (rc != 0) return rc;
// get rid of input buffer
printf("CSNDSYI2 data lengt %i\n",lOutput);
free (*pData);
// and update with the new data
*pData = pOutput;
*lData = lOutput;
return 0;
}
All this creates a key in the CKDS on the remote system which I could use to decrypt a data set.
Summary
It took a long time to write these programs, because I did not know the path to take, and went down many dead ends. Once you know the concepts and know which ICSF functions and options you need, it is not too difficult.
Having these helper routines, I was able to create a program to generate a symmetric key using Diffi-Hellman in about 2 hours! (Most of this time was reading the documentation).
ColinPaice 
A few thoughts: RSA is good, but even a 4096-bit key pair is not as strong as AES-256, so you are effectively transporting with a weaker key. You can use EC-DH to derive an AES EXPORTER on one side and an AES IMPORTER on the other side and use AESKW to wrap the CIPHER key in transit. This pair of complementary keys can be used to transport a number of keys.
When you say, “I used the ISPF panels to export the private key to a data set” I assume you mean that you created a self-signed public-key certificate.
I also notice that since you figured out EC-DH, you can use that more directly. You can
1. exchange the public keys between your remote and local system
2. Derive an exporter on one side and an importer on the other side.
3. When you call CSNBKGN2, you can use “OPEX” to create the CIPHER key locally AND export it using the derived EXPORTER to send to the other side.
4. Use the IMPORTER on the other side with CSNBSYI2 to import the key.
LikeLike
Thanks for your comments.
I’m building up a list of best practices which includes RSA is weaker than AES….
I started with a chicken and egg problem.
Now I know enough to say
create public /private keys etc
generate DH exported/importer
Create cipher key for encrypting data sets
Your 3)When you call CSNBKGN2, you can use “OPEX” to create the CIPHER key locally AND export it using the derived EXPORTER to send to the other side. assumed I knew that an exporter/importer was needed , and not just use PKI.
Personally I would do it in 2 steps so I can reuse my little building blocks.
I’ll think about an “advanced create” where I document create it, export it…. and the advanced – do both in one.
I struggle to see what OPIM gives you. You create on in the local key store.. and one that can be imported into the local key store at a later date? Why? ( I can see if you have multiple +KDS). Also what does IMIM give me? When would I use it?
ISPF panels… I should have said public key “Export the PKDS record’s public key to a certificate data set ”
What can I do with this file? …. Ahh I can use RACDCERT ADD(‘COLIN.EXPORT.ECC1’) ID(COLIN)
LikeLike
Instead of OPEX, you can certainly do this in two steps (CSNBKGN and then CSNDSYX).
Honestly, OPIM, IMIM, etc are strange birds. I cannot think of any good use cases for any of the importable forms.
The only real use for exporting a public key as a self-signed certificate is the use you originally had: to send to a partner so that they can either send you wrapped key material or verify your signatures. However, it would be better to have a proper CA-signed certificate for the latter case.
LikeLike