Setting up ICSF on z/OS

ICSF 5 Minutes

ICSF provides many functions. One function is to manage keys encryption and decryption.

As well as providing encryption etc, it can provide tokens to access encryption keys.

  • ICSF public and private keys are stored in the Public Key Data Set (PKDS)
  • ICSF Cryptographic keys that are encrypted are stored in the Cryptographic Key Data Set(CKDS)
  • ICSF PKCS #11 tokens and objects are stored in Token Key Data Set

There is a batch interface for some command, and ISPF interface using @ICSF, and an API.

The instructions below are a “get you going”. You can protect you keys see Maintaining cryptographic keys.

Create the datasets

Create the CKDS

//IBMCKDS   JOB 1 
//DEFINE  EXEC PGM=IDCAMS,REGION=4M 
//SYSPRINT DD SYSOUT=* 
//SYSIN DD * 
  DELETE              'COLIN.SCSFCKDS' 
  DEFINE CLUSTER (NAME(COLIN.SCSFCKDS)      - 
                  VOLUMES(C4SYS1)            - 
                RECORDS(200 100)           - 
                RECORDSIZE(372,32756 )     - 
                  KEYS(72 0)                 - 
                  FREESPACE(10,10)           - 
                  SHAREOPTIONS(2,3))         - 
            DATA (NAME(COLIN.SCSFCKDS.DATA) - 
                  BUFFERSPACE(100000)        - 
                  ERASE)                     - 
           INDEX (NAME(COLIN.SCSFCKDS.INDEX)) 
/*

Create the PKDS

//IBMPKDS   JOB 1 
//DEFINE  EXEC PGM=IDCAMS,REGION=64M 
//SYSPRINT DD SYSOUT=* 
//SYSIN DD * 
  DELETE              'COLIN.SCSFPKDS' PURGE 
  DEFINE CLUSTER (NAME(COLIN.SCSFPKDS)        - 
                  VOLUMES(C4SYS1)            - 
                  RECORDS(100 50)            - 
                  RECORDSIZE(800,32756)      - 
                  KEYS(72 0)                 - 
                  FREESPACE(0,0)             - 
                  SHAREOPTIONS(2,3))         - 
            DATA (NAME(COLIN.SCSFPKDS.DATA) - 
                  BUFFERSPACE(100000)        - 
                  ERASE                      - 
                  CISZ(32768))               - 
           INDEX (NAME(COLIN.SCSFPKDS.INDEX)) 
/*

Set up the TKDS

This is described here.

The documentation describes 2 ways of creating the TKDS.

  • Define
  • Define and initialise it

I do not know what the difference is. The first seems to work OK

//IBMCKDS   JOB 1 
//DEFINE  EXEC PGM=IDCAMS,REGION=4M 
//SYSPRINT DD SYSOUT=* 
//SYSIN DD * 
  DELETE              'COLIN.SCSFTKDS' 
  DEFINE CLUSTER (NAME(COLIN.SCSFTKDS)    - 
                  VOLUMES(C4SYS1)            - 
                  RECORDS(100 50) - 
                  RECORDSIZE(2200,32756) - 
                  KEYS(72 0) - 
                  FREESPACE(0,0) - 
                  SPANNED - 
                  SHAREOPTIONS(2,3)) - 
            DATA (NAME(COLIN.SCSFTKDS.DATA) - 
                  BUFFERSPACE(100000)        -
                  CONTROLINTERVALSIZE(32768) -       
                  ERASE)                     - 
           INDEX (NAME(COLIN.SCSFTKDS.INDEX)) 
/* 
/*

Update the parmlib member for ICSF

The ICSF job output has information like

IEE252I MEMBER CSFPRMCP FOUND IN USER.Z31A.PARMLIB

Either use this member, or create a new member.

My member has

CKDSN(COLIN.SCSFCKDS)                        
PKDSN(COLIN.SCSFPKDS)                        
TKDSN(COLIN.SCSFTKDS)                        
DOMAIN(0)

See Parameters in the installation options data set.

Running on zPDT and ADCD, I also had to specify SSM(YES) so I could specify KGUP parameter CLEAR.

Check your IKJTSOxx has 

AUTHPGM NAMES(          /* AUTHORIZED PROGRAMS      */      
   ... 
   CSFDAUTH           /* ICSF COMMAND             */ + 
   CSFDPKDS           /* ICSF Command             */ 
   ...
   )

Started task member CSF

In the ICSF documentation the started task is called CSF. Personally I would have called it ICSF.

//CSF  PROC PRM=CP 
//CSF  EXEC PGM=CSFINIT,PARM=&PRM,REGION=0M,TIME=1440,MEMLIMIT=NOLIMIT

RACF Started definition

On my system it uses the default STARTED * (G) profile. This has

STDATA INFORMATION          
------------------          
USER= START1                
GROUP= SYS1                 
TRUSTED= NO                 
PRIVILEGED= NO              
TRACE= YES

RACF user definitions

RDEFINE CSFSERV CSF* UACC(NONE) 
RDEFINE CSFSERV CSF1TRL UACC(NONE)
RDEFINE CSFSERV CSF1TRC UACC(NONE) 
PERMIT CSF*     CLASS(CSFSERV)  ID(PKISRVD) ACCESS(READ) 
PERMIT CSF1TRL  CLASS(CSFSERV)  ID(PKISRVD) ACCESS(READ) 
PERMIT CSF1TRL  CLASS(CSFSERV)  ID(COLIN  ) ACCESS(READ) 
PERMIT CSF1TRL  CLASS(CSFSERV)  ID(IBMUSER) ACCESS(READ) 
PERMIT CSF1TRC  CLASS(CSFSERV)  ID(IBMUSER) ACCESS(READ) 
SETROPTS CLASSACT(CSFSERV) RACLIST(CSFSERV) 
SETROPTS RACLIST(CSFSERV,CRYPTOZ) REFRESH

Start ICSF

S  CSF

This gave me

CSFO0230 CKDSN(COLIN.SCSFCKDS)                                
CSFO0230 PKDSN(COLIN.SCSFPKDS)                                
CSFO0230 TKDSN(COLIN.SCSFTKDS)                                
CSFO0230 DOMAIN(0)                                            
CSFO0166 DEFAULT CICS WAIT LIST WILL BE USED.                 
IEE252I MEMBER CTICSF00 FOUND IN SYS1.PARMLIB                 
CSFM607I A CKDS KEY STORE POLICY IS NOT DEFINED.              
CSFM607I A PKDS KEY STORE POLICY IS NOT DEFINED.              
CSFM610I GRANULAR KEYLABEL ACCESS CONTROL IS DISABLED. 
CSFM611I XCSFKEY EXPORT CONTROL FOR AES IS DISABLED.                       
CSFM611I XCSFKEY EXPORT CONTROL FOR DES IS DISABLED.                       
CSFM612I PKA KEY EXTENSIONS CONTROL IS DISABLED.                           
CSFM654I KEY ARCHIVING USE CONTROL IS DISABLED.                            
CSFM723I ARCHIVED KEY USE DATA DECRYPTION CONTROL IS DISABLED.             
CSFM732I MASTER KEY ENTRY UTILITY KEY OWNERSHIP CONTROL IS DISABLED.       
CSFM653I CKDS LOADED 3 RECORDS WITH AVERAGE SIZE 254                       
CSFM653I TKDS LOADED 45 RECORDS WITH AVERAGE SIZE 2083                     
CSFM129I MASTER KEY DES ON CRYPTO EXPRESS8 COPROCESSOR 8C00, SERIAL       
NUMBER 93AAC740, IS CORRECT.                                               
CSFM129I MASTER KEY AES ON CRYPTO EXPRESS8 COPROCESSOR 8C00, SERIAL        
NUMBER 93AAC740, IS CORRECT.                                               
CSFM129I MASTER KEY RSA ON CRYPTO EXPRESS8 COPROCESSOR 8C00, SERIAL        
NUMBER 93AAC740, IS CORRECT.                                               
CSFM129I MASTER KEY ECC ON CRYPTO EXPRESS8 COPROCESSOR 8C00, SERIAL        
NUMBER 93AAC740, IS CORRECT.                                               
CSFM111I CRYPTOGRAPHIC FEATURE IS ACTIVE. CRYPTO EXPRESS8 COPROCESSOR      
8C00, SERIAL NUMBER 93AAC740.                                              
CSFM129I MASTER KEY DES ON CRYPTO EXPRESS8 COPROCESSOR 8C01, SERIAL        
NUMBER 93AAC741, IS CORRECT.                                               
CSFM129I MASTER KEY AES ON CRYPTO EXPRESS8 COPROCESSOR 8C01, SERIAL        
NUMBER 93AAC741, IS CORRECT.                                               
CSFM129I MASTER KEY RSA ON CRYPTO EXPRESS8 COPROCESSOR 8C01, SERIAL        
NUMBER 93AAC741, IS CORRECT.                                               
CSFM129I MASTER KEY ECC ON CRYPTO EXPRESS8 COPROCESSOR 8C01, SERIAL        
NUMBER 93AAC741, IS CORRECT.                                               
CSFM111I CRYPTOGRAPHIC FEATURE IS ACTIVE. CRYPTO EXPRESS8 COPROCESSOR      
8C01, SERIAL NUMBER 93AAC741.                                              
CSFM133I THERE ARE NO ACTIVE PKCS11 COPROCESSORS.                          
CSFM508I CRYPTOGRAPHY - THERE ARE NO CRYPTOGRAPHIC ACCELERATORS ONLINE.    
CSFM698I DOMAIN IN USE: 0                                                  
CSFM015I FIPS 140 SELF CHECKS FOR PKCS11 SERVICES SUCCESSFUL.              
CSFM400I CRYPTOGRAPHY - SERVICES ARE NOW AVAILABLE.                        
CSFM130I CRYPTOGRAPHY - DES SERVICES ARE AVAILABLE.                        
CSFM130I CRYPTOGRAPHY - RSA SERVICES ARE AVAILABLE.                        
CSFM130I CRYPTOGRAPHY - ECC SERVICES ARE AVAILABLE.                        
CSFM127I CRYPTOGRAPHY - AES SERVICES ARE AVAILABLE.                        
CSFM126I CRYPTOGRAPHY - FULL CPU-BASED SERVICES ARE AVAILABLE.
CSFM001I ICSF INITIALIZATION COMPLETE                              
CSFM640I ICSF RELEASE FMID=HCR77E0.                                
CSFM716I ICSF HAS BEEN INITIALIZED WITH SCSFMOD0 FROM LNKLST       
CSFM716I ICSF HAS BEEN INITIALIZED WITH SIEALNKE FROM LNKLST

Message CSFM133I THERE ARE NO ACTIVE PKCS11 COPROCESSORS is because zPDT does not support this.

To stop ICSF use the operator command

p CSF

Initialise the environment

Get into the ICSF environment.

  • From ISPF option 6 (TSO)
  • @ICSF
  • panelid on to display the name of the panel in the top left corner of the screen
  • you should be in panel CSF@PRIM
  • option 6 PPINIT – Pass Phrase Master Key/KDS Initialization -> panelid CSFPMC40
  • Enter your pass phrase, tab down to _ Reinitialize system and select it using /
  • Enter your data set names for example CKDS ===> ‘COLIN.SCSFCKDS’ . Ensure the name is in quotes.
  • press enter. I got a panel with message ‘ARE YOU SURE YOU WISH TO PROCEED WITH PASS PHRASE INITIALIZATION?’
  • press enter to continue.
  • The message CSFM653I PKDS LOADED 6 RECORDS WITH AVERAGE SIZE 583 was displayed and INITIALIZATION COMPLETE was displayed in the top right corner.

Update your backup procedure to backup these datasets.

What can you do once it has started?

You can issue operator commands

d icsf,kds                                            
  CSFM668I 14.33.27 ICSF KDS 319                      
  CKDS  COLIN.SCSFCKDS                                                   
    FORMAT=KDSR                  SYSPLEX=N  MKVPs=DES AES                
    DES MKVP date=2024-09-10 12:43:29                                    
    AES MKVP date=2024-09-10 12:43:29                                    
  PKDS  COLIN.SCSFPKDS                                                   
    FORMAT=KDSR                  SYSPLEX=N  MKVPs=RSA ECC                
    RSA MKVP date=2024-09-10 12:43:30                                    
    ECC MKVP date=2024-09-10 12:43:30                                    
  TKDS  COLIN.SCSFTKDS                                                   
    FORMAT=KDSRL                 SYSPLEX=N  MKVPs=None

You can use the @ICSF TSO command (see above)

  • To list the CKDS use 5 UTILITY; 5 CKDS KEYS;1 List all records
  • To list the PKDS use 5 UTILITY; 6 PKDS KEYS;1 List all records
  • To list the TKDS use 5 UTILITY; 7 tokens in TKDS ;4 List existing tokens

Note: Be careful when using the ISPF line commands as the D means delete, not display!

Batch programs

You can use The Key Generation Utility Program CSFKGUP. This uses definitions described here. See One minute MVS – Using individual data set encryption on z/OS for an example of defining a key.

Whoops

After I had used PKI Services to define certificates, I got the health checker message CSFH0054I Check for clear keys in the CKDS, PKDS, and TKDS.

The problems were

Active TKDS: COLIN.SCSFTKDS 
---------------------------------------------
PKISRVD.PKITOKEN                00000001T 
PKISRVD.PKITOKEN                00000002T 
PKISRVD.PKITOKEN                00000003T 
PKISRVD.PKITOKEN                00000004T

Which came from PKISERVD

I fixed this changing the PKI Server pkiserv.conf file to have SecureKey=T, but zPDT does not support encrypted keys, so with zPDT you have to have SecureKey=F.
I got messages in the PKISERVD log

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

Unknown's avatar

Published by Colin Paice

I retired from IBM where I worked on MQ on z/OS, and did customer stuff. I retired, and keep my hand in with MQ, by playing with it! I'm now an #IBMChampion from my work trying to make z/OS product more usable.

Published

Leave a comment