Category: ICSF

ICSF return codes – not for humans

Using the ISPF ICSF functions I got

OUTPUT KEY DS NOT EMPTY (TO BE ABLE TO WRITE TO THE OUTPUT KEY DATA SET IT MUST BE EMPTY)

This was with the option 6, and trying to reinitialise the CSF.SCSFCKDS and CSF.SCSFPKDS.

The data sets had already been initialised. If you want to start with a new pair of data sets, you will need to delete and recreate them.

Below are some of the errors I experienced using ICSF

IKYC010I Error 791740530 returned from CP_NewKeysCreate: PKI Services can not generate certificates with secure keys.
IKYC010I Error 791740530 returned from JNH_create_certificate: PKI Services can not generate certificates with secure keys.

I had in pkiserv.conf

# Should the CA generate secure keys in the Token Data Set (TKDS) 
# when it has key generation capability? 
# Valid SecureKey values are: 
# T - True indicates secure keys are generated in the TKDS 
# F - False (or absence of this keyword) indicates clear keys 
#     will be generated in the TKDS. Note: Installation 
#     configuration policy may override the ability to create 
#     clear keys causing clear key requests to create secure 
#     keys. 
# If TokenName is not specified, the SecureKey keyword 
# will be ignored. 
SecureKey=T

I changed this to F and I could generate certificates.

When CSF was restarted I got the health check exception

CSFH0054I Check for clear keys in the CKDS, PKDS, and TKDS.                                                               
                                                                
Active TKDS: COLIN.SCSFTKDS 
--------------------------------------------------------- 
PKISRVD.PKITOKEN                00000001T 
PKISRVD.PKITOKEN                00000002T 
PKISRVD.PKITOKEN                00000003T 
PKISRVD.PKITOKEN                00000004T

zPDT does not support PKCS #11 instructions, so you have to live with this.

INSUFFICIENT ACCESS AUTHORITY TO PERFORM THIS FUNCTION. CSF1TRC FAILED WITH
RETURN CODE: 00000008 REASON CODE: 00016000

I got this when trying to define a token PKISRVD.Z2

  • I had access to CSF1TRC
  • The reason was there was no RDEFINE CRYPTOZ SO.PKISRVD.Z2
  • I did not need access to it – the profile just had to exist
  • It needs the SO on the front.
  • To be able to use it, you also need USER.PKISRVD.Z2 and be given authority to it.

IEC143I 213-85 RC=X’00000008′,RSN=X’0000271C’

The return codes as documented in ICSF Application programmers guide – appendix A.

271C (10012)

Colin’s answer.

It could not find the key. Perhaps the CKDS was updated using the KGUP utility. Try refreshing the CKDS (either in batch or using the ISPF panels). For example

//REFRESHE EXEC PGM=CSFEUTIL,PARM=’CSF.SCSFCKDS,REFRESH’
//REFRESHF EXEC PGM=CSFPUTIL,PARM=’REFRESH,CSF.SCSFPKDS.NEW’

Perhaps you are trying to encrypt a data set with a non symmetric key – for example a PKI.

IEC143I 213-8,RC=X’00000008′,RSN=X’00000BF3′

The return codes as documented in ICSF Application programmers guide – appendix A.

BF3 (3059) The provided key_identifier refers to an encrypted variable-length CCA key token or a key label of an encrypted variable-length CCA key token. The key-management field in the CCA token does not allow its use in high performance encrypted key operations.


User action: Supply a key token or the label of a key token with the required key-management settings.

Colin’s comments

With CSNBKTB2 I got the 0xbf3 when ‘XPRTCPAC’ was missing. For example I needed rule_array = ‘INTERNAL’||’AES ‘||’CIPHER ‘||’ANY-MODE’||’XPRTCPAC’

The doc for AES CIPHER says XPRTCPAC Allow export to CPACF protected key format.

I also got this trying to use an EXPORTER or an IMPORTER key. This does not support XPRTCPAC.

Defining the cipher using ISPF worked. Using KGUP I needed

ADD TYPE(CIPHER) ALGORITHM(AES), 
KEYUSAGE(ANY-MODE) LENGTH(32), 
KEYMGT(XPRTCPAC), 
LABEL(COLINCIPHER2 )

I also got this BF3 when the key was archived.

IEC143I 213-85, RC=X’00000008′,RSN=X’00000BFB’

The provided symmetric key label refers to an encrypted CCA key token, and the CSFKEYS profile covering it does not allow its use in high performance encrypted key operations.

User action: Contact your ICSF or RACF administrator if you need to use this key in calls to Symmetric Key Encipher (CSNBSYE) or Symmetric Key Decipher (CSNBSYD). Otherwise, use Encipher (CSNBENC) or Decipher (CSNBDEC) instead.

Colin’s answer

Define the profile with the bold text

RDEFINE CSFKEYS DES5 UACC(NONE) –
ICSF(SYMCPACFWRAP(YES) SYMCPACFRET(YES))

IEC143I 213-85, RC=X’00000008′,RSN=X’0000272C’

The return codes as documented in ICSF Application programmers guide – appendix A.

272C (10028)

Colin’s comment

I got this when I tried to use

ADD TYPE(DECIPHER) ALGORITHM(DES) LABEL(DES5) CLEAR or
ADD TYPE(ENCIPHER) ALGORITHM(DES) LABEL(DES5) CLEAR

The following worked

ADD TYPE(CIPHER) ALGORITHM(DES) LABEL(DES5) CLEAR

as did

ADD TYPE(CIPHER) ALGORITHM(AES),
KEYUSAGE(ANY-MODE) LENGTH(32),
KEYMGT(XPRTCPAC),
LABEL(COLINCIPHER2 )

Colin’s answer.

I had defined the cipher as DECIPHER.

CSFM655I AN ARCHIVED RECORD COLINCIPHER IN THE ACTIVE CKDS WAS REFERENCED.

I got this when I used an archived key, and had KEYARCHMSG(YES) specified in my ICSF startup.

CSFG1094 TRANSKEY label TOO WEAK.

Colin’s comment

I was trying to use TRANSKEY but the length of the transkey is shorter than the key being defined, for example

ADD LABEL(ATOB) TYPE(EXPORTER) CLEAR LENGTH(16) ALGORITHM(DES)

ADD LABEL(KEY2) TYPE(DATA) LENGTH(24)TRANSKEY(ATOB) ALGORITHM(DES)

Instead of LENGTH(16) I had to use DOUBLEO.

IEC143I 213-86

During open processing for an encrypted extended format data set, on return from the ICSF service used to process the key label associated with the data set, the system detected that the encryption type of the data key associated with the key label was not of a supported encryption type. Only encryption keys of type AES256 are supported for extended format data sets.

Colin’s comment

Using

ADD TYPE(DATA) ALGORITHM(AES) LABEL(AES5) LENGTH(32)

Using ISPF panels 5 UTILITY, 5 CKDS KEYS, 7 Generate AES DATA keys, Enter the CKDS record label for the new AES DATA key.

With AES key bit length: 128 or 192, I got this message. Using 256 worked.

with length(32) works. With length(16) it gives 213-86

Update: Only encryption keys of type AES256 are supported for ANY data set encryption.

I also got this abend code when the data set was not extended format.

IEC143I 213-85

COLINAES CL(CSFKEYS ) INSUFFICIENT ACCESS AUTHORITY COLIN.ENCR.DSN,
ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )
RC=X’00000008′,RSN=X’00003E84′

Colin’s comments

The userid did not have access to the profile COLINAES of type CSFKEYS in ICSF. The data set was COLIN.ENCR.DSN.

RACF class XFACILIT CSF.XCSFKEY.ENABLE.AES was defined, which says do more detailed security checks, but the XCSFKEY profile was not found. RDEFINE XCSFKEY * UACC(NONE) WARNING

IEC143I 213-85, RC=X’00000008′,RSN=X’0000085E’

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.
User action: Use the variable-length key token in a manner consistent with its usage attributes or create a new key token with the desired attributes

Colin’s comments 1

I got this when I had

ADD TYPE(CIPHER ) ALGORITHM(AES) LENGTH(32) LAB(AESCI)

Changing it to type(DATA) worked.

Colin’s comments 2

  • I had a C program and used CSNBKTB2. When CBC was defaulted I got the 85E, when I used ANY-MODE it worked.
  • I had another program which used rule_array = ‘INTERNAL’||’AES ‘||’CIPHER ‘||’XPRTCPAC’||’ANY-MODE’||’ENCRYPT ‘. Without ENCYPT it worked. With both ENCRYPT and DECRYPT it worked.

Colin’s comment 3.

A type(cipher) with key used(any) worked; with key used(cbc) it didn’t work.

IEC143I 213-91

During open processing for an encrypted extended format sequential data set, the system determined that the data key in the CKDS associated with the key label for the data set is not the same data key used to encrypt the data set.

I created an encrypted dataset, then deleted and recreated the cipher key. This means the dataset could not be processed as the key was now lost.

Return codes

02f (47) A source key token is unusable because it contains data that is not valid or undefined.

I tried to extract the key of a skeleton key token, when there was none. CSNBKYT2 and the KEY-LEN option

3d (61) The keyword supplied with the key_type parameter is not valid.

I was using CSNBKGN2 and wrongly specified INPORTER instead of IMPORTER

048 ( 72 ) The value specified for length parameter for a key token, key, or text field is not valid.

Colin’s comments.

I got this in CSNDSYI2 when using a private key with a small key size(1024). When I used a private key with key size of 4096 it worked.

09B ( 155 ) The value that the generated_key_identifier parameter specifies is not valid,

or it is not consistent with the value that the key_form parameter specifies.

Colin’s comments

Case 1.

I was trying to generate an IMPORTER and an EXPORTER key. I used CSNBKTB2 to build a skeleton. When I used CSNBKGN2 to generate the token. I got this return code. I think this is because I did not provide a Transport Encryption Key (KEK)

When I used CSNDEDH passing the output from CSNBKTB2, the private key label, and the public key label, it worked, and I could add it to the CKDS using CSNBKRC2.

Case 2.

CSNBKGN2 only accepts skeletons created with type = CIPHER, HMAC, or MAC. See table 77. Trying to use a skeleton for EXPORTER or IMPORTER give you this message.

Case 3.

In CSNBKTB2 I had specified

‘INTERNAL’||’AES ‘||’CIPHER ‘||’XPRTCPAC’||’ANY-MODE’||’DECRYPT ‘

CSNBKGN2 gave me rs 155. Remove the DECRYPT and it worked

Case 4.
I was using CSNBKGN2 with pkeyType1 = “TOKEN “; I needed to change this to AES for it to work.

Case 5. I had generated a skeleton with TYPE=EXTERNAL. When I came to generate the key using this skeleton, it was mode=OP – or INTERNAL! I changed the skeleton and it worked.

If MODE=OP the skeleton must have INTERNAL, if MODE=EX the skeleton must have EXTERNAL.

The opposite may give the same return code – eg skeleton with type=internal, and generate key with non OP mode.

F6 ( 246 ) Not documented

I got

  • CSNDKRC  add pkds getting 0 246

I got this with

rc = 'FFFFFFFF'x
rs = 'FFFFFFFF'x
ADDRESS LINKPGM "CSNDKRC",
  'myrc' 'myrs' ,
 ...

because I had not initialised myrc and myrs.

7FB ( 2040 ) Bad data

This check is based on the first byte in the key identifier parameter. The key identifier provided is either an internal token, where an external or null token was required; or an external or null token, where an internal token was required. The token provided may be none of these, and, therefore, the parameter is not a key identifier at all.

Colin’s comment

  • Check you are passing in the right data! I had misspelt a variable.
  • I was trying to import a PKI public certificate – when it was an AES exported certificate
  • I was trying to use a PKI a private CCA key token of type ECC. CSNDSYI2 only accepts … key enciphered under an RSA public key or AES EXPORTER key.
  • You are trying to use CSNDSYI2 for a DATA key when you should be using CSNDSYI.
  • I was trying to add a key to the ckds, with the wrong format. It had been generated as exporter/importer/external token.

806 ( 2054 ) Invalid RSA enciphered key cryptogram; OAEP optional encoding parameters failed validation.

Colin’s comments

I got this when I used the wrong private key to decrypt a key in CSNDSYI2. When I used the correct key it worked.

829 ( 2089 ) The algorithm does not match the algorithm of the key identifier

The algorithm does not match the algorithm of the key identifier.
User action: Make sure the rule_array keywords specified are valid for the type of key specified. Refer to the rule_array parameter described in this publication under the appropriate callable service for the valid values.

Colin’s comment.

  • I got this because I had a private key created as an ECC. Where it was expecting an RSA key.
  • CSNDSYX trying to use an PKI public key with ECC…. to encryption under an application supplied RSA public key or AES EXPORTER key.

825 (2095) The value in the key_form parameter is incompatible with the value in the key_type parameter.

I was using CSNBKGN2. I had pkeyType1=”EXPORTER” . I had rule_array Key Form (required) as “EX “. I change pkeyType1 to CIPHER, and got past it.

86A ( 2154 ) Bad key type

At least one key token passed to this callable service does not have the required key type for the specified
function.

Colin’s comments.

  • I got this trying to use an Importer key instead of an Exporter key.
  • I got this trying to use a DH key when an RSA key was expected. The requirements were CSNDSYX: RSA public key or AES EXPORTER

86E ( 2158 ) Not in the books

I got this doing Diffie-Hellman key exchange CSNDEDH using a private key and a public key.

  • With private ECC Curve: PRIME Bits 521 and public ECC Curve: PRIME Bits 384 I got reason code 2158.
  • With private ECC Curve: PRIME Bits 521 and public ECC Curve: PRIME Bits 521 I got reason code 0.
  • With private ECC Curve: PRIME Bits 521 and public ECC Curve: BRAINPOOL Bits 521 I got reason code 2158.
  • With private ECC Curve: BRAINPOOL Bits 521 and public ECC Curve: BRAINPOOL Bits 521 I got reason code 0.

It looks like you have to have matching curve type, and matching size (in bits) for it to work. The documentation under ECC Diffie-Hellman (CSNDEDH and CSNFEDH) says

The ECC curve type and size must be the same as the type (Prime, Brainpool, or Koblitz) and size of
the ECC key-token specified by the public key identifier parameter.

BF9 (3065) Duplicate key

ICSF Duplicate key token policy checking is active. The caller is requesting to add a token to the key data set (CKDS or PKDS as appropriate) that already exists within the key data set. The request fails.

I got this when adding a key to the PKDS and the key name field within the record already exists in the data base. I tried to add key ATOB, with key name TEMP1 – but TEMP1 already existed.

DC9 ( 3529 ) Bad label

A key identifier was supplied to a callable service as a key token or the label of a key token in a key data set. Either the key type of the key or the algorithm of the key is unsupported by the cryptographic features available to ICSF.

Colin’s comment

Perhaps you specified a label name – when it did not exit.

PKA Key Generate (CSNDPKG):generated_key_token_length: The length of the generated key token or label for the generated key token.

I assumed you could give it a label, and it would store the data under that label.

2B30 ( 11056 ) The input PKA token contains length fields that are not valid.


User action: Re-create the key token.

Colin’s comment
2B30 (11056) The skeleton_key_identifier_length field is not valid.
User action:  Check  the skeleton_key_identifier_length and skeleton_key_identifier  (returned from CSNDPKB fields key_token_length,key_token)

Return code 8 reason 2AF8 ( 11000 ) The value specified for length parameter for a key token, key, or text field is not valid.


User action: Correct the appropriate length field parameter. For example I had target_key_identifier_length as 1000, but the documentation said The maximum value is 725 bytes.

Colin’s comment

Make sure you pass the address of the length eg &size, not the size itself.

Make sure you are adding to the correct database. If you try to add a PKI to a CKDS you will get this reason code.

I specified the length of a key – but for DES the length had to be zero.

Make fields bigger. I got this with

RSA_enciphered_key_length: The length of the RSA_enciphered_key parameter. This service updates this field with the actual length of the RSA_enciphered_key it generates. The maximum size is 512 bytes.

I had to make it 530 before it worked. Note when I came to check this at a later data – it all worked perfectly and I did not need to make it bigger!)

With CSNBKGN2 I have specified a key length of 64 when I had OP… with OP the length must b zero.

I specified a key length of zero when a value like 256 was required.

In create skeleton, I specified a key length, but did not specify KEY_CLR in the rules.

If key length = 0, when it should be a positive integer.

CSFPTRL: rc:8 rs:11000

No more data. When looping through you get rs 3017, buffer too small, meaning there is more data to come. rs = 0 means last record. rs = 11000 means past the end of the data.

271C ( 10012 ) A key label was supplied for a key identifier parameter.

This label is the label of a key in the in-storage CKDS or PKDS. A key record with that label (and the specific type if required by the ICSF callable service) could not be found. So it could be in the CKDS or PKDS, but with the wrong type.

For a retained key label, this error code is also returned if the key is not found in the CCA coprocessor specified in the PKDS record.

I also got this when using CSNDSYX and did not have rule_array with AESKW.

Colin’s comment.

  • I had specified a key of type data (which existed in the CKDS), but it was expecting a key of type Exporter, so was not found and could not find the label in the PKDS).
  • CSNDSYX trying to use an PKI public key with ECC…. to encryption under an application supplied RSA public key or AES EXPORTER key.
  • You specified a key, but the key was not char[64] and had garbage in the value. This can occur if you use a C null terminated string.
  • I was using CSNBKGN2 and used a rule I_rule[2] = {“AES “,”IN “} instead of IM.

2740 ( 10048 ) The key_type parameter does not contain one of the valid types for the service or the keyword TOKEN.

Colin’s comment

I was trying to use CSNDEDH which required a private key and a public key of type ECC. I had specified an RSA key.

3E80(16000) RACF failed your request to use this service or PKCS #11 token. This may be caused by the CSFSERV or CRYPTOZ class.

Colin’s comments.

Check the job log. This userid does not have read access to CSFOWH CLASS(CSFSERV )

IRRD117I Unexpected ICSF CSFPPKS return code x’00000008′ and reason code x’00002B00′. The request is not processed.

The doc says

The public or private key values are not valid (for example, the modulus or an exponent is zero or the exponent is even) or the key could not have created the signature (for example, the modulus value is less than the signature value). In any case, the key cannot be used to verify the signature.

I had

RACDCERT ID(COLIN) GENCERT -                                   
  SUBJECTSDN(CN('TRYPKI') - 
             O('NISTEC256') - 
             OU('SSS')) - 
   NISTECC - 
   KEYUSAGE(   HANDSHAKE     )  - 
   SIZE(256 ) - 
   WITHLABEL('TRYPKI') 

RACDCERT ID(COLIN)          - 
    GENREQ(LABEL('TRYPKI'))      - 
    DSN('COLIN.PKI.GENREQ')

Changing size to 384 worked.

IRRD117I Unexpected ICSF CSFPTRC return code x’0000000C’ and reason code x’00000BCF’.

See BCF. The PKCS #11 TKDS is not available for processing

CSFC0116 CONTROL BLOCK VALIDATION ERROR. RETURN CODE = 8, REASON CODE = 36.

I got this when reinitialising csf. The data sets were not quoted, and used a data set name of ‘.CSF.CSFCKDS.NEW’ (starting with a period).

Action: Enclose the names in quotes.

CSFY0076 VSAM ERROR OCCURRED PROCESSING DD CSFCKDS. VSAM FEEDBACK CODE = 93080010

I think this is saying it cannot get the CKDS exclusive. I stopped CSF and the job ran.

CSFY0076 VSAM ERROR OCCURRED PROCESSING DD CSFCKDS. VSAM FEEDBACK CODE = A9080010

I think code A9080010 is record not found. It matches the message in CSFDIAG

CSFG0264 ENTRY TEMP IMPORTER NOT FOUND ON CKDS. ADD NOT PERFORMED

CSFKGUP return code 36

I ran a KGUP program, got return code 36 and no other output. csfg0002 says

36: State of special secure mode on the coprocessor is not the same as the state that is specified in the PARM field of the EXEC JCL statement.

CSFG0986 CKDS IS NOT USABLE.

I was using the wrong CKDS. I had two and was swapping between them.

CSFG0074 SYNTAX ERROR IN CONTROL STATEMENT

I had

ADD TYPE(CIPHER  ) ALGORITHM(AES), 
 CLEAR KEY(9C96548DEC7D5057,4B95D3B09E8D75D6,BF6C497593E5E31D, 
 B13AC2AF14331483), 
 LAB(COLINCLEAR)

with the wrong number of digits in one of the key parts. I had 483>0< at the of the statement.

CSNDSYX rc 8 rs 16004 RACF

I was trying to use key AESCIPHER and exporting key KEYBTOA. I got CSNDSYX rc 8 rs 16004 RACF failed your request to use the key label or token.

Not authorised

For rc 16004 I got

AESCIPHER CL(CSFKEYS )
INSUFFICIENT ACCESS AUTHORITY
ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )

Give the userid access to the resource.

I needed this for the Key to be exported and the Key Exporting Key.

Missing XCSFKEY profile

After a GTF RACF trace I found I did not have a profile for class XCSFKEY profile AESCIPHER. I defined this, and the request worked.

In this page, it says Profiles in the XCSFKEY class are used in authorization checks only when the Symmetric Key Export service (CSNDSYX, CSNFSYX, or CSNDSXD) is called. See Increasing the level of authority required to export symmetric keys for additional information.

I needed this profile because I had (a long time ago) defined a class XFACILIT profile CSF.XCSFKEY.ENABLE.AES. See table 1.

One Minute MVS – ICSF. It might be better if they finished it.

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 (see here) 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.
  • 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. See dataset CSF.SCSFCLI0 .
  • 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
//CSF EXEC PGM=CSFINIT,PARM=&PRM,…..

S CSF,PRM=CP

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.

Rexx program to invoke ICSF panels

I used the following to invoke the ISPF panels for ICSF. I call the exec CSF.

To invoke it, from an ISPF screen type TSO CSF.

/* Rexx */                                                
/* IBMs ICSF */                                           
 address ispexec                                          
"LIBDEF ISPPLIB DATASET ID('CSF.SCSFPNL0') STACK"         
"LIBDEF ISPMLIB DATASET ID('CSF.SCSFMSG0') STACK"         
"LIBDEF ISPSLIB DATASET ID('CSF.SCSFSKL0') STACK"         
"LIBDEF ISPTLIB DATASET ID('CSF.SCSFTLIB') STACK"         
address tso "ALTLIB ACTIVATE APPLICATION(CLIST)           
            DATASET('CSF.SCSFCLI0')"                      
                                                          
"SELECT PANEL(CSF@PRIM) NEWAPPL(CSF) PASSLIB"             
                                                          
address tso "ALTLIB DEACTIVATE APPLICATION(CLIST)"        
"LIBDEF ISPSLIB"                                          
"LIBDEF ISPPLIB"                                          
"LIBDEF ISPMLIB"                                          
"LIBDEF ISPTLIB"