Multi-coprocessor selection capabilities

Multi-coprocessor selection capabilities allow you to employ more than one CCA coprocessor.

When more than one CCA coprocessor is installed, an application program can control which CCA coprocessor to use. It can explicitly select a CCA coprocessor, it can switch on the AUTOSELECT option, or it can optionally employ the default CCA coprocessor.

AUTOSELECT option

If switched on, the AUTOSELECT option overrides an explicit CCA coprocessor selection and default CCA coprocessor selection for all verbs (except those listed in Verbs that ignore AUTOSELECT).

When the AUTOSELECT option is switched on, the CCA coprocessor to be used by a verb will be selected by the operating system (the Linux device driver) from the set of available CCA coprocessors, including any coprocessors loaded with CCA user defined function (UDX) code. The Linux device driver chooses a CCA coprocessor based on a policy for load balancing.

To switch on the AUTOSELECT option, use the Cryptographic Resource Allocate verb (CSUACRA). Alternatively, the AUTOSELECT option can be switched on at program start by setting the environment variable CSU_DEFAULT_ADAPTER to the value DEV-ANY. For example:

export CSU_DEFAULT_ADAPTER=DEV-ANY

To switch off the AUTOSELECT option, use the Cryptographic Resource Deallocate verb (CSUACRD).

Master key coherence for AUTOSELECT

When using the AUTOSELECT option, all CCA coprocessors accessible by the operating system must have the same state. In particular, they must be configured with the same master key as appropriate for the services in use. For example, if your application uses only DES functions and you enable AUTOSELECT, then the SYM-MK should be the same across all accessible CCA coprocessors. If you use any RSA functions from PKA verbs, then the ASYM-MKs must be the same. For AES usage the AES-MKs must match, and for ECC the APKA-MK must match.

Verbs that ignore AUTOSELECT

The following verbs ignore the AUTOSELECT option and use the explicitly selected or default CCA coprocessor instead. These verbs act as if the AUTOSELECT option does not exist, acting exactly as they did in prior releases in which AUTOSELECT was not present.

Table 1. Verbs that ignore AUTOSELECT
Verbs that ignore AUTOSELECT
Verb	Explanation
CSUACFQ	When querying CCA coprocessor state it is important to retrieve data from the explicitly queried CCA coprocessor.
CSUARNT	When testing adapter health it is also important to receive explicit results.
CSNDRKL, CSNDRKD	Listing and managing the retained keys for a CCA coprocessor requires dealing with explicitly selected CCA coprocessors. Note that it is specifically not recommended to use any retained key functions (such as choosing to use retained keys with PKA verbs) when AUTOSELECT is active. By their very nature retained keys are tied to the specific CCA coprocessor where they were created
CSNBMKP	Managing the Master Keys for a CCA coprocessor also requires explicit allocation and de-allocation to achieve expected results.
HOST-only verbs	Some verbs are not impacted by AUTOSELECT simply because they never use the CCA coprocessor. These verbs take actions that do not involve secrets guarded by the card Master Keys. These include: CSUACFV, CSNBKSI, CSNBCVG, CSNBKTB, CSNBKTB2, CSNBKTP, CSNBKTP2, CSNBT31O, CSNBT31R, CSNBT31P, CSNBAKRC, CSNBAKRD, CSNBAKRL, CSNBAKRR, CSNBAKRW, CSNBKRC, CSNBKRD, CSNBKRL, CSNBKRR, CSNBKRW, CSNBCKRC, CSNBCKRD, CSNBCKRL, CSNBCKRR, CSNBCKRW, CSNDKRC, CSNDKRD, CSNDKRL, CSNDKRR, CSNDKRW, CSNDPKB, CSNDPKX
CPACF using verbs	Some verbs use the CPACF according to configuration of appropriate environment variables. These verbs will ignore AUTOSELECT if told to use CPACF. These include: CSNBOWH, CSNBDEC, CSNBENC, CSNBSAE, CSNBSAD, CSNBMGN, CSNBMVR

Explicit CCA coprocessor selection

To explicitly select a CCA coprocessor, use the Cryptographic Resource Allocate verb (CSUACRA). This verb allocates a CCA coprocessor loaded with the CCA software. When a CCA coprocessor is allocated and the AUTOSELECT option is not on, CCA requests are routed to it until it is de-allocated. Similarly, when a CCA coprocessor is allocated and one of the verbs that ignore the AUTOSELECT option is used, then CCA requests are routed to it until it is de-allocated.

To de-allocate an allocated coprocessor, use the Cryptographic Resource Deallocate verb (CSUACRD). When a coprocessor is not allocated (either before an allocation occurs or after the cryptographic resource is de-allocated), requests are routed to the default coprocessor unless the AUTOSELECT option is on.

Note: The scope of CCA coprocessor selection when using the CSUACRA and the CSUACRD verbs is to a thread. A multi-threaded application program can use all of the installed CCA coprocessors simultaneously. A program thread can use only one of the installed coprocessors at any given time, but it can switch to a different installed coprocessor as needed. To perform the switch, a program thread must deallocate an allocated cryptographic resource, if any, and then it must allocate the desired cryptographic resource. The CSUACRA verb fails if a cryptographic resource is already allocated.

Listing CCA coprocessors

With the first call to CCA from a process, CCA associates coprocessor designators CRP01, CRP02, and so on with specific coprocessors. The host determines the total number of coprocessors installed through a call to the coprocessor device driver. Adding, removing, or relocating coprocessors can alter the number associated with a specific coprocessor. The host then polls each coprocessor in turn to determine which ones contain the CCA firmware. As each coprocessor is evaluated, the CCA host associates the identifiers CRP01, CRP02, and so forth to the CCA coprocessors. CCA coprocessors loaded with a UDX extension are also assigned a CRPnn identifier.

For a specific device driver, names such as these are used: CRPnn, cardnn, APnn, and so forth, where the nn values normally do not match (for example, some start with 0, others start with 1).

To determine the coprocessor type of a card (one out of CEX4C through CEX8C), use one of these methods:

Invoke the Cryptographic Facility Query verb (see Determining if a card is a CEX4C, CEX5C, CEX6C, CEX7C, or CEX8C).
Use the lszcrypt command (see Confirming your cryptographic devices).
Use the hwtype attribute of your cryptographic devices in sysfs (see the version of Device Drivers, Features, and Commands, that applies to your distribution).
Run the panel.exe utility installed with the RPM, using option -x (panel.exe -x), to get a quick summary of cards available and their status. See The panel.exe utility.
Run ivp.e, another utility installed with the RPM, which gives more detailed information about each card available. See Utilities.

Note that the mapping of logical card identifiers such as CRP01 and CRP02 to physical cards in your machine is not defined. This is because the mapping can change depending on the machine and its configuration. If your application needs to identify specific coprocessor cards, you can do one of the following:

Use the Cryptographic Facility Query verb (see Cryptographic Facility Query (CSUACFQ)) with the STATCARD or STATCRD2 rule_array keyword
Use the panel.exe utility program with option -x, in order to read a card's serial number (see The panel.exe utility).

Default CCA coprocessor

The selection of a default device occurs with the first CCA call to a coprocessor. When the default device is selected, it remains constant throughout the life of the thread. Changing the value of the environment variable after a thread uses a coprocessor does not affect the assignment of the default coprocessor. If a thread with an allocated coprocessor ends without first de-allocating the coprocessor, excess memory consumption results. It is not necessary to deallocate a cryptographic resource if the process itself ends. It is suggested only if individual threads end while the process continues to run.

You can alter the default designation by explicitly setting the CSU_DEFAULT_ADAPTER environment variable. This is accomplished by issuing following command:

export CSU_DEFAULT_ADAPTER=CRPxx

Replace CRPxx with the identifier for the resource you wish to use, such as CRP02. The rpm limits the maximum value of xx such that CRP01 through CRP08 are the valid identifiers for the default coprocessor (limited by the number of coprocessors actually configured).

When cards of multiple types (CEX*C) are active in the same system, note the following:

The CCA library detects CEX*C adapters and intermingles them in the CRPxx adapter instance list. This is a list of all available adapters, in the order that they were discovered by the device driver.
The default adapter will be the first instance of CEX*C adapters with the newest adapter level found from the beginning of this list. If for example, the ordered discovery list returned from the device driver is: [CEX7C, CEX8C, CEX5C, CEX6C, CEX8C]. This list corresponds to [CRP01 == CEX7C, CRP02 == CEX8C, CRP03 == CEX5C, CRP04 == CEX6C, CRP05 == CEX8C]. Therefore, the default adapter will be the first CEX8C, in our example, on position 2, referred to as CRP02.
A user can specify the proper CRPxx number to allocate and work with any card (CEX*C) .
For a specific device driver, names such as these are used: CRPxx, cardxx, APxx, and so forth, where the xx values normally do not match (for example, some start with 0, others start with 1).