Parameters

The parameters for CSNBSAD.

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, 2, 3, or 4.

rule_array


Direction:	Input
Type:	String array

An array of 8-byte keywords providing the processing control information. The keywords must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.

Table 1. Keywords for Symmetric Algorithm Decipher control information
Keywords for Symmetric Algorithm Decipher control information
Keyword	Description
*Decryption algorithm* (One required)
AES	Specifies use of the Advanced Encryption Standard (AES) as the deciphering algorithm. The block size for AES is 16 bytes, and the key length is 16, 24, or 32 bytes. AES is the only algorithm currently supported by this verb.
*Processing rule* (One, optional)
CBC	Performs ANSI X3.102 cipher block chaining. The data must be a multiple of eight bytes. An OCV is produced and placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CBC OCV from the previous call is used as the ICV for this call.
ECB	Specifies deciphering in Electronic Code Book mode. The ciphertext length must be a multiple of the block size.
GCM	Specifies decryption in Galois/Counter Mode. The ciphertext length must be a multiple of the algorithm block size and less than or equal to 2³² - 1.
PKCS-PAD	Specifies that the cleartext was padded on the right with 1 - 16 bytes of pad characters, making the padded text a multiple of the block size, before the data was enciphered. Each pad character is valued to the number of pad characters added. The cleartext length must be greater than 0. The output cleartext is stripped of any pad characters and the cleartext length is 1 - 16 bytes less than the ciphertext length.
X9.23PAD	Specifies that the cleartext was padded on the right with 1 – 16 bytes of pad characters, making the padded text a multiple of the block size, before the data was enciphered in Cipher Block Chaining mode. The cleartext length must be greater than 0. The output cleartext is stripped of any pad characters and the cleartext length is 1 – 16 bytes less than the ciphertext length.
*Key rule* (One, optional)
KEY-CLR	Specifies that the key_identifier parameter points to a cleartext AES key. Only the key value is allowed; the key is not contained in a key token. This is the default value.
KEYIDENT	Specifies that the key_identifier parameter points to an internal AES key-token or the label of an internal key-token in AES key-storage.
*Initial chaining value (ICV) selection* (One, optional)
CONTINUE	This specifies taking the initialization vector from the output chaining vector (OCV) contained in the work area to which the chaining_vector parameter points. This keyword is not valid with the ECB or GCM processing rule keyword.
INITIAL	This specifies taking the initialization vector from the initialization_vector parameter. Not valid with the GCM processing rule keyword. Otherwise this is the default.
ONLY	Specifies that this is the only request. The initialization vector is used as input to decipher the block of data, and must be the same value used to encipher the ciphertext. Only valid with GCM processing rule keyword. This is the default for GCM.

Ciphering methods describes the cipher processing rules in detail.

key_identifier_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the key_identifier variable. This value must be 16, 24, 32, or ≥ 64.

key_identifier


Direction:	Input
Type:	String

A pointer to a string variable containing either a clear text AES key or an internal CCA or TR-31 key token or a label of such a token in key storage. This is the key used to decipher the data pointed to by the ciphertext parameter.

For rule_array keyword KEY-CLR, a 16-byte, 24-byte, or 32-byte clear AES key is required. For rule_array keyword KEYIDENT, a fixed-length or a variable-length internal CCA AES key-token, a TR-31 AES key token, or the key label for such a key in key storage is required.

A variable-length AES key-token must have a key type of CIPHER and must allow the key to be used for decryption (key-usage field 1 high-order byte = B'x1xx xxxx'). In addition, the key token must have the following key usage based on processing rule keyword:

CBC: must allow the key to be used for Cipher Block Chaining (KUF2 high-order byte = X'00' or X'FF').
ECB: must allow the key to be used for Electronic Code Book (KUF2 high-order byte = X'01' or X'FF').
GCM: must allow the key to be used for Galois/Counter mode (KUF2 high-order byte = X'04' or X'FF').

For a TR-31 key the token must have the following attributes:

TR-31 key usage: D0
Algorithm: A
TR-31 mode of key use: B or D

key_parms_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the key_parms parameter. For processing rule GCM, this value can be 4 or 8 (which is strongly discouraged), or 12 - 16. Otherwise, this value must be 0.

key_parms


Direction:	Input
Type:	String

A pointer to a string variable for key-related parameters. For processing rule GCM, this variable contains the verified authentication tag for the data identified by the ciphertext parameter and any additional authenticated data identified by the optional_data parameter. No other usage is currently defined.

block_size


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the block size used by the cryptographic algorithm. This value must be 16.

initialization_vector_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the initialization_vector variable. For cipher block chaining (CBC or PKCS-PAD) with an INITIAL ICV selection, this value must be 16. For processing rule GCM, NIST recommends a length of 12, but any length from 1 to a maximum of 2³² - 1 can be used. Otherwise, set this value to 0.

initialization_vector


Direction:	Input
Type:	String

A pointer to a string variable containing the initialization vector for the INITIAL call to CBC mode decryption, or if the ICV selection is ONLY. It is not used if the processing rule is ECB or the ICV selection is CONTINUE. The same initialization vector must have been used to encipher the data.

chain_data_length


Direction:	Input/Output
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the chain_data variable. On input, set this variable to a value of at least 32 for CBC mode decryption, 0 for ECB mode encryption, or 104 for GCM mode decryption.

On output, the variable is updated with the length of the data returned in the chain_data variable. The chain_data_length parameter must not be changed by the calling application until chained operations are complete.

chain_data


Direction:	Input/Output
Type:	String

A pointer to a string variable used as a work area for CBC encipher requests. This work area is not used for ECB mode decryption or 104 for GCM mode decryption.

When the verb performs a CBC decipher operation and the ICV selection is INITIAL, the chain_data variable is an output-only buffer that receives data used as input for deciphering the next part of the input data, if any.

When the ICV selection is CONTINUE, the chain_data variable is both an input and output buffer.

When the ICV selection is ONLY, the chain_data variable is an output-only buffer that receives data in the event that the amount of ciphertext is greater than the host code can send to the coprocessor in a single call.

The application must not change any intermediate data in this string.

ciphertext_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the ciphertext variable. For processing rules CBC, ECB, and PKCS-PAD, the ciphertext_length value must be a multiple of the algorithm block size. The maximum length is 2³²-1. For processing rule GCM, the value can be a minimum of 0 up to a maximum of 2³² - 1, otherwise the value must not be 0. If PKCS-PAD is specified, set the output cleartext_length variable from 1 - 16 bytes less than the ciphertext_length value.

When the Crypto Express adapter is a CEX5 or CEX6, the maximum value is 2²⁹-1. When the Crypto Express adapter is a CEX7, the maximum value is 2³²-1.

Note: Do not make the ciphertext_length and cleartext_length parameters point to the same variable.

ciphertext


Direction:	Input
Type:	String

A pointer to a string variable containing the data to be deciphered, including any pad bytes.

cleartext_length


Direction:	Input/Output
Type:	Integer

On input, this parameter is a pointer to an integer variable containing the number of bytes of data in the cleartext variable. On output, this variable is updated to contain the actual length of text output in the cleartext variable. If PKCS-PAD is specified, the cleartext value is updated with 1 - 16 bytes of data less than the ciphertext_length value.

cleartext


Direction:	Input/Output
Type:	String

A pointer to a string variable used to contain the data to be deciphered, excluding any pad bytes.

optional_data_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the optional_data variable. For processing rule GCM, set this value to a minimum of 0 up to a maximum of 2³² - 1, otherwise set this value to 0.

optional_data


Direction:	Input
Type:	String

A pointer to a string variable containing optional data for the decryption. For processing rule GCM, this parameter identifies any additional authenticated data (AAD). No other usage is currently defined.