Parameters

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count

Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1.

rule_array

Direction:	Input
Type:	String array

The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length and must be left-aligned and padded on the right with space characters. The rule_array parameter is described in Table 1.

Table 1. Keywords for Cryptographic Resource Allocate control information

Keywords for Cryptographic Resource Allocate control information

Keyword	Description
Cryptographic resource (Required)
DEVICE	Specifies a CEX*C coprocessor by resource number. The resource_name variable must point to a buffer containing "CRPxx" (length of 5) where 'xx' is the decimal number of the resource in the range '01' to '65'. Note that the panel.exe utility shows the card numbers starting from 0, and the resource number is obtained by adding '1' to the card number. Example: To specify card number 5 as identified by panel.exe -x, use resource number 6. The user of CSUACRA:"DEVICE" will set resource_name to "CRP06", and resource_name_length to 5.
SERIAL	Specifies a CEX*C coprocessor by serial number. The resource_name variable must point to a buffer containing "xxxxxxxx", the 8 character serial number as shown by the panel.exe utility or returned by the CSUACFQ verb. Note that the panel.exe -x command shows the card serial number in this format: 'SER [xxxxxxxx]', along with other output. Example: The serial number is shown by the command panel.exe -x to be xx1234xx, as part of this output: CARD [0: CEX5C] SER [xx1234xx] CCA Vers:Date .... The user of CSUACRA:"SERIAL " will set resource_name to xx1234xx, and resource_name_length to 8.
DEV-ANY	Specifies to enable the AUTOSELECT option, such that the operating system may select the CCA coprocessor to be used from the available resources according to its policy. This selection applies to most verbs, but not all. See Multi-coprocessor selection capabilities for more information.
HCPUACLR	Specifies the use of host CPU assist for clear keys. This keyword enables clear key use of the CPACF for clear key AES encryption and decryption with hash algorithms: SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. This is the default state at the time of the first use of the CCA library by a PID or TID.
HCPUAPRT	Specifies the use of host CPU assist for protected keys. This keyword enables protected key use of the CPACF for protected key AES and DES, TDES, and MAC. This is not the default state at the time of the first use of the CCA library by a PID or TID.
Domain selection (One, optional). The domain to use from the available domains mapped to this operating system instance may be specified.
DOMNxxxx	Specifies the domain to use for the card specified with this process. The 'xxxx' part of the keyword name is replaced by a 4 digit version of the domain number. The maximum domain count is determined by the platform, the domains available are determined by the system configuration which is mapping domains from a card to this operating system instance. The lszcrypt command shows the available domains and cards. If no domains are shown (only cards) then the operating system may not support multi-domain mapping. This keyword may be combined with keywords SERIAL or DEVICE. When this keyword has not been used, the CCA library uses the domain specified in the environment variable CSU_DEFAULT_DOMAIN, or if no domain is specified, then the domain used is the domain given by the ap device driver. Usage examples: (1) If the domain desired is domain 0, use keyword DOMN0000. (2) If the domain desired is domain 65 (decimal), use keyword DOMN0065.

There is an environment variable that also impacts the default card: CSU_DEFAULT_ADAPTER (see Multi-coprocessor selection capabilities). There are also environment variables that influence CPACF support (see Environment variables that affect CPACF usage).

The actual hardware configuration determines what features are available, and CCA uses what exists if the user sets these values as desired, with respect to appropriate defaults.

resource_name_length

Direction:	Input
Type:	Integer

The resource_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the resource_name variable. The length must be 1 - 64.

resource_name

Direction:	Input
Type:	String

The resource_name parameter is a pointer to a string variable containing the name of the coprocessor to be allocated.