Parameters

Edit online

The parameters for CSNBSAE.

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
A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1, 2, 3, 4, or 5.
rule_array
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 keywords are described in Table 1.
Table 1. Keywords for Symmetric Algorithm Encipher control information
Keyword Description
Encryption algorithm (Required)
AES Specifies use of the Advanced Encryption Standard (AES) as the encryption algorithm. The block size for AES is 16 bytes, and the key length is 16, 24, or 32 bytes.
DES Specifies use of the Data Encryption Standard (DES) as the encryption algorithm. Only valid with keywords A28MACGN, A28MACVR, A28OWFEC, and A28OWFCL.
Processing rule (One required, when the DES algorithm keyword is specified. One optional, when the AES keyword is specified, with the exception that keywords A28MACGN, A28MACVR, A28OWFEC, and A28OWFCL must not be specified.)

Ciphering methods describes the cipher processing rules in detail.
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 enciphering in Electronic Code Book mode. The cleartext length must be a multiple of the block size.
GCM Specifies encryption in Galois/Counter Mode. The cleartext length must be less than or equal to 232 - 1.
PKCS-PAD Specifies padding of the cleartext on the right with 1 - 16 bytes of pad characters, making the padded text a multiple of the block size. Each pad character is valued to the number of pad characters added. The ciphertext length must be large enough to include the added pad characters. The ciphertext length must be large enough to include the added pad characters. The padded cleartext is enciphered in Cipher Block Chaining mode.
X9.23PAD Specifies X9.23 padding of the cleartext on the right with 1 to 16 bytes of pad characters, making the padded text a multiple of the block size. The ciphertext length must be large enough to include the added pad characters. The padded cleartext is enciphered in Cipher Block Chaining (CBC) mode.
A28MACGN Specifies to generate a MAC using the APN standards set in AS2805.5.4.

Use the following parameters:

  • key_identifier: 16 B TDES MAC key
  • key_parms: 16 B TDES CIPHER key
  • clear_text: the clear message text
  • chain_data:
    • INPUT: starting MAC residue, encrypted by the key in the key_parms parameter
    • OUTPUT: final MAC residue, encrypted by the key in the key_parms parameter
  • ciphertext: OUTPUT: MAC (8 bytes)
A28MACVR Specifies to verify a MAC using the APN standards set in AS2805.5.4. The rule array must also have a keyword from Residue Value specified when using this keyword.

Use the following parameters:

  • key_identifier: 16 B TDES MAC key
  • key_parms: 16 B TDES CIPHER key
  • clear_text: the clear message text
  • chain_data:
    • INPUT: starting MAC residue, if present as indicated by the Residue Value keyword, encrypted by the key in the key_parms parameter
    • OUTPUT: final MAC residue, encrypted by the key in the key_parms parameter
  • ciphertext:
    • INPUT: MAC to verify
    • OUTPUT: MAC (8 bytes)
A28OWFCL Specifies to use the OWF specified in AS2805.5.4.

This keyword specifies that the value in the chain_data parameter is clear data and is used in the calculation of the OWF, which is returned in the ciphertext parameter as follows:

ciphertext = OWF(key_identifier, chain_data)
A28OWFEC Specifies to use the OWF specified in AS2805.5.4.

This keyword specifies that the value in the chain_data parameter is ECB wrapped using the key specified in the key_parms parameter.

This value is unwrapped and used as the data in the OWF. The result is returned in the ciphertext parameter.
Residue Value (one required with A28MACVR, otherwise not allowed))
A28RES Specifies that there is a residue value in the first 8 bytes of the chain_data parameter. These 8 bytes will be overwritten in the return. See the chain_data parameter for details.
A28NORES Specifies that there is no residue in the first 8 bytes of the chain_data parameter. These 8 bytes should be left as zeros, as they are overwritten in the return. See the chain_data parameter for details. Only valid with A28MACVR.
Key rule (one required for GCM, A28MACGN, A28MACVR, A28OWFEC, and A28OWFCL, otherwise 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 or DES key-token or the label of an internal key-token in AES or DES key storage. This is required for A28MACGN, A28MACVR, A28OWFCL, and A28OWFEC.
Initial chaining value (ICV) selection (One, optional)
CONTINUE Specifies that the request is part of a sequence of chained requests and is not the first (initial) request in the sequence. The chain data is used as input to encipher the next block of data. The chain data buffer is updated with output that is used as input to subsequent chained requests.

This keyword is not valid with the ECB or GCM processing rule keyword.
INITIAL Specifies that this is either the first request of a sequence of chained requests, or the only request. The initialization vector is used as input to encipher the first block of data. The chain data buffer is updated with output that is used as input to subsequent chained requests. 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 encipher the block of data. Only valid with GCM, A28MACGN, A28MACVR, A28OWFEC, and A28OWFCL processing rule keywords. This is the default for GCM, A28MACGN, A28MACVR, A28OWFEC, and A28OWFCL.
key_identifier_length
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
A pointer to a string variable containing either a cleartext AES key or an AES or DES internal CCA or TR-31 key token or a label for such a token in key storage. This is the key used to encipher the data pointed to by the cleartext 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, an internal variable-length CCA or TR-31 token, 64-byte fixed-length CCA AES or DES key token, or a key label for such a key in key storage is required.

When using CBC, ECB, GCM, or PKCS-PAD, and AES with a TR-31 token, it must have the following attributes:

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

A variable-length AES key-token must have a key type of CIPHER and must allow the key to be used for encryption (key-usage field 1 high-order byte = B'1xxx 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 (key usage field (KUF) 2 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 A28OWFEC, this key is a CCA DES EXPORTER double-length key, or TR-31 token with the following attributes:

  • TR-31 key usage: K0
  • Algorithm: T
  • TR-31 mode of key use: E

For A28OWFCL, this key is a CCA DES CIPHER double-length key, or TR-31 token with the following attributes:

  • TR-31 key usage: D0
  • Algorithm: T
  • TR-31 mode of key use: B

For A28MACGN or A28MACVR, this key is a CCA TDES MAC key with a subtype extension of ANY-MAC. It must be double length. Or this key is a TR-31 token with the following attributes:

  • A28MACGN
    • TR-31 key usage: M3
    • Algorithm: T
    • TR-31 mode of key use: C or G
  • A28MACVR
    • TR-31 key usage: M3
    • Algorithm: T
    • TR-31 mode of key use: C or V
key_parms_length
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 by NIST), or 12 - 16. For processing rules A28MACGN, A28MACVR, A28OWFCL, and A28OWFEC, this value should be the length of the input key. Otherwise, this value must be 0.
key_parms
A pointer to a string variable for key-related parameters. For processing rule GCM, this variable receives the generated authentication tag for the data identified by the cleartext parameter and any additional authenticated data identified by the optional_data parameter.

For processing rules A28MACGN, A28MACVR, and A28OWFEC, this parameter contains the key that is used to encrypt the chain_data. This key must be of type CIPHER for A28MACGN and A28MACVR. For A28OWFEC, this key must be a CIPHER or DECIPHER key.

When using TR-31 keys, the token must have the following attributes for the A28* keywords:

  • A28MACGN
    • TR-31 key usage: D0
    • Algorithm: T
    • TR-31 mode of key use: B
  • A28MACVR
    • TR-31 key usage: D0
    • Algorithm: T
    • TR-31 mode of key use: B
  • A28OWFEC
    • TR-31 key usage: D0
    • Algorithm: T
    • TR-31 mode of key use: B or D
block_size
A pointer to an integer variable containing the block size used by the cryptographic algorithm. This value must be 16 for AES and 8 for DES.
initialization_vector_length
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 ECB or ICV selection CONTINUE, this value should be 0. For processing rule GCM, NIST recommends a length of 12, but any length from 1 to a maximum of 232 - 1 can be used.
initialization_vector
A pointer to a string variable containing the initialization vector for the INITIAL call to CBC mode encryption, or if the ICV selection is ONLY. It is not used if the processing rule is ECB or the ICV selection is CONTINUE.

If the processing rule is A28MACGN, A28MACVR, A28OWFEC, or A28OWFCL, this must be 0 or null.

The same initialization vector must be used when deciphering the data.

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

For A28MACGN and A28MACVR, this value must be 8. For A28OWFEC, this value must be 8 or 16. For processing rule A28OWFCL, this value must be 1-16.

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.

For processing rules A28MACGN, A28MACVR, A28OWFCL, and A28OWFEC, this value remains the same.

chain_data
A pointer to a string variable used as a work area for CBC encipher requests. This work area is not used for ECB mode encryption, while GCM mode encryption uses 104 bytes for its work area.

When the verb performs a CBC encipher operation and the ICV selection is INITIAL, the chain_data variable is an output-only buffer that receives data used as input for enciphering 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 cleartext 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.

For processing rules A28MACGN, A28MACVR, A28OWFCL, and A28OWFEC, this parameter holds the encrypted part of the data that is MACed or input to the OWF. If A28MACGN, A28OWFCL, or A28OWFEC is specified, or if A28MACVR with A28RES is specified, this field is the Residue Value from a previous MAC operation. If A28MACVR with A28NORES is specified, the field should be all zeros.

A28MACGN, A28MACVR:

  • Input(8 bytes): 8 bytes of either 0s or a residue value, enciphered using the key in key_parms.
  • Output(returned 8 bytes): The 8 bytes of the output are output MAC residue, enciphered using the key in key_parms.

A28OWFEC:

  • Input: text enciphered using the key in key_parms, which is deciphered and used in the calculation of the OWF.
  • No output in this parameter.

A28OWFCL:

  • Input: clear text that will be used in the calculation of the OWF.
  • No output in this parameter.
cleartext_length
A pointer to an integer variable containing the number of bytes of data in the cleartext variable. The cleartext_length value must be a multiple of the algorithm block size unless processing rule PKCS-PAD or X9.23PAD is specified. For processing rule GCM, the value can be a minimum of 0 up to a maximum of 232 - 1 (starting with CEX7 adapters), otherwise the value must not be 0.

If PKCS-PAD or X9.23PAD is specified, set the output cleartext_length variable from 1 - 16 bytes more than the cleartext_length value to a multiple of the algorithm block size.

For A28MACGN and A28MACVR, the maximum length is 1024. For A28OWFEC and A28OWFCL, the value must be 0.

Note: Do not make the ciphertext_length and cleartext_length parameters point to the same variable.
cleartext
A pointer to a string variable used to contain the data to be enciphered, excluding any pad bytes. When the value of clear_text_length is zero, this parameter is ignored.
ciphertext_length
On input, the ciphertext_length parameter is a pointer to an integer variable containing the number of bytes of data in the ciphertext variable. On output, the ciphertext_length variable is updated to contain the actual length of text output in the ciphertext variable. If PKCS-PAD or X9.23PAD is specified, the ciphertext_length value must be greater than or equal to the next higher multiple of 16 as the cleartext_length value (from 1 - 16 bytes longer). Otherwise, the ciphertext_length value must be greater than or equal to the cleartext_length variable.

For A28MACGN, A28MACVR, this value is 8. For A28OWFEC, this value is 4. For A28OWFCL, this value is the same as the length of the chain data.

ciphertext
A pointer to a string variable used as an output buffer where the verb returns the enciphered data. If PKCS-PAD or X9.23PAD is specified, on output the ciphertext buffer contains 1 - 16 bytes of data more than the cleartext input buffer contains.

For A28OWFEC, this parameter contains the 4 byte output of the OWF. For A28OWFCL and A28MACGN, this parameter contains the 8 byte output of the OWF.

optional_data_length
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 232 - 1, otherwise set this value to 0.
optional_data
A pointer to a string variable containing optional data for the encryption. For processing rule GCM, this parameter identifies any additional authenticated data (AAD). No other usage is currently defined.