Preparing for z/OS data set encryption
In preparation of deploying data set encryption, it is important to understand which settings are mandatory or of particular use to your installation. This issue also includes deciding which utilities, tools, and program offerings can assist or complement the setup and management of your environment.
This chapter includes the following topics:
4.1 Data set configuration
This section describes the configuration process for encrypted data sets. The following data set types are supported for data set encryption:
•VSAM extended format data sets
•Sequential extended format data sets
•PDSE data sets
•Sequential basic format data sets
•Sequential large format data sets
Where possible, best practice for VSAM and sequential data sets is for encrypted data sets to be created as extended format and should be compressed in the access methods before encryption.
 
Note: At the time of this writing, the latest ICSF FMID available is HCR77D1. For cross reference information see z/OS: ICSF Version and FMID Cross Reference.
4.1.1 Migrating to extended format data sets
A storage administrator must validate the current list of data sets that are eligible for encryption and the current ACS routines, which are used to determine storage and allocation requirements. For example, some data sets might need to be converted to extended format before they are eligible for encryption.
We do not recommend to automatically use SMS data classes for data set encryption because this configuration can cause all new allocations to be encrypted before the environment is fully prepared to implement.
Also, be aware of the implications of the use of SMS data classes for the allocation of encrypted data sets after the crypto environment is in place because it gives the storage administrator the authority to manage encryption of data sets, which might not be intended.
For more information about other methods of implementation that reference how SMS can be used for setting up, see Chapter 5, “Deploying z/OS data set encryption” on page 119.
4.1.2 Compressing data sets before encryption
Encrypted data does not compress; therefore, data must be compressed before it is encrypted wherever possible. When enabled for compression, DFSMS access methods compress data sets before encryption.
Data sets eligible for compression
The following data sets can be compressed:
•Sequential extended format data sets support generic, tailored, or zEDC compression.
•A VSAM extended format KSDS supports generic compression (only KSDS can be compressed format).
Compressing data sets
To prepare for compression on new data set allocation, set up an SMS policy to request compression. A storage administrator can update the following information:
•Specific data classes through ISMF to request compression by using the COMPACTION option
•Automatic class selection (ACS) routines through Interactive Storage Management Facility (ISMF) to select data classes that are enabled for compression
4.2 RACF configuration
New authorization checks might need to be performed for users and applications to read and write encrypted data sets. Security administrators fully control over who is allowed to enable (and disable) the encryption of data sets. Security administrators also control who can access the following components:
•Data set
•Encryption key
•Encryption services
4.2.1 Restricting data set encryption to security administrators
By using the FACILITY class, data set encryption can be restricted to only security administrators. This profile with the universal access set to NONE makes data set encryption is unavailable to users who are not explicitly authorized to use it:
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.ENCRYPT UACC(NONE)
Restricting non-security administrators from encrypting data sets ensures that administrators can be sure that encryption is not enabled before the environment is fully configured. Administrators also can be sure that a key management policy is in place, and that they have oversight on which data sets are encrypted with which keys.
4.2.2 Defining DATASET, CSFSERV, CSFKEYS, and other resources
This section describes the following access controls to consider based on your policies for data set encryption:
•Protecting the cryptographic key data set (CKDS)
The data encryption keys that are used for data set encryption are stored in a CKDS.
Access to the VSAM data set for the CKDS is provided by the DATASET resource class. For more information about the DATASET class, see z/OS V2R4 Security Server RACF Security Administrator’s Guide, SA23-2289-40.
 
Note: The DATASET resource that protects the CKDS must not be encrypted with data set encryption because the key is rendered inaccessible at ICSF startup. The keys in the CKDS can be encrypted by using a master key. For more information, see 1.6.2, “IBM Z cryptographic system” on page 15.
The RACF profile that is used for protecting the CKDS data set is listed in Table 4-1 on page 72.
Table 4-1 RACF profile for protecting the CKDS data set
Class
Entry in class
Description
Examples
DATASET
<KDS_dsname>
Allow users access to the CKDS and PKDS data sets
PERMIT
‘<KDS_dsname>’
ID(groupid)
ACCESS(READ)
Protecting encrypted data setsAccess to data sets is provided by the DATASET resource class. For more information about the DATASET class, seez/OS Security Server RACF Security Administrator’s Guide,SA23-2289-40.
For more information about data set encryption, see other resource classes that might be needed, such as CSFKEY, CSFSERV, and FACILITY.
RACF profiles that are used for protecting encrypted data sets are listed in Figure 4-2.
Table 4-2 RACF profiles for protecting encrypted data sets
Class
Entry in class
Description
Examples
DATASET
<dsname>
Allow users access to the data set.
PERMIT ‘<dsname>’
ID(groupid)
ACCESS(READ)
DFP segment to profile
Allow encryption of data set through DFSMS access methods by using a key label that is specified in DFP segment.
 
Note: For data set encryption, a key label can also be supplied by way of other sources, such as JCL and SMS data class.
ALTDSD ‘<dsname>’ UACC(NONE) DFP(RESOWNER(owner) DATAKEY(keylabel_name))
CSFKEYS
**
Protects access to crypto key, enable, and disable, protected key use
*RECOMMENDED* not to use ICSF segment for this profile.
RDEFINE CSFKEYS name
UACC(NONE)
keylabel_name
Protects access to the corresponding key label.
 
Must include ICSF segment with options that are required for data set encryption:
•SYMCPACFWRAP(YES) and
•SYMCPACFRET(YES).
RDEFINE CSFKEYS keylabel_name UACC(NONE)
ICSF(SYMCPACFWRAP(YES) SYMPACFRET(YES))
CSFSERV
*
General access to ICSF services *REQUIRED* UACC(NONE) is recommended
RDEFINE CSFSERV
* UACC(NONE)
 
CSFKRR2
CKDS Key Record Read2 callable service.
 
*REQUIRED* for data set encryption only when CHECKAUTH(YES) is specified in the ICSF installation options data set.
 
CHECKAUTH(NO) is the default.
RDEFINE CSFSERV
CSFKRR2 UACC(READ)
 
FACILITY
STGADMIN.*
Generic entry to protect access to STGADMIN.*, assumed to be created previously.
RDEFINE STGADMIN.* UACC(NONE)
 
STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
Recommended to be defined with UACC(NONE) to restrict any users from attempting to allocate a data set before encryption is fully implemented.
 
With at least read authority, allows creating encrypted data sets by using a key label that is specified through a source other than the DATASET DFP segment.
 
Note: This resource does not protect against creating encrypted data sets by using a key label in the DATASET DFP segment.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
UACC(NONE)
 
STGADMIN.SMS.FAIL.INVALID.DSNTYPE.ENC
Control whether an allocation should succeed or fail if a key label is specified for a DASD data set that is not a supported data set type for data set encryption.
 
Recommended to be defined with UACC(NONE) to prevent allocations from failing if a key label is specified for a data set that is not a supported data set type for data set encryption.
RDEFINE FACILITY STGADMIN.SMS.FAIL.INVALID.DSNTYPE.ENC
UACC(NONE)
 
STGADMIN.SMS.ALLOW.PDSE.ENCRYPT
When the resource name is fully defined, allows the system to treat PDSEs as a supported data set type for data set encryption.
 
Does not require read authority in order to take effect.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.PDSE.ENCRYPT
UACC(NONE)
 
STGADMIN.SMS.ALLOW.DATASET.SEQ.ENCRYPT
When the resource name is fully defined, allows the system to treat sequential basic and large format data sets as supported data set types for data set encryption.
 
Does not require read authority in order to take effect.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.SEQ.ENCRYPT
UACC(NONE)
 
STGADMIN.IGG.DIRCAT
Ability to LISTCAT a data set, which shows the encryption attribute
*OPTIONAL*
 
FIELD
DATASET.DFP.DATAKEY
Controls specification of DATAKEY in DFP segment. Required if FIELD entries are present for data sets.
RDEFINE FIELD
DATASET.DFP.DATAKEY
UACC(NONE)
FACILITY
STGADMIN.*
Generic entry to protect access to STGADMIN.*, assumed to be created previously.
RDEFINE STGADMIN.* UACC(NONE)
STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
Recommended to be defined with UACC(NONE) to restrict any users from attempting to allocate a data set before encryption is fully implemented.
 
With at least read authority, allows creating encrypted data sets by using a key label that is specified through a source other than the DATASET DFP segment.
 
Note: This resource does not protect against creating encrypted data sets by using a key label in the DATASET DFP segment.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
UACC(NONE)
STGADMIN.SMS.FAIL.INVALID.DSNTYPE.ENC
Control whether an allocation should succeed or fail if a key label is specified for a DASD data set that is not a supported data set type for data set encryption.
 
Recommended to be defined with UACC(NONE) to prevent allocations from failing if a key label is specified for a data set that is not a supported data set type for data set encryption.
RDEFINE FACILITY STGADMIN.SMS.FAIL.INVALID.DSNTYPE.ENC
UACC(NONE)
STGADMIN.SMS.ALLOW.PDSE.ENCRYPT
When the resource name is fully defined, allows the system to treat PDSEs as a supported data set type for data set encryption.
 
Does not require read authority in order to take effect.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.PDSE.ENCRYPT
UACC(NONE)
STGADMIN.SMS.ALLOW.DATASET.SEQ.ENCRYPT
When the resource name is fully defined, allows the system to treat sequential basic and large format data sets as supported data set types for data set encryption.
 
Does not require read authority in order to take effect.
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.SEQ.ENCRYPT
UACC(NONE)
STGADMIN.IGG.DIRCAT
Ability to LISTCAT a data set, which shows the encryption attribute
*OPTIONAL*
 
FIELD
DATASET.DFP.DATAKEY
Controls specification of DATAKEY in DFP segment. Required if FIELD entries are present for data sets.
RDEFINE FIELD
DATASET.DFP.DATAKEY
UACC(NONE)
•Protecting key labels
Access to key labels is provided by the CSFKEYS resource class. For more information about the CSFKEYS class, see z/OS Cryptographic Services ICSF Administrator’s Guide, SC14-7506-09.
See other resources that might be used when key labels and associated cryptographic keys, such as XFACILIT and XCSFKEY, are managed.
RACF profiles for protecting key labels are listed in Figure 4-3.
Table 4-3 RACF profiles for protecting key labels
Class
Entry in class
Description
Examples
CSFKEYS
**
Access to crypto key, enable/disable, protected key use
 
*RECOMMENDED* not to use ICSF segment for this profile
RDEFINE CSFKEYS name
UACC(NONE)
DATASET.<dataset_resource>.ENCRKEY.<seqno>
Protects access to the corresponding key label DATASET.<dataset_resource>.ENCRKEY.<seqno>
RDEFINE CSFKEYS keylabel_name UACC(NONE)
ICSF(SYMCPACFWRAP(YES) SYMPACFRET(YES))
XFACILIT
CSF.CSFKEYS.AUTHORITY.LEVELS.FAIL
 
CSF.CSFKEYS.AUTHORITY.LEVELS.WARN
Enables granular key label access; recommended to activate at least WARNING mode and then FAIL mode after ready to implement
 
CSF.XCSFKEY.ENABLE.AES
Allows symmetric key label export for AES keys by using profiles in XCSFKEY class
 
CSF.CKDS.TOKEN.NODUPLICATES
 
Not allow duplicates of key labels *RECOMMENDED*
CSF.KDS.KEY.ARCHIVE.USE
Allows users to use archived keys in cryptographic operations with warning messages and SMF records indicating use. For more information, see 3.5.8, “Deciding whether to archive or delete keys” on page 55.
 
CSF.SSM.ENABLE
Ability for users to change to secure mode
 
XCSFKEY
*
Used when exporting keys; transferring a secure symmetric key to encryption under an RSA key
Checks for entry XFACILIT CFS.XCSFKEY.ENABLE.AES, which is used for exporting of symmetric keys
 
•Protecting crypto services
Access to cryptographic services is provided by the CSFSERV resource class. For more information about the CSFSERV class, see z/OS Cryptographic Services ICSF Administrator's Guide, SC14-7506-09.
RACF profiles for protecting crypto services are listed in Figure 4-4.
Table 4-4 RACF profiles for protecting crypto services
Class
Entry in class
Description
Examples
CSFSERV
*
General access to ICSF services *REQUIRED* UACC(NONE) is recommended
RDEFINE CSFSERV
* UACC(NONE)
CSFBRCK
ICSF panel utility - CKDS KEYS - Browse CKDS (option 5.5)
 
CSFKGUP
ICSF panel utility- Key Generator Utility Program
 
CSFKGN
Key Generate callable service
 
CSFKRR2
CKDS Key Record Read2 callable service
 
CSFKRC2
CKDS Key Record Create2 callable service
 
CSFREFR
ICSF panel utility - Refresh CKDS using ISPF panels
 
CSFCRC
Coordinated Change Master Key and Coordinated Refresh KDS panel utilities, Coordinated KDS Administration callable service
*RECOMMENDED* to turn on AUDIT(ALL)
RDEFINE CSFSERV
CSFCRC
UACC(NONE)
AUDIT(ALL)
CSFDKCS
ICSF panel utility - Load master keys using ISPF panels
*RECOMMENDED* to turn on AUDIT(ALL)
See CSFCRC example
CSFSMK
ICSF panel utility - Set master keys using ISPF panels
*RECOMMENDED* to turn on AUDIT(ALL)
See CSFCRC example
CSFCMK
ICSF panel utility - Change master keys using ISPF panels
*RECOMMENDED* to turn on AUDIT(ALL)
See CSFCRC example
•Protecting operator commands
Access to MVS operator commands is provided by the OPERCMDS resource class. For more information about the OPERCMDS class, see z/OS Security Server RACF Security Administrator’s Guide, SA23-2289-40.
RACF profiles for protecting operator commands with a brief description of each class, a list of optional profiles, and a sample entry, are listed in Figure 4-5.
Table 4-5 RACF profiles for protecting operator commands
Class
Entry in class
Description
Examples
OPERCMDS
MVS.DISPLY.ICSF
Allow users to enter D ICSF commands
RDEFINE
MVS.DISPLAY.ICSF
CLASS(OPERCMDS)
UACC(NONE)
MVS.SETICSF.*
Allow users to enter SETICSF commands, for example SETICSF OPT,REFRESH
RDEFINE
MVS.SETICSF
CLASS(OPERCMDS)
UACC(NONE)
•Ability to LISTCAT an encrypted data set to show catalog encryption attribute
Access to LISTCAT is provided by the STGADMIN.IGG.DIRCAT resource in the FACILITY resource class. For more information about the FACILITY class, see Storage Administration (STGADMIN) Profiles in the FACILITY Class.
An RACF profile for showing catalog encryption attribute is listed in Figure 4-6.
Table 4-6 RACF profiles for showing catalog encryption attribute
Class
Entry in class
Description
Examples
FACILITY
STGADMIN.*
Generic entry assumed to be created previously
UACC(NONE)
STGADMIN.IGG.DIRCAT
Ability to LISTCAT a data set that shows the encryption attribute
 
Protecting ICSF start and stop
It is imperative to have tight controls in place to protect the use of z/OS and JES2 commands to START, STOP, or FORCE ICSF. You might also want to control the use of command SETICSF and perform the following tasks:
•Ensure that the OPERCMDS class is active and RACLISTed and that RACLIST processing is enabled.
•Define the OPERCMDS class profile by using a security product; for example, RACF.
•Grant ICSF access to the OPERCMDS class and then refresh the OPERCMDS class.
Some RACF profiles that restrict who can issue the START, STOP, FORCE, or SETICSF operator commands are described next (see Example 4-1).
 
Note: ICSF does not support the CANCEL or MODIFY operator commands.
Example 4-1 Operator commands to restrict
MVS.START.STC.ICSF.*
MVS.START.STC.ICSF
 
MVS.STOP.STC.ICSF.*
MVS.STOP.STC.ICSF
 
MVS.FORCE.STC.ICSF.*
MVS.FORCE.STC.ICSF
 
MVS.SETICSF.*
Replace ICSF with your actual proc name; for example, CSF if it is different in your installation.
Typically, RACF generic profiles are available that restrict who can issue the MVS START, STOP, and FORCE commands. The specific PERMIT command that you must issue depends on how your RACF administrator defined the profiles in class OPERCMDS to protect these commands.
Alternatively, you can create profiles in class OPERCMDS and permit the necessary access. The sample job performs this task by defining new profiles (see Example 4-2).
Example 4-2 Sample job defining new profiles
RDEFINE OPERCMDS MVS.START.STC.ICSF*.** UACC(NONE) OWNER(SECADM)
PERMIT MVS.START.STC.ICSF*.** CLASS(OPERCMDS) RESET
PERMIT MVS.START.STC.ICSF*.** CLASS(OPERCMDS) +
ID(ICSFADM) ACCESS(UPDATE)
SETROPTS RACLIST(opercmds) REFRESH
You must repeat the same commands and profiles for the STOP, FORCE, and SETICSF commands.
For more information about protecting operator commands, see Planning MVS operations.
For more information about controlling the use of operator commands, see Administering the use of operator commands.
For more information related to these services, see z/OS Cryptographic Services.
System Display and Search Facility
System Display and Search Facility (SDSF) generates console commands (z/OS or JES) when the rules you established to SDSF dictate that the user is allowed to stop or purge the job. If the JESSPOOL class is active, the user’s authority to the JESSPOOL profile that is protecting the job determines whether SDSF generates the command on behalf of the user. If JESSPOOL is inactive, the native SDSF controls in ISFPARMs or the SDSF statements control if the user is authorized to the job.
If the user is authorized from the SDSF perspective, SDSF generates and issues the command on the user’s behalf under the users own ID, but originating from the SDSF console. By using this method, you can authorize the console commands that are generated by SDSF, as shown in the following example:
PERMIT JES2.STOP.ICSF CLA(OPERCMDS) ID(*) WHEN(CONSOLE(SDSF))
This command allows an SDSF generated stop command to run.
If the user directly issues the command on their own (you gave them console access or the / command in SDSF), it does not originate from CONSOLE SDSF.
4.2.3 Setting a policy to control the use of archived keys
Archiving data set encryption keys is preferred over deletion because archived keys can be recalled later, if needed.
When a key is archived, an SMF Type 82 Subtype 30 record is created for each attempted use and an optional job log message is displayed.
You can decide to allow or deny archived keys to be used for cryptographic operations with the CSF.KDS.KEY.ARCHIVE.USE resource in the XFACILIT class. When that resource is defined, ICSF allows archived keys to be used for crypto operations. When that resource is undefined, ICSF fails any attempts to use an archived key.
4.2.4 Configuring the RACF environment for key generation
The following methods are available to generated keys. RACF authorization is required to perform key generation by using the following methods:
•EKMF1
•ICSF Panels
•ICSF APIs
•ICSF KGUP
•TKE
CSFSERV
For all methods, the CSFSERV class must be active and RACLISTed. It should also be enabled for generic use. To enable CSFSERV for generics, use:
SETROPTS CLASSACT(CSFSERV)
SETROPTS RACLIST(CSFSERV)
SETROPTS GENERIC(CSFSERV)
The CSFSERV class should be initially set to disallow access to all users, as shown in the following example:
RDEFINE CSFSERV * UACC(NONE)
Granting access to CSFSERV resources depends on the key generation method. The process includes the following steps:
1. Define the profiles.
 – For ICSF KGUP:
RDEFINE CSFSERV CSFKGUP UACC(NONE)
RDEFINE CSFSERV CSFKGN UACC(NONE)
 – For ICSF Panel Utilities and APIs:
RDEFINE CSFSERV CSFKGN UACC(NONE)
RDEFINE CSFSERV CSFKRC2 UACC(NONE)
RDEFINE CSFSERV CSFKRR2 UACC(NONE)
2. Grant the users (preferably groups) access permission as shown in the following example:
 – For ICSF KGUP:
PERMIT CSFKGUP CLASS(CSFSERV) ID(groupid) ACCESS(READ)
PERMIT CSFKGN CLASS(CSFSERV) ID(groupid) ACCESS(READ)
 – For ICSF Panel Utilities and APIs
PERMIT CSFKGN CLASS(CSFSERV) ID(groupid) ACCESS(READ)
PERMIT CSFKRC2 CLASS(CSFSERV) ID(groupid) ACCESS(READ)
PERMIT CSFKRR2 CLASS(CSFSERV) ID(groupid) ACCESS(READ)
3. Refresh the class, as shown in the following example:
SETROPTS RACLIST(CSFSERV) REFRESH
CSFKEYS
For all methods, the CSFKEYS class must be active and RACLISTed. It should also be enabled for generic use. To enable CSFSERV for generics, use:
SETROPTS CLASSACT(CSFKEYS)
SETROPTS RACLIST(CSFKEYS)
SETROPTS GENERIC(CSFKEYS)
Activating the CSFKEYS class is the only preparation step. For more information about granting access to the CSFKEYS resources, see 5.7, “Granting access to encrypted data sets” on page 138.
4.3 ICSF configuration
z/OS data set encryption requires key labels and data-encrypting2 keys to be defined in an ICSF CKDS. To create an encrypted data set, a key label must be supplied on new data set allocation. The key label must point to an AES 256-bit data-encrypting key to be used for encryption and decryption.
For each encrypted data set, its key label is stored in the data set catalog. The key label is not typically considered sensitive information; however, it identifies the data set encryption key, which is sensitive. Therefore, the use of secure keys is recommended.
Data-encrypting keys are enciphered with a master key to create a secure key that is stored in CKDS. The master key is stored securely in the HSM of an assigned Crypto Express adapter. When a secure key is later accessed, the master key is used in the transformation to a protected key, as described in 3.5.6, “Using protected keys for high-speed encryption” on page 51.
Data set encryption is flexible, which allows as much granularity as wanted when key labels are identified for data sets. The number of key labels and encryption keys that are used across z/OS data sets is unlimited.
The data set encryption management process is provided by z/OS through SAF (interfacing with RACF3), ICSF, DFSMS, and EKMF.
Key labels that are used to retrieve secure keys
Every record in the ICSF CKDS includes an associated key label. When applications or z/OS components start ICSF callable services, the application can specify a key label by way of a parameter to identify the key for the callable service to use.
After a key label is stored in the catalog for an encrypted data set, it cannot be altered. Any subsequent change to SAF or RACF data set profile or data class does not affect existing data sets. This approach ensures that data cannot be tampered with.
SAF or RACF policies define the users that are authorized to use distinct key labels and ICSF callable services. The CSFKEYS resource class controls access to cryptographic keys in the ICSF CKDS and enables the use of protected key. The CSFSERV resource class controls access to ICSF callable services.
How a key label is used to retrieve a secure key from CKDS to be unwrapped by a Crypto Express adapter is shown in Figure 4-1.
Figure 4-1 Using a key label to retrieve a secure key from CKDS
The following key label process steps are shown in Figure 4-1:
1. At data set allocation, DFSMS checks if a key label exists in the DATASET class profile, which protects the data set and saves the key label.
2. At data set open, DFSMS checks if the user is authorized to the class resource that protects the saved key label.
3. DFSMS specifies the saved key label to ICSF and requests to retrieve the secure key from the CKDS.
4. ICSF uses the key label that is specified by DFSMS to locate the secure key in the CKDS.
5. ICSF calls the Crypto Express adapter to convert the secure key to a protected key by using the master key.
For more information about creating a protected key from a secure key, see 3.5.6, “Using protected keys for high-speed encryption” on page 51.
4.3.1 Configuring Crypto Express adapters
To use Crypto Express adapters with ICSF, they must be configured online and assigned to the appropriate LPARs. Each Crypto Express adapter supports multiple cryptographic domains. Each domain can be assigned a unique master key, which prevents access to the key material from other domains.
The maximum number of domains matches the maximum number of LPARs that is available on the server. For example, the z14 supports up to 85 LPARs; therefore, the Crypto Express adapters support up to 85 domains.
For z/OS data set encryption, at least two Crypto Express adapters must be configured as CCA coprocessors.
4.3.2 Creating a Common Record Format (KDSR) CKDS
A CKDS can be created or converted to a common record format (KDSR) format. Any system that shares the KDSR format key data set must be running ICSF FMID HCR77A1 or later. For more information, see 3.4.3, “Using the Common Record Format (KDSR) cryptographic key data set” on page 47.
The first step is to allocate a KDSR format CKDS. The CKDS must be a key-sequenced data set and must be allocated on a permanently resident volume.
The sample job in SYS1.SAMPLIB(CSFCKD3) can be used as a template. Our JCL is shown in Example 4-3.
Example 4-3 Job to define a new cluster
//DEFINE EXEC PGM=IDCAMS,REGION=4M
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER (NAME(PLEX75.SHARED.COPY.SCSFCKDS) -
VOLUMES(BH5CAT) -
RECORDS(500 50) -
RECORDSIZE(372,2048) -
KEYS(72 0) -
FREESPACE(10,10)           -
SHAREOPTIONS(2,3)) -
DATA (NAME(PLEX75.SHARED.COPY.SCSFCKDS.DATA) -
BUFFERSPACE(100000) -
                  ERASE)                     -
            INDEX (NAME(PLEX75.SHARED.COPY.SCSFCKDS.INDEX))
/*
ICSF CKDS must include a single volser that is specified in the VOLUMES parameter. Do not code more than one volume or specify VOLUME(*).
Converting a CKDS
If CKDS is available to convert to KDSR format, the conversion can be done by calling the CSFCRC callable service or by using the ICSF panels. While the conversion is happening, all updates to the key data set that is converted are suspended.
At the end of the conversion, all systems in the sysplex that share the key data set use the KDSR format key data set as the active key data set. All new updates are made to the KDSR format key data set.
Complete the following steps to convert a key data set to KDSR format by using the ICSF panels:
1. In the ICSF Primary Menu panel, select option 2 KDS MANAGEMENT and press Enter.
2. In the ICSF Key Data Set Management panel, select the type of key data set option 6 COORDINATED CKDS CONVERSION and press Enter.
3. In the next panel, select the COORDINATED xKDS CONVERSION option and press Enter.
4. When the ICSF Coordinated KDS conversion panel appears, complete the required fields and press Enter.
5. Specify the new KDSR format CKDS to switch to (see Example 4-4 on page 83) then press Enter to perform a dynamic, nondisruptive conversion.
Example 4-4 Coordinated KDS conversion panel
---------------------- ICSF - Coordinated KDS conversion ----------------------
COMMAND ===>
To perform a coordinated KDS conversion, enter the KDS names below
and optionally select the rename option.
KDS Type ===> CKDS
Active KDS ===> 'PLEX75.SHARED.SCSFCKDS'
New KDS ===> 'PLEX75.SHARED.NEW'SCSFCKDS'
Rename Active to Archived and New to Active (Y/N) ===> Y
Archived KDS ===> 'PLEX75.SHARED.OLD'SCSFCKDS'
Create a backup of the converted KDS (Y/N) ===> N
Backup KDS ===>
Press ENTER to perform a coordinated KDS conversion.
Press END to exit to the previous menu.
4.3.3 CSFPRMxx and installation options
The CSFPRMxx member in PARMLIB contains the installation options that are used for ICSF initialization. A sample CSFPRMxx for z/OS data set encryption is shown in Example 4-5. The CKDS in our example is shared with other systems.
Example 4-5 CSFPRMxx options
CKDSN(PLEXNAME.NEW.SCSFCKDS)
SYSPLEXCKDS(YES,FAIL(YES))
CHECKAUTH(NO)
AUDITKEYLIFECKDS(TOKEN(YES),LABEL(YES))
AUDITKEYUSGCKDS(TOKEN(YES),LABEL(YES),INTERVAL(24))
KEYARCHMSG(YES)
KDSREFDAYS(1)
STATS(ENG,SRV,ALG)
STATSFILTERS(NOTKUSERID)
If you do not intend to share the CKDS across multiple systems, the following option is used:
CKDSN($SYSNAME.NEW.SCSFCKDS)
The SYSPLEXCKDS option can be used for a single system or multi-system sysplex.
Display the current options and defaults by using the ICSF utility panel option 3.1 (OPSTAT options) or the D ICSF,OPT command. For more information, see 8.2, “Viewing ICSF options” on page 170.
For a complete list and more information about default values, see z/OS Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide, SC14-7507.
The following settings are available:
•CKDSN
The name of the VSAM data set for the CKDS.
•SYSPLEXCKDS
Enables the current ICSF instance to join the CKDS sysplex and synchronize updates with other ICSF instances with the same CKDSN.
•CHECKAUTH
The recommended setting for CHECKAUTH is NO. Access to CSFKEYS, CSFSERV, and XCSFKEYS resources are not checked for authorized callers. This setting increases crypto throughput and improves performance.
•AUDITKEYLIFECKDS, AUDITKEYUSGCKDS
Enables auditing for key lifecycle events and key usage events.
•KEYARCHMSG
Specify YES for ICSF to issue a console message when an archived key is attempted to be used in a cryptographic operation. ICSF creates an SMF Type 82 Subtype 30 record, which indicates the attempted use whether KEYARCHMSG is enabled or disabled.
•KDSREFDAYS
The common record format (KDSR) for the CKDS can be used to take advantage of the extra metadata and use the key usage and key lifecycle audit records. The key usage, key lifecycle, and crypto usage statistics must be turned on in the CSFPRMxx PARMLIB member.
KDS Key Utilization Statistics provides the following capabilities:
 – A new key record format (KDSR) for internally saving metadata and statistics about each cryptographic key is available.
 – The Coordination KDS Administration (CSFCRC and CSFCRC6) callable service was enhanced to perform a coordinated conversion of an old format *KDS to the new KDSR format. Included in this new record format is a section tracked the last referenced date for each cryptographic key.
 – The reference date is the last time that a record was used in a cryptographic operation or read, such that the retrieved key might be used in a cryptographic operation. Because the read is interpreted as a show of interest, the reference date is updated.
 – A new ICSF startup option, KDSREFDAYS(n), was added that specifies (in days) how often a record should be written for a reference date and time change.
KDSREFDAYS(0) means that ICSF does not track key reference dates. The default is KDSREFDAYS(1) and the maximum value that is allowed is KDSREFDAYS(30).
•STATS, STATSFILTERS
Crypto usage tracking can be controlled with the STATS and STATSFILTERS options. The STATS option enables usage tracking for various cryptographic statistics.
 
Note: SMF must be configured to record ICSF events and set the time interval for recording. Also, ICSF must be configured to track the wanted usage statistics.
For more information about configuring SMF, see 4.4.2, “Configuring SMF recording options in SMFPRMxx” on page 106.
Keywords can be combined to track multiple statistics. If the STATS option is not specified, usage tracking is not performed. The STATS and STATSFILTERS parameters use the following syntax:
STATS(ENG,SRV,ALG)
STATSFILTERS(NOTKUSERID)
The following STATS parameter values available:
•ENG enables usage tracking of cryptographic engines and supports Crypto Express coprocessors, Regional Cryptographic Servers, CP Assist for Cryptographic Functions (CPACF), and cryptographic software.
•SRV enables usage tracking of ICSF callable services and UDXes.
•ALG enables usage tracking of the cryptographic algorithms that are referenced in cryptographic operations.
 
Tip: The ALG option can help you identify users that are using weak keys (such as DES).
Limited support is available for key generation, key derivation, and key import.
STATSFILTERS controls the identifier that is used to collect usage information. Usage is tracked by unique user and job identifiers. The user identifier consists of an address space user ID and a task level user ID.
For applications, such as CICS that can generate a unique task level user ID for each transaction, many SMF records can be generated. To prevent this problem, use the STATSFILTER(NOTKUSERID) option. Specifying STATSFILTER(NOTKUSERID) ignores the task level user ID and uses only the address space user ID when the job or user identifier is created.
STATSFILTER(NOTKUSERID) reduces the number of SMF records that are written.
The SETICSF OPT,STATS command can be used to enable STATS, as shown in Example 4-6.
Example 4-6 Output of the SETICSF command
SETICSF OPT,STATS=(ENG,SRV,ALG),SYSPLEX=NO
CSFM667I 13.27.39 SETICSF Options 802
STATS:
SC60 : ENG, SRV, ALG
4.3.4 Starting and stopping ICSF
ICSF runs as a started task on z/OS. A sample started task from SYS1.SAMPLIB(CSF) is shown in Example 4-7.
Example 4-7 Sample ICSF started task
//CSF PROC
//CSF EXEC PGM=CSFINIT,REGION=0M,TIME=1440,MEMLIMIT=NOLIMIT
//CSFPARM DD DSN=SYS1.PARMLIB(CSFPRM00),DISP=SHR
The CSFPARM DD statement points to the CSFPRMxx PARMLIB member that contains the ICSF installation options.
To start ICSF, issue the START CSF,SUB=MSTR command.
 
Note: ICSF must be started before any components that intend to access encrypted data sets (for example, SMF data sets or data sets that are used during z/OS initialization). For more information, see 3.4.2, “Starting ICSF early in the IPL process” on page 46.
To stop ICSF, issue the STOP CSF command.
Verifying that ICSF is running
You should verify that the ICSF address space is up and running and that it was started with no error. To verify that the ICSF address space is up and running, use command DISPLAY JOB,ICSF (or CSF, depending on your PROC name), as shown in Example 4-8.
Example 4-8 DISPLAY JOB,ICSF with results
DISPLAY JOB,CSF
CNZ4106I 14.50.30 DISPLAY ACTIVITY 604
JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS
00003 00037 00006 00037 00011 00006/00030 00022
CSF CSF NSW S A=002C PER=NO SMC=000
PGN=N/A DMN=N/A AFF=NONE
CT=002.211S ET=00333.31
WUID=STC05636 USERID=IBMUSER
WKL=SYSTEM SCL=SYSSTC P=1
RGP=N/A SRVR=NO QSC=NO
ADDR SPACE ASTE=3E603B00
Review the ICSF the SYSLOG and check that you see the following messages:
CSFM126I CRYPTOGRAPHY - FULL CPU-BASED SERVICES ARE AVAILABLE
CSFM001I ICSF INITIALIZATION COMPLETE
4.3.5 Loading the AES master key
Master keys should be managed by two or more key officers. Each key officer generates and owns their master key part. All key parts must be entered (in any order) to assemble the final key part. In this way, no single person has the entire master key.
The following high-level process is used to load the new master key registers:
1. Generate a random number for the AES master key part.
2. Generate a checksum for the AES master key part.
3. Load the first AES master key part.
4. Repeat Steps 1 -3 for the wanted number of middle key parts.
5. Load the final AES master key part.
6. Generate and load the remaining master keys.
7. Verify the new master key registers.
This process is shown in Figure 4-2.
Figure 4-2 Steps to loading a new master key
Attention: Although this scenario shows a change of MASTER KEY for AES, the process is the same for all other types of master keys (DES, RSA, and ECC).
Checking the status of the master key register
Complete the following steps to check the AES master key:
1. From the ICSF Main panel, choose Option 5 Utility and press Enter (see Figure 4-3).
Figure 4-3 ICSF main panel
2. Check that the new master key register is empty by selecting action character to s (status) and press Enter (see Figure 4-4).
Figure 4-4 Check status of new master key register
3. View the register status on the Coprocessor Hardware status panel (see Figure 4-5).
Figure 4-5 Register status
Generating a checksum for the AES master key part
Complete the following steps to generate a checksum:
1. In the ICSF Utilities panel, select Option 3 - Random and press Enter (see Figure 4-6).
Figure 4-6 ICSF Utilities panel Option 3
2. View the Random Number Generator (RNG) panel (see Figure 4-7), which includes Random Number 1 - 4 with all 0s.
Figure 4-7 Random Number Generator panel entries all zeros
3. Press F1 for Help (see Figure 4-8).
Figure 4-8 Help panel
4. Press F3 to return to the Random Number Generator panel. Enter RANDOM and then, press Enter. The new random numbers that are generated are shown in Figure 4-9.
Figure 4-9 New random numbers generated
5. Press F3 to return to the Random Number Generator panel and choose Option 4 - Checksum. The Checksum Panel with the random numbers pre-populated is shown in Figure 4-10.
Figure 4-10 Checksum panel
6. Press F1 for Help. Choose Option 1 for Key Type (see Figure 4-11).
Figure 4-11 Selecting key type from Help panel
7. View the possible key type values and lengths (see Figure 4-12).
Figure 4-12 Key types
8. Press F3 to return to the Checksum panel. Enter AES-MK for the key type and press Enter (see Figure 4-13).
 
Note: Use AES-MK for data set encryption.
Figure 4-13 Keys with type AES-MK
 
Important: It is strongly recommended to save a copy of the key value and checksum, otherwise the master key cannot be recreated and you will not be able to decrypt your data, if the key gets lost.
9. Press F3 to return to the Utility Panel. Press F3 to return to the ICSF Main panel.
Loading the first AES Master Key part
Complete the following steps to load the first AES Master Key part:
1. Select Option 1 - Coprocessor Management from the ICSF Main panel. The Coprocessor Management panel is shown in Figure 4-14.
Figure 4-14 Coprocessor Management Panel
2. Press F1 for Help, scroll down (by pressing Enter) to see the Master Key State definitions (see Figure 4-15).
Figure 4-15 Cryptographic Coprocessor master key states
3. Press F3 to return to the Coprocessor Management panel. Enter s next to the crypto feature to view its status (see Figure 4-16).
Figure 4-16 Return to ICSF Coprocessor Management panel
The Coprocessor Hardware Status panel is shown in Figure 4-17. Notice that the new master key register is empty.
Figure 4-17 Coprocessor Hardware Status panel with empty New Master Key register
4. Press F3 to return to the Coprocessor Management panel. In the Coprocessor Management panel, enter e next to the crypto feature to enter key parts (see Figure 4-18) and press Enter.
 
Note: To simultaneously load multiple Crypto Express adapters (that are assigned to the current LPAR or domain) with the same master key, enter e next to all of the necessary cryptographic adapters and press Enter.
Figure 4-18 Coprocessor Management panel with e by a crypto feature
5. You see the Master Key Entry panel. For the Key Type, enter AES-MK; for Part, enter first; and for Checksum enter, DA (see Figure 4-19). Then, press Enter.
Figure 4-19 Master Key Entry panel
6. Check the new master key register status; in our example, it is PART FULL (see Figure 4-20).
Figure 4-20 Master Key Entry - Part Full
Generating the wanted number of middle parts
Repeat the following steps for the wanted number of key parts:
Repeat the steps for each intermediate AES master key part. Each key custodian generates and loads (and securely saves) the following individual key parts:
•Generate a random key (and save the results) by using ICSF Option 5.3.
•Generate a checksum, VP (and save the results) by using ICSF Option 5.4.
•Load the key part into the new master key register by using ICSF Option 1.e (with part value entered as MIDDLE).
After all intermediate (middle) key parts are generated and saved, the final AES master key part must be loaded. This process is described next.
Loading the final AES master key part
Complete the following steps to load the final AES master key part:
1. Choose Option 1 - Coprocessor Management panel from the ICSF Main panel. In the Coprocessor Management panel, enter e next to the crypto feature to enter the final key part (see Figure 4-21). Press Enter.
Figure 4-21 Coprocessor Management panel (final part)
2. Use the Random Number Generator to generate numbers for the final part. In the Parity Option, enter RANDOM and press Enter (see Figure 4-22).
Figure 4-22 Random Number Generator for final part
3. In the Checksum and Verification and Hash Pattern panel, enter AES-MK for the Key Type (see Figure 4-23). Press Enter.
Figure 4-23 Checksum and Verification and Hash Pattern panel before Checksum
The results of final key part generation are shown in Figure 4-24.
Figure 4-24 Checksum and Verification and Hash Pattern panel with final key part
4. In the Master Key Entry panel, enter AES-MK for the Key Type. Enter FINAL for the Part type, and enter C2 for Checksum (see Figure 4-25 on page 98). Press Enter.
 
Note: If you enter an incorrect checksum value, ICSF warns you with a message “Incorrect checksum value” in the upper right corner of the panel. Ensure that you enter the correct value that was reported as the generated checksum value.
Figure 4-25 Master Key Entry panel set final part
5. Check the Master Key Entry panel for the new master key register. Confirm that the status is FULL and the final key part VP matches the checksum value (see Figure 4-26).
Figure 4-26 Master Key full
6. Press F3 to return to the Coprocessor Management panel. Enter s next to the crypto feature to view the status (see Figure 4-27). Press Enter.
Figure 4-27 Coprocessor Management check full key
7. Review the Coprocessor Hardware Status panel (see Figure 4-28 on page 99), which shows the new master key register as FULL.
Figure 4-28 Coprocessor Hardware Status with full key
If other members in your sysplex share the CKDS and use a different domain number, repeat the process for each member of the sysplex (except for steps 1 and 2).
In this scenario, these steps were not repeated for the second member (SC75) of the sysplex, which is sharing the CKDS. When we attempted to perform the coordinated master key change, we received the error messages that are shown in Figure 4-29.
Figure 4-29 Environment error
The master keys incorrect error is shown in Example 4-9.
Example 4-9 New master key incorrect
CSFM615I COORDINATED CHANGE-MK FAILED. NEW MASTER KEYS INCORRECT ON
SC75. RC = 12, RSN = 3098.
IEF196I CSFM615I COORDINATED CHANGE-MK FAILED. NEW MASTER KEYS
IEF196I INCORRECT ON SC75. RC = 12, RSN = 3098.
CSFM636I SYSTEM SC75 FAILURE FOR COORDINATED CKDS ACTIVITY. MSGTYPE=00
0001 RC=12 RSN=3098.
CSFM616I COORDINATED CHANGE-MK FAILED, RC=0000000C RS= 00000C1A
SUPRC= 00000000 SUPRS= 00000000 FLAGS= 48000000.
CSFU006I CHANGE-MK FEEDBACK: RC=0000000C RS=00000C1A SUPRC=00000000
SUPRS=00000000 FLAGS=48000000.
IEF196I CSFU006I CHANGE-MK FEEDBACK: RC=0000000C RS=00000C1A
IEF196I SUPRC=00000000 SUPRS=00000000 FLAGS=48000000.
If your system is using multiple coprocessors, they must have the same master keys. When you load a new master key in one coprocessor, you load the same new master key in the other coprocessors. Therefore, to reencipher a key data set under a new master key, the new master key registers in all coprocessors must contain the same value.
Optionally, generating and loading the remaining master keys
Only the AES master key is required for z/OS data set encryption. If you need more master keys for other crypto applications, complete the following steps for the necessary master keys (such as DES, RSA, and ECC) and each key custodian or key part:
1. Generate a random key (and save the results) by using ICSF Option 5.3.
2. Generate a checksum, VP, HP (and save the results) by using ICSF Option 5.4.
3. Load the key part into the new master key register by using ICSF Option 1.e.
4. Repeat steps 1-3 for each key part.
5. Repeat steps 1-4 for each master key type.
When you start or reencipher a CKDS or PKDS, ICSF places the verification pattern for the master keys into the key data set header record.
Verifying the new master key registers
View the master key entry panel because it should be FULL for AES new master key register if you followed the previous steps. If you repeated the steps for DES, RSA, and ECC, their status also is FULL.
4.3.6 Initializing the CKDS
CKDS initialization involves storing the master key verification pattern (MKVP) in the header record of the CKDS. The CKDS must be allocated before initialization (for more information, see 3.4, “ICSF administration considerations” on page 45). After the AES master key is loaded, the CKDS can be initialized.
CKDS initialization can be performed by using the CKDS Management ICSF panel (see Example 4-10 on page 101).
Example 4-10 CKDS Management Panel
---------------------------- ICSF - CKDS Management ---------------------------
OPTION ===> 1
Enter the number of the desired option.
1 CKDS OPERATIONS - Initialize a CKDS, activate a different CKDS,
(Refresh), or update the header of a CKDS and make
it active
2 REENCIPHER CKDS - Reencipher the CKDS prior to changing a symmetric
master key
3 CHANGE SYM MK - Change a symmetric master key and activate the
reenciphered CKDS
4 COORDINATED CKDS REFRESH - Perform a coordinated CKDS refresh
5 COORDINATED CKDS CHANGE MK - Perform a coordinated CKDS change master key
6 COORDINATED CKDS CONVERSION - Convert the CKDS to use KDSR record format
7 CKDS KEY CHECK - Check key tokens in the active CKDS for format errors
Press ENTER to go to the selected option.
Press END to exit to the previous menu.
4.3.7 Verifying the ICSF Configuration   
This section helps you determine whether the following building blocks are operational:
•ICSF Options
•CKDS Initialization
•Active Master Key
The Cryptographic Services ICSF: System Programmer’s Guide provides helpful hints for ICSF first-time startup.
For more information about a checklist for first-time startup, see Checklist for first-time startup of ICSF.
Checking the ICSF job log
The ICSF address space job log shows which crypto hardware function is available.
 
Note: When you start ICSF with SUB=MSTR (as recommended), you cannot access the ICSF job log by using the System Display and Search Facility (SDSF) or vendor products, such as (E)JES. In this instance, you cannot browse the content of the ICSF job log.
When you display the ICSF address space job log, you can expect to see the messages that are shown in Example 4-11.
Example 4-11 ICSF address space job log
CSFM129I MASTER KEY DES ON CRYPTO EXPRESS6 COPROCESSOR 6C00, SERIAL NUMBER DV785
CSFM129I MASTER KEY AES ON CRYPTO EXPRESS6 COPROCESSOR 6C00, SERIAL NUMBER DV785
CSFM129I MASTER KEY RSA ON CRYPTO EXPRESS6 COPROCESSOR 6C00, SERIAL NUMBER DV785
CSFM129I MASTER KEY ECC ON CRYPTO EXPRESS6 COPROCESSOR 6C00, SERIAL NUMBER DV785
CSFM111I CRYPTOGRAPHIC FEATURE IS ACTIVE. CRYPTO EXPRESS6 COPROCESSOR 6C00, SERI
CSFM111I CRYPTOGRAPHIC FEATURE IS ACTIVE. CRYPTO EXPRESS6 ACCELERATOR 6A01, SERI
CSFM130I CRYPTOGRAPHY - RSA SERVICES ARE AVAILABLE.
CSFM130I CRYPTOGRAPHY - ECC SERVICES ARE AVAILABLE.
CSFM133I THERE ARE NO ACTIVE PKCS11 COPROCESSORS.
CSFM015I FIPS 140 SELF CHECKS FOR PKCS11 SERVICES SUCCESSFUL.
CSFM009I NO ACCESS CONTROL AVAILABLE FOR ICSF SERVICES OR KEYS
CSFM400I CRYPTOGRAPHY - SERVICES ARE NOW AVAILABLE.
CSFM130I CRYPTOGRAPHY - DES 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=HCR77C1.
The following messages are shown in Example 4-11 on page 101:
•A Master key was loaded (messages CSFM129I).
•The CCA Crypto Express is active (messages CSFM111I).
•AES services are available to generate AES DATA or CIPHER keys (message CSFM127I).
•CPACF services are available for protected keys that are used by data set encryption (message CSFM126I).
Viewing ICSF Options
After ICSF is started, you can view the current usage settings from the ICSF Installation Option Display panel or the operator console.
STATS
STATS information can also be obtained by issuing the Display ICSF command from the system console. STATSFILTERS information is not displayed. All usage (engines, services, and algorithms) that is being tracked on SC60 (also known as PLEX60) is shown in Example 4-12.
Example 4-12 Command D ICSF,OPT
D ICSF,OPT
CSFM668I 11.06.42 ICSF OPTIONS 744
SYSNAME = SC60 ICSF LEVEL = HCR77C1
LATEST ICSF CODE CHANGE = 12/06/17
.
.
.
STATS:
SC60 ENG, SRV, ALG
Changing ICSF Options
After ICSF is started, the SETICSF command can be used to dynamically change ICSF options.
SETICSF OPT,STATS
To change the cryptographic usage settings to monitor only crypto engine usage across a sysplex, issue the SETICSF OPT,STATS=(ENG),SYSPLEX=YES command.
To stop all cryptographic usage tracking, issue the SETICSF OPT,STATS=NONE,SYSPLEX=YES command.
 
Note: STATSFILTERS is not supported. You can use SETICSF OPT,REFRESH to change the setting of STATSFILTERS
SETICSF OPT,REFRESH
To refresh common options that were updated in the CSFPRMxx PARMLIB member, issue the SETICSF OPT,REFRESH command. For more information about supported options for refresh, see SETICSF.
Displaying the CKDS state
You can use z/OS command D ICSF,KDS to obtain more information about your KDS status, as shown in Example 4-13.
Example 4-13 Using the D ICSF,KDS command
D ICSF,KDS
CSFM668I 13.36.58 ICSF KDS 551
CKDS SYS1.SC60NEW.SCSFCKDS
FORMAT=KDSR SYSPLEX=N MKVPs=DES AES
PKDS SYS1.SC60NEW.SCSFPKDS
FORMAT=KDSR SYSPLEX=N MKVPs=RSA ECC
No TKDS was provided.
The system displays the following information (message CSFM668I) about the active key data sets (KDS) on the system or sysplex:
•The data set name for each active KDS (CKDS, PKDS, and TKDS).
•The format of the KDS (for example, KDSR is the recommended format to use).
Possible values are KDSR, FIXED, and VARIABLE.
•The communication level in place for the KDS (for example, 3). This information is displayed in a sysplex environment only.
•Whether the KDS is being shared in a sysplex group (for example, Y/N).
•The MKVPs initialized in the KDS (for example, DES AES).
The following values are used:
 – DES, AES, or both for CKDS
 – RSA, ECC, or both for PKDS
 – P11, RCS, or both for TKDS
Displaying the master key state
The use of the D ICSF,MKS command displays the status of the master key registers (see Example 4-14).
Example 4-14 D ICS,MKS command and results
D ICSF,MKS
CSFM668I 13.38.20 ICSF MKS 566
SYSNAME: SC60 DOMAIN: 084 CPC Name: CETUS
FEATURE SERIAL# STATUS AES DES ECC RSA P11
6C00 DV785304 Active A A A A
The CCA feature device number (6C00), its serial number (DV785304), its status (active), and the master keys that are loaded (AES for our purpose) are shown in Example 4-14 on page 103.
Displaying the Crypto Express adapter status
The use of the D ICSF,CARDS command provides more information about the crypto express adapters (see Example 4-15).
Example 4-15 D ICSF, CARDS command and results
D ICSF,CARDS
CSFM668I 13.40.58 ICSF CARDS 568
ACTIVE DOMAIN = 084
CRYPTO EXPRESS6 COPROCESSOR 6C00
STATUS=Active SERIAL#=DV785304 LEVEL=6.0.6z
REQUESTS=0000001185 ACTIVE=0000
CRYPTO EXPRESS6 ACCELERATOR 6A01
STATUS=Active
REQUESTS=0000000005 ACTIVE=0000
The active domain (84), number of requests (1185 for the device), and firmware level of the device (for example, 6.0.6z) are shown in Example 4-15.
Viewing the Coprocessor Management Panel
You can also obtain information about your crypto configuration and usage by using the ICSF ISPF panels. The primary panel gives you the crypto domain in use (84), as shown in Example 4-16.
Example 4-16 ICSF ISPF primary panel
OPTION ===> 1
System Name: SC60 Crypto Domain: 84
Enter the number of the desired option.
1 COPROCESSOR MGMT - Management of Cryptographic Coprocessors
Select option 1 COPROCESSOR MGMT to see the results, as shown in Example 4-17.
Example 4-17 Option 1 COPROCESSOR MGMT selection results
Select the cryptographic features to be processed and press ENTER.
Action characters are: A, D, E, K, R, S, and V. See the help panel for details.
CRYPTO SERIAL
FEATURE NUMBER STATUS AES DES ECC RSA P11
------- -------- -------------------- --- --- --- --- ---
6C00 DV785304 Active A A A A
6A01 N/A Active
The COPROCESSOR MGMT selection results give the status of your crypto adapters, where “A” stands for active (which is expected).
If you select S, you see the information that is shown in Example 4-18 on page 105.
Example 4-18 Selection of an active coprocessor
REGISTER STATUS COPROCESSOR 6C00
More: +
Crypto Serial Number : DV785304
Status : ACTIVE
PCI-HSM Compliance Mode : INACTIVE
Compliance Migration Mode : INACTIVE
AES Master Key
New Master Key register : EMPTY
Verification pattern :
Old Master Key register : EMPTY
Verification pattern :
Current Master Key register : VALID
Verification pattern : 49232659E5B39664
The Current Master Key register field that must be VALID and Status must be ACTIVE is shown in Example 4-18.
4.3.8 Reviewing messages and codes
When your installation is alerting and automating actions based on messages that are issued by ICSF, keep updated with any changing messages be seeing the following resources:
•For more information about messages for ICSF, see Cryptographic Services: Integrated Cryptographic Service Facility Messages, SC14-7509.
•For more information about new, changed, and no longer issued messages and codes for z/OS 2.3 and 2.4 ICSF, see Cryptographic Services ICSF message changes for z/OS V2R3.
4.4 Audit configuration
Configure auditing for your environment to prove that data sets are being encrypted and encryption keys are being managed. For more information about the SMF record output, see Chapter 6, “Auditing z/OS data set encryption” on page 143.
4.4.1 Enabling SMF record types 14, 15, 42, 62, 70, 80, 82, and 113
This section describes the primary SMF records and subtypes that are used for data set encryption and CKDS auditing. It also provides a brief overview of the utilities that are used for data set encryption and audit requirements.
The SMF records, their subtypes, and descriptions are listed in Figure 4-7.
Table 4-7 SMF record types
SMF
record type
Sub type
Description
14 and 15
 
Encrypted sequential data sets (extended format, basic format and large format) and PDSEs.
42
6
Used by zBNA. Contains information for encrypted sequential data sets (extended format, basic format and large format) and PDSEs.
62
 
Encrypted VSAM data sets.
70
2
Cryptographic hardware activity that is measurements from the Resource Measurement Facility (RMF).
80
 
Security authorization attempts.
82
1
Records when ICSF is started or options are refreshed. Reports ICSF installation options.
82
9
Records when the CKDS is updated.
82
14
Records when clear master key parts are loaded.
82
28
Records when protected keys are created (creating protected keys requires the CSFKEYS CSF-PROTECTED-KEY-TOKEN profile).
82
31
Reports crypto engine usage.
 
Enabled by way of the entry in CSFPRMxx: STATS(ENG,SRV,ALG) or dynamically by entering the SETICSF OPT command.
82
40
Reports changes in transitional phases in key lifecycle.
 
Enabled by way of the entry in CSFPRMxx: AUDITKEYLIFECKDS(TOKEN(YES) LABEL(YES))
82
44
Reports usage of keys.
 
Enabled by way of the entry in CSFPRMxx: AUDITKEYUSGCKDS(TOKEN(YES) LABEL(YES)INTERVAL(n)).
113
 
Required for zBNA.
4.4.2 Configuring SMF recording options in SMFPRMxx
The System Management Facility (SMF) collects and records system and job-related information in SMF records. Configuration of SMF recording involves updating the SMFPRMxx member of your PARMLIB.
The following important options must be considered for z/OS data set encryption:
•TYPE
For z/OS data set encryption, ensure that the SMF types include 14 (more specifically, 14:9), 15, 42 (more specifically, 42:6), 62, 70 (more specifically, 70:2), 80, and 82 (more specifically, 82:31, 82:40, and 82:44).
•INTVAL
The SMF global recording interval is used for SMF Type 82:31 and other record types. The system default is 30 minutes of SMF recording. At the end of the interval, SMF records are written to data sets or log streams.
•SYNCVAL
The SMF global recording interval is used for SMF Type 82:31 and other record types. The system default is an offset of 0 from the top of the hour. From the top of the hour, SMF records for INTVAL number of minutes and then writes the SMF data to data sets or log streams.
SMFPRMxx example
You can set up SMF by using an SMF parameter member that is contained in the system PARMLIB. An SMF parameter member is shown in Example 4-19.
Example 4-19 SMF parameter member
DSNAME(HLQ.SMF.MANA,HLQ.SMF.MANB) /* SMF data sets */
INTVAL(15) /* INTERVAL = 15 MINUTES */
SYNCVAL(00) /* SYNCHRONIZATION = 00 MINUTES */
SYS(TYPE(0,3,82(13:23,31,40:42),83,134)) /* Include subtype 31 */
The following parameter members are shown in Example 4-19:
•INTVAL(xx) parameter determines how often usage statistics are recorded. For example, a value of 15 triggers ICSF to record the usage every 15 minutes.
•SYNCVAL(xx) parameter synchronizes the recording interval with the end of the hour on the TOD clock (for example, a value of 00 triggers ICSF to start recording the usage at the end of the hour).
•SYS(TYPE(*)) parameter specifies the type of records that are being recorded. These ICSF usage events are recorded in SMF type 82, subtype 31 records.
4.4.3 Enabling auditing for master key change operations
All ICSF administration services, utilities, and panels are access-controlled with SAF resources. They can be audited on the RACROUTE call that generates a RACF SMF record. RACF logs the execution time and associated user.
For critical services (for example, set master key) enable RACF to audit successes to produce an audit record for that event. If the record is not needed, use the default and audit only the failure.
The following CSFSERV profiles are accessed when performing a master key change, which should be set to audit successes:
•CSFDKCS : Enter Master Key Part
•CSFCRC : Change Master Key
•CSFSMK : Set Master Key
We recommend turning on auditing by using the following commands before the start of the master key change process:
•RALTER CSFSERV CSFDKCS UACC(NONE) AUDIT(ALL) for entering master keys with option 1.E
•RALTER CSFSERV CSFCRC UACC(NONE) AUDIT(ALL) for changing master key with option 2.1.5 5 COORDINATED CKDS CHANGE MK
•RALTER CSFSERV CSFSMK UACC(NONE) AUDIT(ALL) for setting master key (option 2.4)
4.4.4 RMF Crypto Hardware Activity Report
The Resource Measurement Facility (RMF) provides performance monitoring of cryptographic coprocessor and accelerator usage in the RMF Crypto Hardware Activity report. This report is created from data in SMF record type 70, subtype 2.
The following Monitor I gathering options on the REPORTS control statement are available:
•CRYPTO measures cryptographic hardware activity
•NOCRYPTO suppress the gathering
4.4.5 EKMF Auditing
The EKMF Workstation and EKMF Web will log all key management actions to the audit log in the EKMF repository by default.
The EKMF workstation can add a MAC to each audit record for integrity validation.
Logging: When enabled in the EKMF workstation's audit log settings, the EKMF Workstation will send its audit log to SMF via the EKMF agent. By default, the EKMF Agent will require that SMF logging is enabled for any workstation that connects to the EKMF Agent.
In order for the SMF logging to be done, RACF must be setup for audit of the FACILITY class profile for resource KMG.EKMF.SMF.
The following is an example of defining the resource with audit and permitting the EKMF task user id:
 
RDEFINE FACILITY KMG.EKMF.SMF ACC(NONE) OWNER(SYS1) AUDIT(ALL(READ))
PERMIT KMG.EKMF.SMF CLASS(FACILITY) ID(<TASK_USERID>)
The RACF READ access check (RACROUTE REQUEST=AUTH) on the FACILITY class resource KMG.EKMF.SMF is done with a log-string where the content is the audit record from the EKMF Workstation.
When EKMF logs to SMF, the records are written as type 80 (Authorized access) for FACILITY class resource KMG.EKMF.SMF where the audit data is placed in the relocate section variable data - data type 46 (X'2E') 1-255 bytes.
4.5 EKMF Configuration
The EKMF key management system (see Chapter 10, “IBM Enterprise Key Management Foundation Web Edition” on page 217) provides key management capabilities across multiple ICSF CKDS keystores and can be used to create keys and store them in the CKDS keystores under specific key labels.
For each CKDS keystore, for which EKMF should manage keys, it is required that an EKMF Agent is running on the same z/OS system.
When CKDS sysplex sharing is used, only one EKMF Agent is needed for a sysplex.
EKMF must be configured with information about the location of EKMF agents as well as the keys it should create.
Keys are defined by key templates that ensures a consistent key creation process and distribution to predefined CKDS keystores with key labels that follows a predefined key label naming standard.
4.5.1 EKMF Agent
The EKMF agent must be configured to trust the connection from an instance of EKMF Web or the EKMF Workstation.
Establishing trust between EKMF Web and EKMF Agent
EKMF Web and EKMF Workstation will provide a key fingerprint for an ECC signature key. This fingerprint must be used to define a RACF resource profile in the XFACILIT class:
KMG.WS.<64-character-hex-fingerprint>
The EKMF task user ID must have READ access to this resource.
The following commands (Example 4-20) make the EKMF agent trust EKMF Web and Workstation, using 'EKMF' as the task user ID and
8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102
as the EKMF fingerprint.
Example 4-20 Establishing trust between EKMF Web and EKMF Agent
RDEFINE XFACILIT -
KMG.WS.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102
 
PERMIT -
KMG.WS.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102 -
CLASS(XFACILIT) ACC(READ) ID(EKMF)
Automatic logon of EKMF Web to the EKMF Agent
EKMF Web will perform an automatic system logon to the EKMF agent without password. Therefore, the EKMF agent must be told which client user ID to use for authorization. This is specified in the KMGPARM options data set with the &WEBCLIENT(client user ID) option.
To authorize the automatic logon, define a RACF resource profile in the XFACILIT class:
KMG.WEBCLIENT.<client user ID>
The EKMF agent task user ID must have READ access to the resource.
For a specific EKMF Web key fingerprint there must be an authorization to use the &WEBCLIENT for logon. Define a RACF resource profile in the XFACILIT class:
KMG.LG. <64-character-hex-fingerprint>
The EKMF agent task user ID must have READ access to the resource.
The following commands, shown in Example 4-21, are used to make the EKMF Web able to logon as EKMFCLT using 'EKMF' as the EKMF agent task user ID, &WEBCLIENT (EKMFCLT) in KMGPARM and
‘8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102’
as the EKMF Web fingerprint.
Example 4-21 EKMF Web automatic logon configuration
RDEFINE XFACILIT KMG.WEBCLIENT.EKMFCLT
 
PERMIT KMG.WEBCLIENT.EKMFCLT CLASS(XFACILIT) ACC(READ) ID(EKMF)
 
RDEFINE XFACILIT -
KMG.LG.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102
 
PERMIT -
KMG.LG.8A7A87509C40A5ED228E05DED51DD690EEFAC4C49B83E0A9A288B515D6745102 -
CLASS(XFACILIT) ACC(READ) ID(EKMF)
EKMF client user ID
While EKMF Web only has one client user ID, there may be multiple client user IDs for the EKMF workstation.
An EKMF client user ID must be given permission to be used with an EKMF agent running under the specific task user ID. Define a RACF resource profile in the FACILITY class:
KMG.EKMF.KMGPRACF.<task user ID>
The client user ID(s) must have READ access to the resource. Example 4-22 shows the command used to permit client user 'EKMFCLT' to be used with an EKMF agent running as user 'EKMF'.
Example 4-22 Client user ID access
RDEFINE FACILITY KMG.EKMF.KMGPRACF.EKMF
 
PERMIT KMG.EKMF.KMGPRACF.EKMF CLASS(FACILITY) ACC(READ) ID(EKMFCLT)
4.5.2 EKMF Web
There are two parts to preparing EKMF Web for creating data set encryption keys. First, keystores must be defined, to let EKMF Web know how to send keys to those particular CKDS keystores. Second, key templates must be defined, which tells EKMF Web the key label to use and which keystores the key should be distributed to.
Keystores
A Keystore in EKMF Web is defined by the network address of the z/OS system that holds the CKDS and the port number of the EKMF agent running on that z/OS system. For details, see 10.3.1, “EKMF Keystores” on page 223.
Before EKMF Web can connect to an EKMF agent, the EKMF agent must be configured to trust EKMF Web.
A keystore is defined in EKMF Web by specifying a name, a network address, a port number and a public key hash, as shown in Figure 4-30 on page 111:
Name: The name can be chosen freely and is only used as an identification of the keystore in the EKMF Web application.
Address or host name: The address the network address of the z/OS system where the keystore and EKMF agent resides. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
Port number: The port number is the port on which the EKMF Agent listens for connections. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
Public Key Hash: The public key hash is used to establish trust between EKMF Web and the EKMF Agent. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
Figure 4-30 Create new keystore
Key Templates
Keys are defined by key templates, which ensures a consistent key creation process. To create a key template (see Figure 4-31 on page 112) for a key for data set encryption, specify the following:
•The Keystore type must be set to 'Pervasive Encryption'
•The Name is used as an identification of the key template within the EKMF Web application. The Name can only use uppercase letters, digits and dashes and cannot be longer than 30 characters.
•The Key label defines the ID of the key in EKMF Web as well as the keystore label in the CKDS. Key labels can contain tags, which are placeholders for values that can be specified at key generation time. Using a mix of literal text and tags means that a key template can enforce a given key label naming convention. See 10.3.3, “Key label” on page 223.
•Key size for an AES key for pervasive encryption is always 256 bits.
•The Key type can be either AES CIPHER4 keys or AES DATA keys. AES CIPHER keys are the recommended key type for z14 or later.
•Key state refers to the EKMF key state model (see 10.3.6, “Key lifecycle” on page 225) based on NIST recommendations.
 
Notes:
 – A key that is created as Active will be distributed to keystores as part of the key generation process.
 – A key that is created as pre-active will not be distributed. It can later be activated and distributed to keystores.
 – Allow key export controls if an AES CIPHER key should be exportable out of the CKDS. Setting the key export to 'Off' means that the key cannot be exported from the CKDS, while a value of 'On' means that it will be exportable.
Tip: It is recommended to specify that the key should be non-exportable. This will prevent unauthorized copying of the key.
 – Keystores specify the keystores (defined in “Keystores” on page 115) where the key should be distributed to. Select the relevant keystores in the drop-down menu.
Figure 4-31 EKMF - create new key template
4.5.3 EKMF Workstation
There are two parts to preparing the EKMF Workstation for creating data set encryption keys. First, Hosts must be defined, to let the EKMF Workstation know how to send keys to the CKDS keystores on those hosts. Second, key templates must be defined, which tells the EKMF workstation the key label to use and which keystores the key should be distributed to.
Hosts
A Host in the EKMF Workstation is defined by the network address of the z/OS system that holds the CKDS and the port number of the EKMF agent running on that z/OS system.
Before the EKMF Workstation can connect to an EKMF agent, the EKMF agent must be configured to trust the EKMF Workstation (see Figure 4-32 on page 114):
•A Host has a Host identification, which is a unique name for the host.
•The description is a free-text field that can be used to provide a short description of the host.
•Host type must be set to 'Z-SERIES' to identify the host as running on a z/OS system.
•IP Name is the network address of the z/OS system where the EKMF agent resides. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
•IP Address will be updated based on the value entered in the IP Name field.
•Port number is the TCP port on which the EKMF Agent listens for connections. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
•The timeout value determines how long the EKMF Workstation should wait for a response from the EKMF Agent. If the timeout is exceeded, the EKMF agent will be considered unavailable.
•The codepage name indicates which codepage the EKMF Workstation should use to communicate with the EKMF Agent. This information should be provided by the z/OS system programmer who installed the EKMF Agent.
•Link Encryption should be set to ECDH. This will establish an AES session encryption key using an Elliptic-Curve Diffie-Hellman key exchange. The other link-encryption options will be removed in future version of EKMF.
•The logon group is used to group hosts into groups. The EKMF workstation will only ask for credentials once per logon group and will reuse those credentials for all Hosts in the logon group.
Figure 4-32 EKMF workstation - host definition
Having defined all relevant hosts, update the EKMF Workstation device configuration to enable EKMF to distribute keys to the CKDS keystores on the hosts.
Key Templates
Keys are defined by key templates, which ensures a consistent key creation process.
The following paragraphs describe the fields required in a key template to create an AES CIPHER key or an AES DATA key that can be used for data set encryption. It is recommended to fill out all fields of a key template. Additional descriptions of key template fields are in the EKMF documentation.
CIPHER KEYS
To create a key template for an AES CIPHER key, the fields in the key template in Figure 4-33 on page 115 must be specified as follows:
•The Title is a short description of the purpose of the key template
•The Number is the unique identifier for the key template. Once set, it cannot be changed. Valid characters are a-z, 0-9 and underscore (_).
•Set the status to active, to be able to use the key template to generate keys.
•The Key label is the label that identifies the key in EKMF (The keystore label for the CKDS is defined in the key template instances below). Key labels can contain tags, which are placeholders for values that can be specified at key generation time. Using a mix of literal text and tags means that a key template can enforce a given key label naming convention (see 10.3.3, “Key label” on page 223).
•Key state refers to the EKMF key state model (see 10.3.6, “Key lifecycle” on page 225) based on NIST recommendations.
 – A key that is created as active will be distributed to keystores as part of the key generation process.
 – A key that is created as pre-active will not be distributed. It can later be activated and distributed to keystores.
•Key size for an AES key for data set encryption is always 256 bits.
The selected origins in a key template controls the origin of the key material for the key. Specify 'Generate' to be able to generate a key using the key template.
Figure 4-33 EKMF workstation - key template editor
Key instances describe separate instances of a key in the CKDS keystore(s) - see Figure 4-34 on page 116.
For a PE key, select Install: Yes, and the keystore type as ICSF.
The keystore label can be set to reference they key label specified above, or a different key label can be defined.
The values to specify for application and key zone will be specific to the particular EKMF workstation setup, because these two values combined determine the specific Hosts/CKDS keystores the key is distributed to. Specifying KEYMNGNT for application and 'I - ICSF' for the key zone will typically distribute a key to all configured hosts/CKDS keystores.
Select the KEK algorithm to be AES and select an AES KEK used to protect the AES CIPHER key when stored in the EKMF repository and during transport from the EKMF workstation to the CKDS
Figure 4-34 EKMF workstation - key instance
The Key type has a separate editor (see Figure 4-35), which is opened by using the 'magnifying-glass' button to the right of the key type field.
The key type defines the type and attributes of the key in the CKDS. For the key to be usable as a PE key, select:
•Key type: CIPHER
•CPACF export control: XPRTCPAC.
•Key-usage control: DECRYPT and ENCRYPT
•Key-usage mode: ANY-MODE
The additional settings control key exportability and its key token format. The selection here doesn't affect the usability of the key, but it is recommended to configure the key to be non-exportable, as it will prevent unauthorized copying of the key.
Figure 4-35 EKMF workstation - key editor (CIPHER key)
DATA KEYS
If a DATA key is required, create a key template as for CIPHER key (see Figure 4-33 on page 115), with the notable difference that the key type selection isn't used and the KEK algorithm should be set to RSA.
For the DATA key specific fields (shown when selecting RSA as the KEK algorithm), set ‘KEK location’ to UKDS7 and Token Format to PKCSOAEP (see Figure 4-36).
Select an RSA KEK used to protect the AES DATA key when stored in the EKMF repository and during transport from the EKMF workstation to the CKDS.
Figure 4-36 EKMF workstation - Key instance - DATA key
 
1 EKMF Workstation or EKMF Web
2 DATA keys or CIPHER keys; CIPHER keys require z14 and later w/ Crypto Express6S or newer and ICSF HCR77C1 or later.
3 An equivalent access control software security system, such as CA ACF2 for z/OS, also can be used.
4 z14 or later w/ CEX6S (and newer hardware) and minimum ICSF level HCR77C1.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.12.163.175