IBM PCIeCC2 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 PCIe Cryptographic Coprocessor Version 2 (PCIeCC2).


Which platforms are supported?

The PCIeCC2 is available on the following platforms:

  • x86 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.

What operating system can I use?

The 4767 is supported on x86 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®)

Which x86 servers are supported?


How can I learn about the PCIeCC2 and its specifications?


How can I obtain performance data?

What warranty does IBM provide for the 4767?

Find warranty information for the 4767 here (04/2016, PDF, 677 KB) (from Library page).


Where do I get replacements for the batteries?

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).


Can I use a smart card to log on to CCA and manage master keys?

You can order optional smart card readers and smart cards (04/2016, PDF, 2.2 MB) (from Library page) 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.


What is involved in maintaining the batteries?

See the "Installing and configuring the Install a 4767 in your x86 server (04/2016, PDF, 886 KB) (from Library page), after installing the host software first.


How do I properly replace the batteries?

See the "Replacing coprocessor batteries" section of this manual (04/2016, PDF, 886 KB) (from Library page) 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.


How do I install the 4767 in my server?


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


How can I obtain firmware updates?


How can I unload old 4765 firmware and load the 4767 firmware?

  • 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" in this manual (4/2016, PDF, 1.1 MB) ( Library page).


How do I set up a cryptographic node?


Can I customize the firmware of the HSM?

Learn more about the Cryptographic Coprocessor Toolkit (PDF, 1 MB) 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.


Where can I get the expertise I need to customize CCA?


When I have a problem, how do I get help?


Are there any CCA class offerings?


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


How can I obtain a CCA or EP11 software update?


How can I stay informed about Cryptocards news?


How can I ask the Crypto team a question?


What does a CCA return code of 12 and reason code of 338 mean?

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 software into the coprocessor" chapter of this manual (PDF, 1.2 MB), (from Library page). 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.


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.

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.


Can I use Java to build applications to use with the CCA API?

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 this manual (04/2016, PDF, 1.1 MB) ( Library page).


What is the current certification status of the 4767?

The PCIeCC2 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 cryptographic adapters use the Dual_EC_DRBG method?

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.


What are the CCA ACP commands for each OS?

CCA has access-control point (ACP) command names that sometimes differ between operating systems. How can I determine the ACP command names by operating system?

See this Microsoft® Excel® spreadsheet to determine ACP command names by operating system.


How do I enhance throughput with CCA and the IBM PCIeCC2?

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 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.


What is the meaning of the "8xxxxxxx" return codes from CLU?

The following describes return codes that can be returned by the IBM PCIe Cryptographic Coprocessor device driver. Programs such as CLU (Coprocessor Load Utility) and the host parts of the IBM Common Cryptographic Architecture (CCA) Support Program 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.

  • 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 cryptographic coprocessors installed with CCA on x86 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 4767 PCIe Cryptographic Coprocessor Installation Manual for battery ordering and replacement procedures.
804xxxxx (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.

How do I verify the integrity of the IBM 4767?

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

Part Number Class-key certificate file
00LV498 00LV498v.clu
00LU398 00LU398v.clu

 

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:

 

Public key Q used by IBM to sign class key certificates