CEX5S / 4767 – FAQ

IBM provides documentation that helps developers design, write, and debug applications that take advantage of CCA's capabilities. These documents are available on the IBM CCA download site.

Note: To access this site, you must obtain and log in with an IBMid. This process is quick and easy. Instructions are on the download site.

The IBM 4767 is available on the following platforms:

• x64 servers as an IBM Z® machine type-model (MTM) 4767-002 (4767).
• CPACF Enablement (Central Processor Assist for Cryptographic Functions). CPACF is a set of cryptographic instructions providing improved performance on IBM Z mainframes (currently z14®, z13s™, and z13® only) as crypto feature Crypto Express5S (CEX5S), feature code (FC) 0890. Note: FC 0890 requires 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.
• IBM Power Systems servers (currently only POWER8®) as feature code (FC) EJ32 or FC EJ33. Note: FC EJ32, Customer Card Identification Number 4767, comes without blind-swap cassette custom carrier, while FC EJ33, Customer Card Identification Number 4767, comes with blind-swap cassette custom carrier.

The 4767 is supported on x64 servers running one of these 64-bit operating systems:

• Microsoft® Windows® Server 2012 R2
• Red Hat® Enterprise Linux (RHEL)
• SUSE® (a Micro Focus Company) Linux Enterprise Server (SLES)

The CEX5S crypto feature is supported on IBM Z mainframes running one of these 64-bit operating systems:

• IBM z/OS®
• Linux on IBM Z

Feature codes EJ32 and EJ33 are supported on IBM Power Systems POWER8 running one of these operating systems:

• IBM AIX®
• IBM i®
• IBM PowerLinux® (RHEL Server, SLES, or Ubuntu®)

See the IBM 4767 x64 servers page.

See the CEX5S / 4767 overview page.

Obtain 4767 performance measurements here.

Find warranty information for the 4767 here (04/2016, PDF, 693 KB).

Here is how to order an IBM 4767 for your server or mainframe.

See the CEX5S / 4767 CCA page for details about CCA.
See the CEX5S / 4767 EP11 page for details about EP11.

Battery replacement: Order a 4767 battery replacement kit, which is required to safely replace the on-board batteries (note that this is the same kit as for a 4765). See the "Replacing coprocessor batteries" section of the IBM 4767 Installation Manual (11/2019, PDF, 876 KB) to learn how to safely remove and replace the on-board batteries of a 4767. The manual also describes how to properly recycle or dispose of the old batteries.

You can order optional smart card readers and smart cards so that you can use smart cards to manage CCA DES and PKA master keys cards, and log on to CCA using smart card CCA profiles.
See the the CCA Smart Card User Guide for additional information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

See the IBM 4767 download software page to obtain the host software, device drivers, and adapter firmware. Firmware updates are also available from this page.

News about 4767 software / firmware updates is posted on the CryptoCards News page.

To uninstall 4765 software and install 4767 software:

• Run the 4765 installer to uninstall the 4765 host software and device driver.
• Shut down the server and remove the 4765 adapter.
• Restart the server.
• Run the 4767 installer to install the 4767 host software and device driver.
• Shut down the server and install the 4767 adapter.
• Restart the server.

See the "Loading and unloading coprocessor firmware" chapter in the CCA Installation Manual for additional information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

See the "Installing the coprocessor" section of the IBM 4767 Installation Manual (PDF, 876 KB) for instructions on installing the 4767.

See the “Transporting a coprocessor” section of the IBM 4767 Installation Manual (PDF, 876 KB) for instructions.

Important news for our current customers is posted here.

See the "Using the CNM and CNI utilities to manage the cryptographic node" chapter in the CCA Installation Manual for additional information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

Learn more about the Cryptographic Coprocessor Toolkit available for purchase from IBM to develop custom programming that extends the application program which performs within the HSM to create entirely new applications, thus extending the functionality of IBM's CCA application program. See the Crypto Education page to learn how to obtain education on the Cryptographic Coprocessor Toolkit.
See the CCA Software Developer’s Toolkit Guide for additional information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

The Contact Crypto page explains how to send the Crypto team a question or report a problem.

The Samples page provides usage examples for CCA and EP11.

Find out about education offerings here.

CCA returns a return/reason code of 12/338 (X'C'/X'152') whenever a CCA application program attempts to use CCA but the coprocessor code has not been loaded. While other conditions can give rise to 12/338, this is typically the cause of the problem.
Be sure that the coprocessor code loading is complete by following the instructions in the "Loading and unloading coprocessor firmware" chapter in the CCA Installation Manual for additional information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

Also be sure to read the readme.txt file accompanying your CCA software. To determine what software is loaded in your coprocessor, use either the CLU (Coprocessor Load Utility) ST (status) or VA (validate) command, also described in the installation manual.

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.

The coprocessor is also reset when the host device driver is explicitly loaded, or by running the CLU (Cryptographic Load Utility) program. Whatever the reason for the reset, the coprocessor will begin running POST and will not be usable for several minutes until the POST completes.

A CCA application program can be written to poll the coprocessor in order to determine when it is ready by periodically sending a CCA command like a Crypto_Facility_Query (CSUACFQ) status request and waiting until it returns with a successful return code.

Yes. There is a JNI (Java Native Interface) available for using Java to build CCA applications. See the “Building Java applications to use with the CCA JNI” chapter in the CCA Installation Manual for more information. For instructions on how to obtain this document, please refer to IBM 4767 documentation above.

The IBM 4767 cryptographic processes are performed within an enclosure on the HSM that is validated to FIPS PUB 140-2, Security Requirements for Cryptographic Modules, Overall Security Level 4. See FIPS certification number 3164  (Link resides outside ibm.com) on the Computer Security Resource Center website for the certification. Level 4 is the highest level of certification achievable for commercial cryptographic devices.

The IBM 4767 with IBM Enterprise PKCS#11 firmware is Common Criteria Part 3 conformant (EAL4) (Link resides outside ibm.com).  The evaluation has been conducted in accordance with the provisions of the certification scheme of the German Federal Office for Information Security (BSI) and the conclusions of the evaluation facility in the evaluation technical report are consistent with the evidence adduced.

The IBM 4767-002 with CCA version 5.3 firmware fulfills the security requirements of the German Banking Industry Committee (GBIC)  (Link resides outside ibm.com). The report is listed under number 3299. The CCA release 5.3 provides sophisticated state-of-the-art protections for handling sensitive information like PIN data, cryptographic key data and account data. The HSM IBM Model 4767-002 CCA Release 5.3 implementation is compliant with GBIC's security requirements.

Do any IBM CCA cryptographic coprocessors 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.

This section describes how to enhance throughput of the IBM 4767 when using the IBM CCA 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 affect. 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 fin ite 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.

This section describes return codes that can be returned by the IBM 4767 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

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 4767 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual. This manual and all other product documentation can be found on the Library page.

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 : 5.4.33 CCA

201810290833504A000000000000000000

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

The CLU ST command response includes a secure part number (P/N) value, such as 00LV498. On CCA releases before 5.4, make a note of this 7-character alphanumeric value. It will be needed to complete the CLU validate command below. Starting with CCA release 5.4, this value is no longer needed.

In the final manufacturing step, an IBM PCIe Cryptographic Coprocessor generates its own RSA public-private device-key key pair with the private key is retained within the coprocessor. Manufacturing uses a class key to certify the device key, which is returned to the coprocessor.

Power from the on-board batteries or PCIe bus enables the coprocessor to actively monitor for tampering events. This monitoring occurs from the time of factory certification until the end of the coprocessor's useful life. Detection of tampering activity results in the zeroization of the coprocessor's secrets, along with the destruction of the private device key and its certificate.

For each different coprocessor part number, IBM ships a CLU file called a class-key certificate file. This type of file contains the class-key certificates for each class of coprocessor. For any given coprocessor class, CLU has hardcoded into it the necessary root key to validate the class-key certificates.

CLU has a VA (validate) command that optionally takes as input the name of a class-key certificate file that has been digitally signed by IBM. The file name is derived from the secure part number of the coprocessor. The secure part number (P/N) can be retrieved using the CLU ST (status) command. Once you determine the part number for the coprocessor that you wish to validate, append "v.clu" to it to determine the name of the CLU data file to use for with the CLU VA command. For part number 00LV498, the class-key certificate data file name would be 00LV498v.clu.

Note: In CCA releases before Release 5.4, the file name must be provided as input to CLU VA in order to validate that the contents of the segments are from IBM. The class-key certificate file names are shown in the table below. Beginning with CCA Release 5.4, the name is not needed and, if provided, the utility simply ignores the contents of the file.

When CLU is called with the VA command, it validates the certificate chain from the adapter. CLU then validates the device key certificate from the adapter. Finally, using the validated device key, CLU validates status responses that the coprocessor signs with its device key.

Class-key file for use with the CLU VA command

The key that IBM uses to sign the certificates for the class keys used with the IBM 4767 PCIe Cryptographic Coprocessor is a 521-bit Prime ECC key whose public key Q as shown in the table below, with the first byte containing the most significant bits: