Encrypting coupling facility structure data

On systems at the z/OS V2R3 level and above, list and cache structure entry and entry adjunct data can be encrypted while the data is being transferred to and from the coupling facility and while the data resides in the coupling facility structure. List and cache structure services use secure cryptographic key tokens obtained from the z/OS Integrated Cryptographic Service Facility (ICSF) software element to encrypt and decrypt user provided structure data. Encryption of structure data can be controlled on a structure-by-structure basis.

Steps for setting up and using encrypted coupling facility structures

The following topics describe the system requirements, set up steps and considerations to evaluate when enabling coupling facility structure data encryption on systems and the sysplex:

System requirements

  • A system must be at z/OS V2R3 or higher operating on IBM zEnterprise EC12 or IBM zEnterprise BC12 or newer servers with the cryptographic hardware configured and activated to perform cryptographic functions and hold Advanced Encryption Standard (AES) master keys within a secure boundary. Cryptographic hardware features available on the required servers that support cryptographic functions and AES master keys include:
    • IBM zBC12 and zEC12 with the Crypto Express3 Coprocessor (CEX3C) or Crypto Express4 Coprocessor (CEX4C)
    • IBM z13 and z13s with the Crypto Express5 Coprocessor (CEX5C).
    Note: Feature 3863, CPACF DES/TDES Enablement must be installed to use features CEX3C, CEX4C or CEX5C.
  • ICSF is required to be started on the z/OS system.

    CP Assist for Cryptographic Functions (CPACF) in the z/OS environment is used to encrypt and decrypt structure data. ICSF works with the hardware cryptographic feature to provide secure, high-speed cryptographic services in the z/OS environment. ICSF is required to be started on the z/OS system to:

    • Provide the required ICSF APIs needed by XCF to obtain and manage secure cryptographic tokens for structures, and
    • To set and manage AES master keys in the hardware cryptographic feature. AES master keys must be set on all servers where z/OS systems use CF encryption. The AES master key must be the same for all z/OS systems in the sysplex.

      XCF requires the use of the ICSF coordinated change master key function and the use of a single sysplex-wide shared cryptographic key data set (CKDS) by all members in the sysplex to ensure CFRM policy data for encrypted structures remain consistent with AES master keys in the sysplex.

      For information on setting and managing AES master keys and running ICSF in a sysplex environment, see the sections on CKDS management in a sysplex and coordinated change master key and coordinated refresh in z/OS Cryptographic Services ICSF Administrator's Guide.

    For information on installation, initialization, and customization of ICSF and activating coprocessor features, see z/OS Cryptographic Services ICSF System Programmer's Guide.
  • The following Access Control Points (ACP) must be enabled in the domain role for the cryptographic coprocessor. The required ACP are enabled by default:
    • Key Generate – OP (Enabled by default)
    • Key Test (Always enabled, can not be disabled)
    • High-performance secure AES keys (Enabled by default)
    For information on displaying and setting the Common Cryptographic Architecture (CCA) coprocessor domain role, see z/OS Cryptographic Services ICSF Administrator's Guide, section Display CCA domain roles and z/OS Cryptographic Services ICSF Application Programmer's Guide, section Access control points and callable services .

XCF requirements

  • The XCF address space must have adequate authorization through the z/OS Security Server (RACF) or an equivalent security product to access ICSF services protected by the CSFSERV general resource class. See the information on assigning the RACF TRUSTED attribute in z/OS MVS Initialization and Tuning Reference for information about using RACF to assign the TRUSTED attribute to the XCF address space.
  • The Administrative Data Utility (IXCMIAPU) must be used to create or update structure definitions in the CFRM policy data. The ENCRYPT parameter with the value of YES (e.g., ENCRYPT(YES) ) must be added to the structure definition statement of each structure that encryption is desired for.
    Note the following:
    • In addition to authorizing use of the utility (see Authorizing use of the utility) for updating CFRM policies, and CFRM couple data sets, at least READ access to ICSF CSFSERV CSFKGN and CSFSERV CSFKYT resource profiles is required when running the utility for the purposes of specifying ENCRYPT(YES) on a structure definition. At least READ access to the CSFSERV profiles is required regardless of whether the utility is run against the ACTIVE CFRM couple data set or an INACTIVE CFRM couple data set. For information on the CSFSERV general class resource, see the z/OS Cryptographic Services ICSF Administrator's Guide.
    • The Administrative Data Utility must be run on a system where ICSF is started.

      The AES master key for the system where the utility is run must be the same AES master key as the target sysplex where the CFRM administrative data set will be active.

    See Administrative data utility and CFRM parameters for administrative data utility for information on the ENCRYPT parameter, adding and updating CFRM policy structure definitions and activating a CFRM policy.

Sysplex coexistence considerations

In a sysplex where encrypted structures are used, but not all systems support connecting to encrypted structures (systems at z/OS V2R2 or below), coexistence support must be installed on the down level systems. Coexistence APAR OA52060 allows lower level systems to use CFRM couple data sets containing cryptographic information without inadvertently corrupting the cryptographic information set by up level encrypted structure support.

Systems joining a sysplex containing encrypted structures

Ensuring all systems in the sysplex satisfy the system requirements for coupling facility structure encryption also applies to systems joining the sysplex. Special planning considerations need to be made to ensure a system can join a sysplex that has encrypted structures allocated. Specifically, planning is needed to ensure that the AES master key can be set correctly in the hardware cryptographic feature. The AES master key may not have been set correctly for a new system or for a system that was not active when the AES master key was changed. When coupling facility structure encryption is used for critical sysplex functions such as XCF signaling, the system may not be able to be brought up or even join the sysplex without the correct AES master key set. In order to use the z/OS system to set the AES master key, the system may need to run in XCF-local mode first. Planning is needed to ensure a proper configuration to run in XCF-local mode is available. See z/OS Cryptographic Services ICSF Administrator's Guide for alternatives to using XCF-local mode to set the AES master key.

Dumping encrypted CF structures

The system will decrypt encrypted coupling facility structure data being written to a dump data set so that coupling facility structure dump data will always be unencrypted. STRLIST dump support will recognize that the structure contains encrypted data and decrypt encrypted structure data before storing the data in the SVC dump data sets. To ensure data is not stored in the clear in a dump data set, plan to encrypt dump data sets. When planning to encrypt dump data sets, be sure to consider that structure dumps can be taken early in IPL.

Master key changes

Cryptographic key tokens are stored in the CFRM couple data set (CDS). The cryptographic key tokens contain encryption keys enciphered under the current master key. This enciphered encryption key is referred to as a secure key. ICSF will issue a message and issue an ENF (ENF 19) when master key change processing completes. Triggered by that ENF, CFRM will re-encipher all secure keys in the active and the administrative policy records in the active CFRM CDS using the new master key. Message IXC121I is issued when this processing completes.

The use of the ICSF coordinated change master key function and the use of a single sysplex-wide shared CKDS by all members in the sysplex ensures CFRM policy data for encrypted structures remain consistent with AES master keys in the sysplex.

With CFLEVEL22 or above, the structure's secure key is stored in the CF. After the CFRM CDS is updated with the re-enciphered secure keys, CFRM will update the secure keys in the CF. Message IXC121I is issued when this processing completes.

Any inactive/spare CFRM couple data sets will not automatically be updated when a master key change takes place. To re-encipher the secure keys in an inactive CFRM CDS, run the administrative data utility (see Using the administrative data utility) to replace or add a policy that uses ENCRYPT(YES) on a structure definition statement. The utility will issue message IXC747I to indicate that the structure secure keys were re-enciphered under the current master key.

Structure encryption key management

Each structure definition in a CFRM CDS that specifies ENCRYPT(YES) requires an encryption key. The administrative data utility for CFRM must be run to assign an initial encryption key to a structure definition.

The SETXCF MODIFY command can be used to change a structure's encryption key in the active CFRM policy. See the SETXCF MODIFY command in z/OS MVS System Commands for more information on how to perform structure key token changes. A new encryption key will be generated for the structure, encrypted under the current master key and stored in the active CFRM CDS. The structure key change will take effect immediately for an unallocated structure. The change will become a pending CFRM policy change for an allocated structure. Additionally, the newly generated structure key will be propagated to all the defined administrative policies in the active CFRM CDS where the structure name exists.

You can run the administrative data utility for CFRM against an inactive/spare CFRM CDS to generate a new encryption key for a structure name by deleting and defining ALL policies in the CFRM CDS where the structure name definition exists. This technique is useful when planning to use an inactive/spare CFRM CDS on a subsequent sysplex-wide IPL or SETXCF COUPLE, PCOUPLE command.

Determining the encryption state of a structure

If not all system and XCF requirements are met, structure data may not be able to be encrypted for an allocated structure. For example, the cryptographic coprocessor configuration may be in error thus preventing CFRM from obtaining the necessary secure key token verification patterns required to perform data encryption.
  • The DISPLAY XCF, STR command can be used on z/OS V2R1 and z/OS V2R2 systems with APAR OA52060 and above to identify the coupling facility structure data encryption state of allocated structures and whether the resident structure data state matches the CFRM policy specification. For more information on the DISPLAY XCF,STR command and the ENCRYPTED, NOTENCRYPTED and ENCMISMATCH filter options, see z/OS MVS System Commands.
  • Beginning in z/OS V2R3, IBM Health Checker for z/OS check XCF_CF_STR_ENCRYPT verifies that structure data in an allocated structure is consistent with the effective ENCRYPT parameter and cryptographic encryption key for the structure (when the structure data is encrypted) in the CFRM policy.

    The health check can also be run in verbose mode to list the structure data encryption specification from the CFRM policy and the resident data format (encrypted or not encrypted) for allocated structures. For more information on check XCF_CF_STR_ENCRYPT, see IBM Health Checker for z/OS User's Guide.