Parameters

Edit online

The parameters for CSNBENC.

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

key_identifier
A string that is the internal CCA or TR-31 key token containing the data-encrypting key or the label of such a key in key storage to be used for encrypting the data.

If the key is a CCA token, then it must be 64 bytes. For TR-31 tokens, it can be up to 9992 bytes.

If the key token or key label contains a single-length key, single-DES encryption is performed. If the key token or key label contains a double-length or triple-length key, triple-DES encryption is performed.

Double-length CIPHER and ENCIPHER keys are also supported.

For TR-31 keys, the token must have the following attributes:

  • TR-31 key usage: D0
  • Algorithm: D or T
  • TR-31 mode of key use: B or E
text_length
On entry, the length of the plaintext (clear_text parameter) you supply. The maximum length of text is 214,783,647 bytes. A zero value for the text_length parameter is not valid. If the returned enciphered text (cipher_text parameter) is a different length because of the addition of padding bytes, the value is updated to the length of the ciphertext.

The application program passes the length of the plaintext to the verb. This verb returns the length of the ciphertext to the application program.

clear_text
The text that is to be enciphered.
initialization_vector
The 8-byte supplied string for the cipher block chaining. The first eight bytes (or less) block of the data is XORed with the ICV and then enciphered. The input block is enciphered and the next ICV is created. You must use the same ICV to decipher the data.
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, or 3.
rule_array
An array of 8-byte keywords providing the processing control information. The array is positional. The first keyword in the array is the processing rule. You choose the processing rule you want the verb to use for enciphering the data. The second keyword is the ICV selection keyword. The third keyword (or the second if the ICV selection keyword is allowed to default to INITIAL) is the encryption algorithm to use. The rule_array keywords are described in Table 1.
Table 1. Keywords for Encipher control information
Keyword Description
Processing Rule (1, required)
CBC Performs ANSI X3.102 cipher block chaining. The data must be a multiple of 8 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.
CUSP Performs Cryptographic Unit Support Program (CUSP) cipher block chaining.
IPS Performs Information Protection System (IPS) cipher block chaining.
X9.23 Performs cipher block chaining with 1 - 8 bytes of padding. This is compatible with the requirements in ANSI X9.23. If the data is not in exact multiples of eight bytes, X9.23 pads the plaintext so the ciphertext produced is an exact multiple of 8 bytes. The plaintext is padded to the next multiple eight bytes, even if 8 bytes are added. An OCV is produced.
ICV Selection (1, optional)
CONTINUE Specifies to take the initialization vector from the output chaining vector (OCV) contained in the work area to which the chaining_vector parameter points. CONTINUE is valid only for the CBC processing rule.
INITIAL Specifies to take the initialization vector from the initialization_vector parameter. INITIAL is the default value.
Encryption Algorithm (Optional)
DES Specifies to use the data encryption standard and to ignore the token marking.

Ciphering methods describes the cipher processing rules in detail.

pad_character
An integer between 0 and 255 that is used as a padding character for the X9.23 process rule (rule_array parameter).
chaining_vector
An 18-byte field that CCA uses as a system work area. Your application program must not change the data in this string. The chaining vector holds the output chaining vector (OCV) from the caller. The OCV is the first eight bytes in the 18-byte string.

The direction is Output if the ICV selection keyword of the rule_array parameter is INITIAL.

The direction is Input/Output if the ICV selection keyword of the rule_array parameter is CONTINUE.

cipher_text
The enciphered text the verb returns. The length of the ciphertext is returned in the text_length parameter. The cipher_text could be eight bytes longer than the length of the clear_text field because of the padding that is required for some processing rules.