Setting up z/OS data set encryption

Importance of host based compression

It is recommended that clients who use host-based encryption, also use host-based compression before data encryption. If the data is not compressed prior to encryption, there can be consequences to other parts of the client infrastructure. For example, replicated data that is being compressed in the SAN infrastructure by DWDM technology will no longer effectively compress encrypted data. If the data is not compressed before it is encrypted, additional bandwidth might be required.

Additionally, tape systems might require extra capacity in terms of disk space, in the case of virtual tape or tape cartridges. If data deduplication is supported, host-based encryption can prevent data deduplication from working. Therefore, where possible, use compressed format data sets. With encrypted compressed format data sets, the access methods perform compression before encryption. Refer to Considerations when planning for data set encryption.

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 encryption DATA key within the ICSF key repository (CKDS) to be used to encrypt or decrypt the data. For each encrypted data set, its key label is stored in the catalog. The key label is not sensitive information; it identifies the encryption key, which is sensitive; therefore, IBM® recommends only using secure keys. For more information, see z/OS Cryptographic Services ICSF System Programmer's Guide.

Before enabling this function

Because data set encryption has both hardware and software requirements, you must consider all systems that share data with a system on which you plan to enable data set encryption before creating an encrypted data set. This includes backout software levels, backup systems, read-only systems, replication target systems and disaster recovery systems. Before encrypting data sets other than those used for testing, be sure that all the systems that must access encrypted data sets are capable of doing so by meeting the required hardware and software requirements. In addition to the hardware and software requirements that must be available on every system that will access the encrypted data sets, all key labels and encryption keys associated with the encrypted data sets must also be available.

Take the following steps to make data set encryption unavailable to users who are not explicitly authorized to use it:

Define the STGADMIN.SMS.ALLOW.DATASET.ENCRYPT profile in the FACILITY class, and set the universal access to NONE:
```
RDEFINE FACILITY STGADMIN.SMS.ALLOW.DATASET.ENCRYPT UACC(NONE)
```
If the FIELD class is active, check for any profile that would allow any user without SPECIAL attribute access to the DATASET.DFP.DATAKEY. If there are none, no additional action is needed. If there is any profile that would allow access to DATASET.DFP.DATAKEY, create a DATASET.DFP.DATAKEY profile in the FIELD class with a UACC of NONE:
```
RDEFINE FIELD DATASET.DFP.DATAKEY UACC(NONE)
```

Taking the above steps is intended to assure that only authorized users are allowed to use data set encryption. Such users should be made aware that until the decryption functions are available on all sharing systems, backup systems, and disaster recovery systems, access to encrypted data can be lost at any time.

Tasks for setting up z/OS data set encryption

This section assumes that the following Core infrastructure requirements are already in place, or are understood by the user:

ICSF installation, configuration, administration ICSF AES master key(s) populated
Crypto Express® hardware cards installed, configured, and known to ICSF
RACF® installation, configuration, administration, or equivalent SAF product
Basic knowledge or understanding of AES keys, data keys, key labels, ICSF and RACF in a sysplex.

Create key labels and encryption keys

To create an encrypted data set, a key label must be assigned to the data set. The key label and its associated AES-256 bit encryption key must exist in the CKDS by the time the data set is opened. To create keys in the CKDS, refer to z/OS Cryptographic Services ICSF System Programmer's Guide. IBM recommends the use of secure keys.

Set up CSFKEYS

To control which users can use which keys, protect resources CSFKEYS class. The CSFKEYS class controls access to cryptographic keys identified by the key label.

To enable the use of ICSF keys:

Grant the user READ authority to the resource key-label in the CSFKEYS class. This authority can be granted for all uses of the key-label or only when the use of the key-label is permitted when using the a CRITERIA value of DSENCRYPTION for SMS.
- if the class has not already been enabled for generics
```
SETROPTS GENERIC(CSFKEYS)
```
- Define profiles in the CSFKEYS class to protect key labels
```
RDEFINE    CSFKEYS  profile-name UACC(NONE) 
           ICSF(SYMCPACFWRAP(YES)   SYMCPACFRET(YES))
```
- Give the users (preferably groups) access to the profiles
```
PERMIT profile-name CLASS(CSFKEYS) 
       ID(name)    ACCESS(READ)
```
or
```
PERMIT profile-name CLASS(CSFKEYS) 
       ID(name)    ACCESS(READ) 
       WHEN(CRITERIA(SMS(DSENCRYPTION)))
```
Define the ICSF information for the key with SYMCPACFWRAP(YES) and SYMCPACFRET(YES), if it was not specified on the DEFINE
```
RALTER CSFKEYS profile-name 
       ICSF(SYMCPACFWRAP(YES)   SYMCPACFRET(YES))
```
Set RACF options
- if the CSFKEYS class is not already active
```
SETROPTS CLASSACT(CSFKEYS)
```
- if the CSFKEYS class has not already been RACLISTed
```
SETROPTS RACLIST(CSFKEYS)
```
- or if the CSFKEYS class has already been RACLISTed
```
SETROPTS RACLIST(CSFKEYS) REFRESH
```

Set up CSFSERV

Important: The following setup is required only if CHECKAUTH(YES) is specified on the ICSF installation options data set. CHECKAUTH(NO) is the default.

Protect the resources CSFSERV class. ICSF controls access to cryptographic services through the CSFSERV resource class. For more information, see z/OS Cryptographic Services ICSF Administrator's Guide.

The following table summarizes the CSFSERV resource required for processing encrypted data sets.

Table 1. CSFSERV resource required for data set encryption
Function	ICSF callable service	Resource
CKDS Key Record Read2	CSNBKRR2	CSFKRR2

If the user does not have sufficient access, open processing will fail. An informational message ICH408I (which indicates insufficient authorization) might be issued.

Grant the user READ authority to the resource CSFSERV class:
- if the class has not already been enabled for generics
```
SETROPTS GENERIC(CSFSERV)
```
- Define profiles in the CSFSERV class to protect key labels
```
RDEFINE CSFSERV * UACC(NONE)
```
- Define profile CSFKRR2 if it does not exist
```
RDEFINE CSFSERV CSFKRR2 UACC(NONE)
```
- Give the users (preferably groups) access
```
PERMIT CSFKRR2 CLASS(CSFSERV) ID(groupid) ACCESS(READ)
```
Set RACF options:
- if the CSFSERV class is not already active
```
SETROPTS CLASSACT(CSFSERV)
```
- if the CSFSERV class has not already been RACLISTed
```
SETROPTS RACLIST(CSFSERV)
```
- or if the CSFSERV class has already been RACLISTed
```
SETROPTS RACLIST(CSFSERV) REFRESH 
```

Create an encrypted data set

To create an encrypted data set, you must assign a key label to the data set when it is newly allocated (data set create). A key label can be specified through any of the following methods:

RACF data set profile
JCL, dynamic allocation, TSO ALLOCATE, IDCAMS DEFINE
SMS data class

To specify a key label using the DFP segment in the RACF data set profile, use keyword DATAKEY(Key-Label). The system will use this key label for extended format data sets that are created after DATAKEY is added to the data set profile. Use keyword NODATAKEY to remove a key label, if defined, from the RACF DFP segment. The key label is ignored for a data set that is not a DASD data set.

To specify a key label using JCL, dynamic allocation, and TSO allocate, use JCL keyword DSKEYLBL='key-label', dynamic allocation text unit DALDKYL, or TSO allocate DSKEYLBL(label-name). DSKEYLBL parameter is effective only if the new data set is on DASD. The key label is ignored for a data set that is not a DASD data set.

See details about the DSKEYLBL parameter (key-label) keyword on the JCL DD statement in z/OS MVS JCL Reference.

To specify a key label using SMS data class, use the Data Set Key Label field on the ISMF DEFINE/ALTER panel. The system will use this key label for extended format data sets that are created after the data set key label is added to the data class. The key label is ignored for a data set that is not a DASD data set.

See details on using the Data Set Key Label field in the ISMF panels in z/OS DFSMS Using the Interactive Storage Management Facility.

To specify a key label using the DEFINE CLUSTER command for a VSAM CLUSTER, use the KEYLABEL parameter; for example, KEYLABEL(MYLABEL). Any alternate index associated with the CLUSTER will also be encrypted and use the same key label as specified for the CLUSTER. The key label is ignored for a data set that is not a DASD data set.

For more information on using DEFINE CLUSTER command for a VSAM CLUSTER, see z/OS DFSMS Access Method Services Commands.

When a key label is specified on more than one source, the key label is derived from one of the above sources only on the initial data set allocation (on data set create). The key label is derived in the following order of precedence:

From DFP segment in the RACF data set profile.
Explicitly specified on the DD statement, dynamic allocation text unit, TSO ALLOCATE command, or DEFINE CLUSTER control statement.
From the data class that applies to the current DD statement.
Note: The REFDD and LIKE JCL DD statement keywords do not cause a key label from the data set referred to be used when allocating a new data set.

On successful allocation of an encrypted data set, the following message is issued:

IGD17150I DATA SET dsname IS ELIGIBLE FOR ACCESS METHOD ENCRYPTION
KEY LABEL IS (key_label)

Specifying a key label for a non-extended format data set

If an encryption key label is specified for a DASD data set that is not extended format, the key label is ignored and the data set is successfully created as non-encrypted non-extended format data set. In addition, SMS message IGD17156I is issued (or if using IDCAMS DEFINE and data set is non-SMS managed, message IDC3040I is issued) indicating that the key label is ignored. Instead to have the system fail the allocation, the user must have at least READ authority to the resource in the FACILITY class: STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC

If this facility class resource exists and the user has at least read authority, SMS will fail the allocation and issue message IGD17151I (or if using IDCAMS DEFINE and non-SMS managed data set request, message IDC3039I is issued).

Enable data set encryption

An enablement action is required to allow the creation of encrypted data sets when the key label is specified through a method outside of the DFP segment in the RACF data set profile.

To allow the system to create encrypted data sets using a key label specified through a method other than through the DFP segment in the RACF data set profile, the user must have at least READ authority to the following resource in the FACILITY class:

STGADMIN.SMS.ALLOW.DATASET.ENCRYPT

Note: IBM recommends that you define STGADMIN.* with UACC(NONE).

The system checks the user's authority to access this resource when a data set to be encrypted is first allocated (that is, created). It is not checked again before encrypting a data set.

Allocation processing

SMS allocation processing determines if a data set can be allocated as an encrypted data set. Under certain conditions, you can specify how the allocation should proceed. The following tables summarize the system behavior during SMS allocation processing for a new data set based on specific FACILITY class resources and the user's authorization to the resource.

On a z/OS® V2R2 system (with OA50569) and later, the following table describes the result of an allocation request for an extended format data set when a key label has been specified. On a successful allocation, the resulting data set will be an encrypted extended format data set. Other factors not described in this table (such as lack of space) might cause the allocation to fail.

Table 2. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS V2R2 with OA50569)
FACILITY class resource	STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
Access	Not defined OR not authorized		At least authorized for READ
Allocation type	JCL	IDCAMS DEFINE	JCL	IDCAMS DEFINE
Key label from DFP segment of RACF DS profile	Allocation continues with IGD17150I	Allocation continues with IGD17150I	Allocation continues with IGD17150I	Allocation continues with IGD17150I
Key label from a source other than DFP segment of RACF DS profile	Allocation fails with IGD17155I	Allocation fails with IDC3038I	Allocation continues with IGD17150I	Allocation continues with IGD17150I

On a z/OS V2R2 system (with OA50569) and above, the following table describes the result of an allocation request for a DASD non-extended format data set when a key label has been specified from any source. On a successful allocation, the resulting data set will be a non-encrypted non-extended format data set. Other factors not described in this table (such as lack of space) might cause the allocation to fail.

Table 3. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS V2R2 with OA50569)
FACILITY class resource	STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC
Access	Not defined OR not authorized		At least authorized for READ
Allocation type	JCL	IDCAMS DEFINE	JCL	IDCAMS DEFINE
SMS mgd	Allocation continues with IGD17156I	Allocation continues with IGD17156I	Allocation fails with IGD17151I	Allocation fails with IGD17151I
non-SMS mgd	Allocation fails with IGD17156I	Allocation fails with IDC3040I	Allocation fails with IGD17151I	Allocation fails with IDC3039I

On a z/OS V2R1 system (with OA50569), the following table describes the result of an allocation request for a DASD data set (extended format and non-extended format) when a key label has been specified from any source. On a successful allocation, the resulting data set will be a non-encrypted data set since you cannot create new encrypted data sets on a z/OS V2R1 system. Other factors not described in this table (such as lack of space) might cause the allocation to fail.

Table 4. SMS Allocation Processing Based on System Levels and Allocation Request (z/OS V2R1 with OA50569)
FACILITY class resource	STGADMIN.SMS. FAIL.INVALID.DSNTYPE.ENC
Access	Not defined OR not authorized		At least authorized for READ
Allocation type	JCL	IDCAMS DEFINE	JCL	IDCAMS DEFINE
Key label specified on JCL (DSKEYLBL)	Job fails with IEFC630I	N/A	Job fails with IEFC630I	N/A
Key label specified on IDCAMS DEFINE (KEYLABEL)	N/A	Allocation fails with IDC3211I	N/A	Allocation fails with IDC3211I
Key label from DFP segment of RACF DS profile or from data class)	Refer to the following two rows
SMS mgd	Allocation continues with IGD17156I	Allocation continues with IDC3040I	Allocation fails with IGD17154I	Allocation fails with IDC0017I
non-SMS mgd	Allocation continues with IGD17156I	Allocation continues with IDC3040I	Allocation fails with IGD17154I	Allocation fails with IDC0017I

Accessing encrypted data sets

Applications that use standard BSAM, QSAM, and VSAM APIs do not require changes to access encrypted data sets. The user data transferred between the application and the access methods is in the unencrypted form. The access method encrypts the data when writing to DASD and decrypts the data when reading from DASD. For encrypted compressed format data sets, the access method compresses the data before encrypting it on output. On input, the access method decrypts the data before decompressing it.

Considerations regarding ICSF startup and shutdown

If you plan to encrypt SMF data sets or other data sets used during z/OS initialization, you must ensure that ICSF is started early in the IPL process to avoid delays in z/OS initialization and termination. As such, it is highly recommended the command S CSF,SUB=MSTR is placed early in the COMMNDxx member to ensure that there is minimum delay in z/OS initialization. Specifying SUB=MSTR is necessary to allow ICSF to start before JES.

Furthermore, during z/OS system shutdown, ICSF must be one of the last features to stop so that dependent functions are not impacted. It is highly recommended that you shut down ICSF after terminating the JES address space and after initiating SMF halt processing. Note when ICSF is stopped after SMF is halted, that there might not be an SMF record cut for the termination of ICSF. (The ability to start ICSF with SUB=MSTR is available on all supported releases of ICSF.)

Considerations regarding backup/migration/replication functions

Key label authorization

The following system functions maintain data in the encrypted form. Therefore, users performing these functions do not require authorization to the key label associated with the data sets being processed with these functions:

DFSMSdss functions: COPY, DUMP, and RESTORE
DFSMShsm functions: migrate/recall, backup/recover, abackup/arecover, dump/data set restore, FRBACKUP/FRRECOV DSNAME
Track based copy (PPRC, XRC, FlashCopy®, concurrent copy) operations

Other considerations

DFSMSdss REBLOCK keyword is ignored on COPY and RESTORE functions for encrypted data sets.
DFSMSdss ADRREBLK installation exit will not be called for encrypted data sets.
DFSMSdss does not support VALIDATE processing when backing up encrypted indexed VSAM data sets. VALIDATE will be ignored.
Backup and migration of encrypted data sets may impact expected savings with disk or tape device compression. Where possible, convert to compressed format data sets. When data set level compression requested, access methods handle compression before encryption for compressed format encrypted data sets.