IBM CEX7S / 4769 frequently asked questions

This page provides answers to frequently asked questions by customers of IBM's latest generation of PCIe hardware security module (HSM), the IBM CEX7S / 4769.


Which platforms are supported?

The IBM 4769 is available on the following platforms:

  • CPACF Enablement (Central Processor Assist for Cryptographic Functions). CPACF is a set of cryptographic instructions providing improved performance IBM Z® mainframes (IBM z15® only) as crypto feature Crypto Express7S (CEX7S), feature code (FC) 0898 / 0899. Note: FC 0898 / 0899 require FC 3863 - through hardware acceleration. Using the cryptographic hardware, you gain security from using the CPACF and the Crypto feature through in-kernel cryptography APIs and, for Linux on z Systems, the libica cryptographic functions library. Cryptographic keys must be protected by your application system, as required.
  • x64 servers as an IBM Z® machine type-model (MTM) 4769-001 (4769).
  • IBM Power Systems servers (POWER10® and POWER9®) as feature code (FC) EJ35 or FC EJ37. Note: FC EJ35, Customer Card Identification Number (CCIN) C0AF, comes without blind-swap cassette custom carrier, while FC EJ37, CCIN C0AF, comes with blind-swap cassette custom carrier.

What operating system can I use?

The CEX7S crypto feature is supported on IBM z15 mainframe running one of these 64-bit operating systems:

  • IBM z/OS®
  • IBM Linux® on IBM Z®

The 4769 is supported on x64 servers running 64-bit Red Hat® Enterprise Linux (RHEL). See the x64 servers page for information about supported servers and RHEL versions.

Feature codes EJ35 and EJ37 are supported on IBM Power Systems (POWER10 and POWER9) running one of these operating systems:

  • IBM AIX®
  • IBM i®
  • IBM PowerLinux® (RHEL Server or SLES) - POWER10 only

How can I learn about the IBM CEX7S / 4769 and its specifications?

See the CEX7S /4769 overview page.


How can I obtain performance data?

Obtain 4769 performance measurements here.


How can I find news about IBM's crypto products?

Important news for our current customers is posted here.


How can I find out if there are any software updates to CCA?

Learn about software updates to the CCA software here.


How can I ask the Crypto team a question or get help for a problem?

Ask the Crypto team a question, make a comment, or report a problem.


Why do I have to wait for the adapter to be ready to use?

Any time that the coprocessor is reset, it goes through an extensive set of power-on self-test (POST) functions. POST carefully tests all parts of the coprocessor. This includes special tests required for a device that is certified under FIPS 140 at Level 4. The coprocessor is a complex device that contains cryptographic hardware which must be carefully tested. These tests can take up to several minutes to run. The coprocessor is not available for use by any application programs until the POST tests complete.

On most servers, waiting for a reset will not be a problem when the server is booting. This is because the coprocessor POST runs at the same time. The coprocessor is usually available before the server is finished booting.


Do any IBM cryptographic adapters use the Dual_EC_DRBG method?

No. No IBM CCA cryptographic coprocessors have ever used the Dual_EC_DBRG method, and thus customers using these coprocessors are not exposed to any weakness that might be in that algorithm. Coprocessors running CCA Release 4.4 or later use the SHA-256 based method from NIST SP 800-90, and older releases of CCA used a SHA-1 based method from ANSI X9.31.

IBM implements algorithms that are recommended by standards bodies and industry experts as the best practices, and updates those algorithms over time as recommendations change. For example, changes have occurred over time from DES to Triple-DES to AES and increases in RSA key size from 1024 to 4096 bits. Our current version of CCA implements the algorithms that are recognized as best practices today. To the best of our knowledge, and as supported by multiple crypto experts, there are no known weaknesses in the algorithms themselves. If industry recommendations change based on new analysis, IBM will consider moving to the newly recommended algorithms as we have always done in the past.


How do I enhance throughput with CCA and the IBM CEX7S / 4769?

The following describes how to enhance throughput of the IBM PCIe Cryptographic Coprocessor when using the IBM Common Cryptographic Architecture application programming interface. There are characteristics of your CCA host application program that can affect performance and throughput of the coprocessor. To better understand how to enhance throughput, consider these areas before designing your CCA applications:

  • Multi-threading and multi-processing
  • Caching of AES, DES, and PKA keys

Multi-threading and multi-processing

IBM cryptographic coprocessors are hardware security modules (HSMs). An IBM PCIe HSM can process multiple CCA requests simultaneously. This is because the HSM has several independent hardware elements that enable it to multi-process. These elements include the RSA engine, DES engine, CPU, random number generator, and PCIe communications interface. All of these elements work independently, and each can process a part of a different CCA verb at the same time. By being able to work on several CCA API calls at the same time, the HSM can keep some or all of its hardware elements busy. Keeping all of the hardware elements busy maximizes overall system throughput.

In order for an application to take advantage of the multi-processing capability of the coprocessor, the host system must send multiple CCA requests at the same time. These requests need to be sent without waiting for each one to finish before sending the next one. One option is to have several independent host application programs all using the coprocessor at the same time. The best way to accomplish this is to design CCA host application programs that are multi- threading. Every thread would independently send CCA requests to the HSM, such as when a Web server application starts a new thread for each request that it receives over the network. This results in enhanced utilization and maximum system throughput.

Incoming requests are automatically managed, and it is not possible to overload the HSM.


Caching AES, DES, and PKA keys

The HSM can optionally keep ready-to-use keys in a memory cache. Using cached keys enhances throughput, but can have an adverse effect. Here is an explanation about how caching keys enhances throughput, followed by how using cache can cause problems.

When a wrapped key is used, it incurs the overhead of being validated and unwrapped. The hardware security module (HSM) can optionally store a finite number of unwrapped symmetric or asymmetric keys in a memory cache, safely stored and ready to use within the encapsulated secure module. When caching keys is activated, any retained RSA key that is used is also stored in cache. Even though retained keys are never wrapped, uncached retained keys incur the overhead of being retrieved from internal flash EPROM memory. As a result of using key caching, applications that reuse a common set of keys can run much faster than those that use different keys for each transaction. Typical CCA applications use a common set of AES, DES, and PKA keys. This makes caching very effective at improving throughput. It should be noted that PKA public keys and uncached keys that are in the clear are not cached because they have very low overhead.

To improve performance, the CCA implementation provides caching of key records obtained from key storage within the CCA host code. However, the host cache is unique for each host process. Caching can be a problem if different host processes access the same key record. An update to a key record caused in one process does not affect the contents of the key cache held for other processes. To avoid this problem, caching of key records within the key storage system can be suppressed so that all processes will access the most current key records. To suppress caching of key records, use the export system command to set the environment variable CSUCACHE to 'N' or 'n' or to any string that begins with either of those letters.


What do CLU's return codes mean?

This section describes return codes that can be returned by the IBM 4769 device driver. Programs such as CLU (Coprocessor Load Utility) and the host parts of CCA can receive unusual status in the form of a 4-byte return code from the device driver. A coprocessor reset can also cause a device driver code to be returned. The following events can cause a coprocessor reset:

  • Device power-on
  • A device driver reset command
  • Coprocessor internal activity, such as completion of code updates
  • Coprocessor fault or tamper detection circuitry detects an event

Each time that a reset is not caused by a fault or tamper event, the device driver causes the coprocessor to run through its POST (power-on self-test), "Miniboot," internal code-loading, and status routines. During this process, the coprocessor attempts to coordinate with a host-system device driver. The coprocessor device driver monitors the status of its communication with the coprocessor and the coprocessor hardware status registers.

There are a very large number of possible 4-byte return codes. The most likely device driver return codes to be encountered are described in the following table. Return codes are shown as hexadecimal digits, all of which are in the form of 8xxxxxxx.

Descriptions of most likely device driver return codes

     
Return code (hexadecimal) Reason Considerations
8040FFBF External intrusion Arises due to optional electrical connection (intrusion latch) to the coprocessor. This condition can be reset. See the CSUACFC verb, keyword RESET-IL.
On IBM HSMs with CCA on x64 and IBM Power servers, no action is taken by CCA based on the state of the intrusion latch, and the state of the intrusion can be safely ignored.
8040FFDA Dead battery The on-board batteries have been allowed to run out of sufficient power, or have been removed. The coprocessor is zeroized and permanently disabled.
8040FFDB X-ray tamper This does not apply to the PCIe coprocessor.
8040FFEB Temperature tamper A high or low temperature threshold has been exceeded. The coprocessor is zeroized and permanently disabled.
8040FFF3 Voltage tamper A high or low temperature threshold has been exceeded. The coprocessor is zeroized and permanently disabled.
8040FFF9 Mesh tamper Physical damage to the tamper-evident shield that protects the coprocessor secrets has been detected. The coprocessor is zeroized and permanently disabled.
8040FFFB Reset bit is on Either (1) low voltage was detected, or (2) the internal operating temperature of the coprocessor went out of limits, or (3) the host driver sent a reset command. Using proper procedures, try removing the coprocessor from the bus and reinserting it.
8040FFFE Battery warning Battery power is marginal. Failure to replace the on-board batteries as soon as possible could result in permanent damage to and non-recoverable failure of the coprocessor. See the IBM 4769 PCIe Cryptographic Coprocessor Installation Manual for battery replacement procedures. This and other 4769 documents are available from the CEX7S / 4769 Library page.
other 8040xxxx (e.g. 80400005)
 
General communication problem Except for the prior X'8040xxxx' codes, there are additional conditions that arise in host-coprocessor communication. Determine that the host system in fact has a coprocessor. Using proper procedures, try removing the coprocessor from the bus and reinserting it. Run the CLU ST (status) command. If the problem persists, please contact the Crypto team.
8340xxxx Miniboot-0 codes This class of return code arises from the lowest-level of reset testing. If a return code in this class occurs, please contact the Crypto team.
8340038F Random number generation fault Continuous monitoring of the random number generator has detected a possible problem. There is a small statistical probability of this event occurring without indicating an actual ongoing problem. 
The CLU ST (status) command should be run at least twice to determine if the condition can be cleared.
8440xxxx Miniboot-1 codes This class of return code arises from the replaceable POST and code-loading code. If a code in this class occurs, please contact the Crypto team.

Verify the integrity of a 4769

It is a good practice to validate that a coprocessor is legitimate and untampered before using it. IBM ships a copy of CLU (Coprocessor Load Utility) to use with the CCA Support Program. You can use this utility to validate your coprocessor.

For information on using CLU, refer to the "Coprocessor Load Utility reference" section of the IBM 4769 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual. This manual and all other product documentation can be found on the CCA download site.

CLU status command

Use the ST command of CLU to start the validation process. This returns the coprocessor status.

From the CLU status response, confirm that the ROM Status is in the desired INITIALIZED state:

ROM Status 
Page 1 Certified : YES 
Segment-1 State : INITIALIZED

If you are using the CCA Support Program, confirm that the state is RUNNABLE and the Owner ID is 2 for the ROM Status of Segment-2 and Segment-3:

Segment-2 State : RUNNABLE 
Segment-2 Owner ID : 2 
Segment-3 State : RUNNABLE 
Segment-3 Owner ID : 2

An Owner ID of 2 indicates the CCA product. Any other value than 2 is not valid for CCA. ( Note: Purchasers of the Cryptographic Coprocessor Toolkit are assigned a unique Owner ID, and are able to load a customized version of CCA.)

Continuing with the status response, observe the values returned for each of the Segment-n Hash values, where n = 1, 2, or 3. returned for the code segments. Each of these three hash values is associated with a particular release of code, for example:

Segment-3 Image : 7.2.55 CCA

202005111101700A000022000000000000

Refer to the following table to verify that the hash digest returned by the CLU status command matches the expected hash digest in the table. If any of the three segment hash digests do not match, the code loaded in the coprocessor is illegitimate and is to be considered tampered. Note: The Segment 1 version number in your coprocessor may be lower than the Segment 2 / Segment 3 version number. This is due to the fact that IBM releases new Segment 1 images very sparingly. Please contact Crypto if you have any questions.

Expected hash digests by CCA release and segment
CCA Release
Segment
Expected hash digest
7.2.55
                  1
3927 38F9 4E49 3111 2274 2B3A 8538 3CDB
BCA6 7F64 C00B 1CBD 86B7 B521 DD2F CB5F
5A34 5A4D FEF9 70CF 7331 8F76 3DE9 F1B8
D62B F570 A6A3 1FEC 8F1B BB48 1484 A9D1
7.2.55
                  2
D522 EEBF BE6E C4D5 54BB 8237 E58E 0682
4950 9B6D D66A B374 C567 983E BB72 45E7
72EC 55D7 EFE1 EBC0 4D06 9C99 D445 00F5
2A71 49B9 2CEC 6F24 427F 173C 218E D271
7.2.55
                  3
B0BF CF55 005F B1EC 855F 6155 7649 B068
A2F1 0139 A11B 764D AD72 D65F 0F0C 2D2C
E196 1655 C565 48C3 3249 BAFA 4D6B C921
0129 3B06 487D 139D 3D51 BBC5 563E 815A