Authors: Richard Kisley, Garry Sullivan

This article concerns the secure configuration practices and behavior for the CEX8S or CEX7S with Common Cryptographic Architecture (CCA) firmware on IBM Z and the IBM Trusted Key Entry (TKE) workstation. This article focuses on a question that is frequently asked about firmware update processes.

Audience:

Administrators and Users of CCA for payment or cryptography applications on 

• ICSF and Linux for IBM z16 and IBM z15.

Note:  the behavior described is not new with the CEX7S or CEX8S, but the examples reflect currently available hardware/firmware.

What is CCA?

CCA is both an Architecture and a set of services.  It provides:

• Crypto algorithms and secure key management

• Specialized functions for banking and payment network interoperability

• A common set of service interfaces and architecture for all IBM z, Cognitive and x64/x86 server platforms

• Over 156 services with more than 1000 options, from ASC X9 TR-31 key support to ASC X9 TR-34 mutually authenticated RSA/certificate based TDES and AES key exchange, as well as traditional PIN-secured transaction processing and other support for core banking functions and major payment network key derivation and cryptograms.

Frequently Asked Question: Does loading firmware that defines new ACPs automatically enable those ACPs?

What are ACPs?

The CCA firmware in the IBM HSM includes a role-based access control system.  Each Role defines what operations are permitted for users or applications that operate under that Role.   A Role contains the Role identifier and a set of Access Control Points (ACPs). Each ACP is a binary value associated with the function that is be enabled/disabled by the ACP setting.  A set of User Profiles, which are called Authorities in some contexts, define the individual users of the IBM HSM.  Each user profile contains the name of 1 role which holds the ACP settings governing that profile, as well as authentication data for that user.  For an administrator using the TKE, the profile for that administrator on the IBM HSM will contain the public key for the administrator, which is used to authenticate the administrator-signed commands to the IBM HSM.

A special Role called the DEFAULT role defines the functions that can be performed by an unauthenticated IBM HSM user.  On IBM Z there is a DEFAULT role for each domain of the IBM HSM.  A domain is mapped to a system LPAR when applications need to use the IBM HSM for secure operations.

New ACPs are sometimes defined when a new level of CCA firmware is released. When IBM HSMs are updated to the new level and the ICSF or Linux code is updated containing the new ACP names and values, the TKE can be used to show or change the settings of the new ACPS. This often raises the question: 

Does adding new CCA firmware automatically change ACP values in the IBM HSM or add ACPs that are 'enabled'?

The quick answer is ‘it depends’:

• Some users never use a TKE with the IBM HSM and rely on the addition of function with the new default ACP settings. The new ACP settings are available when they install new firmware and the corresponding z/OS or CCA library updates (Linux).

• For TKE users, it is important to know that the CCA card changes behavior the first time that a client uses TKE with the card.

When a TKE has been used with a card, the CCA firmware will NOT change any ACP values for any domain on that card without TKE or SE requesting that change.  This includes load of new CCA firmware.  Therefore, if a TKE has been used with an IBM HSM, then the ACP values will stay as they were set using the TKE across almost any event.  The only scenarios that change ACPs (after a TKE has been used with a card) are:

1. zeroize of domain from TKE or SE, forcing a rebuild of the DEFAULT role from default values of current firmware; note that you also lose Master Keys here, so the domain is not operational

2. zeroize the entire HSM from SE, forcing rebuild of all DEFAULT roles on the HSM; note that you also lose Master Keys here, so the domain is not operational

3. change an ACP value from the TKE

Takeaway: Loading new CCA firmware will not change values for new or previous ACPs if a TKE has been used with the CCA card.

 Recommendation: Set ACP values before loading MKs after a zeroize and on any fresh IBM HSM.  See below for instructions.

How to collect ACPs from a domain that is configured:

1: From the “Crypto Module adminstrtion” or “Domain Group Administration” screen:

1. Select the Domain tab

2. Select a Domain (if you are not in a domain group)

3. Select either the controls-desc or controls-ACP tab

4. press the save to file button

5. Enter a file name

6. Press the save domain controls button

2: You can collect all the setting from one HSM and apply them to another. You may want to do that if you replacing an HSM, or migrating from one CEC to another. You can collect information from an older HSM and apply that data to a newer HSM. For example, you can collect data from a Crypto Express 7 and apply the data to a Crypto Express 8. The best way to learn about collect and apply method is by viewing the 5 videos found in this IBM Media Center play list: https://mediacenter.ibm.com/playlist/dedicated/

How to set ACPs before using a domain (before setting MKs):

To avoid using any domain with default ACPs, use the TKE to adjust the ACPs before you start any workloads. There are three methods for managing the domain controls (ACPS) on any given domain:

1. Manually configure the domain. In the case you select and deselect ACPs. After you have made all your changes press “send updates” to apply the changes to the domain or set of domains in a domain group.

2. Load previously saved ACP settings into the domain.

• Reverse the “save" process.

1. Press load from file

2. Select your file

3. press load domain controls

4. Press send updates

1. Apply the settings onto an HSM using the wizards in the “Configuration Migration Tasks application of the TKE. You can apply all the setting from one HSM to another. Your collect information might be from an older HSM. For example, you can apply data from a Crypto Express 7 onto a Crypto Express 8. The best way to learn about the collect and apply method is by viewing the 5 videos found in this IBM Media Center play list: https://mediacenter.ibm.com/playlist/dedicated/101043781/1_vdg8ja4s/1_xd0juqn1

Best way to see if ACP setting are the same between different domains

• Create a domain group that includes all the domains that should have the same settings.

• Open the domain group

• Open the domain group administration window

• Select the File → Compare Group pull-down menu option. (SHOWN)

• NOTE: if the group is big, this compare can take a really long time.

• Examine your results: (SHOWN)

• In this domain group, I compared configured domains with unconfigured domains. I have a lot of mismatches. This is one example of how to look at a specific mismatch:

1. Open the Domain twisty

2. Open the Controls twisty

3. Hover and double click on an ACP.

4. The exact mismatches are shown.

5. Optionally, you can save the data to a file.

• 

• Once mismaches have been found, you must decide what HSM-wide or domain-specific action must be taken to correct any issues.

For more info, please see the following

• IBM PCIe Cryptographic Coprocessors

• ICSF Application Programmer’s guide

• TKE Workstation User’s guide

• Common Cryptographic Architecture Programmer's Guide