Encipher (CSNBENC or CSNBENC1 and CSNEENC or CSNEENC1)

Use the encipher callable service to encipher data in an address space or a data space using the cipher block chaining mode. ICSF supports these processing rules to encipher data. You choose the type of processing rule that the encipher callable service should use for the block chaining.

Processing Rule: Purpose
ANSI X9.23: For block chaining not necessarily in exact multiples of 8 bytes. This process rule pads the plaintext so that ciphertext produced is an exact multiple of 8 bytes.
CBC: For block chaining in exact multiples of 8 bytes.
CUSP: For block chaining not necessarily in exact multiples of 8 bytes. The ciphertext will be the same length as the plaintext.
IBM 4700: For block chaining not necessarily in exact multiples of 8 bytes. This process rule pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes.
IPS: For block chaining not necessarily in exact multiples of 8 bytes. The ciphertext will be the same length as the plaintext.

For more information about the processing rules, see Table 1 and Cipher processing rules.

The cipher block chaining (CBC) mode of operation uses an initial chaining vector (ICV) in its processing. The ICV is exclusive ORed with the first 8 bytes of plaintext prior to the encryption step, and thereafter, the 8-byte block of ciphertext just produced is exclusive ORed with the next 8-byte block of plaintext, and so on. This disguises any pattern that may exist in the plaintext.

The selection between single-DES encryption mode and triple-DES encryption mode is controlled by the length of the key supplied in the key_identifier parameter. If a single-length key is supplied, single-DES encryption is performed. If a double-length or triple-length key is supplied, triple-DES encryption is performed.

To nullify the CBC effect on the first 8-byte block, supply 8 bytes of zero. However, the ICV may require zeros.

Cipher block chaining also produces a resulting chaining value called the output chaining vector (OCV). The application can pass the OCV as the ICV in the next encipher call. This results in record chaining.

Note that the OCV that results is the same, whether an encipher or a decipher callable service was invoked, assuming the same text, ICV, and key were used.

Short blocks are text lengths of 1 to 7 bytes. A short block can be the only block. Trailing short blocks are blocks of 1 to 7 bytes that follow an exact multiple of 8 bytes. For example, if the text length is 21, there are two 8-byte blocks, and a trailing short block of 5 bytes. Short blocks and trailing short blocks of 1 to 7 bytes of data are processed according to the Cryptographic Unit Support Program (CUSP) rules, or by the record chaining scheme devised by and used by the Information Protection System (IPS) in the IPS/CMS program product. These methods of treating short blocks and trailing short blocks do not increase the length of the ciphertext over the plaintext.

An alternative method is to pad the plaintext and produce a ciphertext that is longer than the plaintext. The plaintext can be padded with up to 8 bytes using one of several padding schemes. This padding produces a ciphertext that is an exact multiple of 8 bytes long.

If the cleartext is already a multiple of 8, the ciphertext can be created using any processing rule.

Because of padding, the returned ciphertext length is longer than the provided plaintext; the text_length parameter will have been modified. The returned ciphertext field should be 8 bytes longer than the length of the plaintext to accommodate the maximum amount of padding. You should provide this extension in your installation's storage because ICSF cannot detect whether the extension was done.

The minimum length of data that can be enciphered is one byte.

Attention: If you lose the data-encrypting key under which the data (plaintext) is enciphered, the data enciphered under that key (ciphertext) cannot be recovered.

Choosing between CSNBENC and CSNBENC1

CSNBENC and CSNBENC1 provide identical functions. When choosing which service to use, consider this:

CSNBENC requires the cleartext and ciphertext to reside in the caller's primary address space. Also, a program using CSNBENC adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface.
The callable service name for AMODE(64) invocation is CSNEENC.
CSNBENC1 allows the cleartext and ciphertext to reside either in the caller's primary address space or in a data space. This can allow you to encipher more data with one call. However, a program using CSNBENC1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface.
The callable service name for AMODE(64) invocation is CSNEENC1.

For CSNBENC1 and CSNEENC1, clear_text_id and cipher_text_id are access list entry token (ALET) parameters of the data spaces containing the cleartext and ciphertext.

Format

CALL CSNBENC(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             key_identifier,
             text_length,
             clear_text,
             initialization_vector,
             rule_array_count,
             rule_array,
             pad_character,
             chaining_vector,
             cipher_text )

CALL CSNBENC1(
              return_code,
              reason_code,
              exit_data_length,
              exit_data,
              key_identifier,
              text_length,
              clear_text,
              initialization_vector,
              rule_array_count,
              rule_array,
              pad_character,
              chaining_vector,
              cipher_text,
              clear_text_id,
              cipher_text_id )

Parameters

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. ICSF and cryptographic coprocessor return and reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

key_identifier

Direction	Type
Input/Output	String

A 64-byte string that is the internal key token containing the data-encrypting key, or the label of a CKDS record containing the data-encrypting key, to be used for encrypting the data. 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.

On an IBM eServer zSeries 990 and subsequent releases, single and double length CIPHER and ENCIPHER keys are also supported.

text_length

Direction	Type
Input/Output	Integer

On entry, the length of the plaintext (clear_text parameter) you supply. The maximum length of text is 2,14783647 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.

Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647).

The application program passes the length of the plaintext to the callable service. The callable service returns the length of the ciphertext to the application program.

clear_text

Direction	Type
Input	String

The text that is to be enciphered.

initialization_vector

Direction	Type
Input	String

The 8-byte supplied string for the cipher block chaining. The first 8 bytes (or less) block of the data is exclusive ORed 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

Direction	Type
Input	Integer

The number of keywords you supply in the rule_array parameter. The value must be 1, 2, or 3.

rule_array

Direction	Type
Input	Character String

An array of 8-byte keywords providing the processing control information. The array is positional. See the keywords in Table 1. The first keyword in the array is the processing rule. You choose the processing rule you want the callable service 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.

Table 1. Keywords for the Encipher Rule Array Control Information
Keyword	Meaning
*Processing Rule (required)* Rules CUSP, IPS, X9.23, and 4700-PAD should be specified only when there is one request or on the last request of a sequence of chained requests.
CBC	Performs cipher block chaining as described in NIST SP 800-38A. 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 ciphering that is compatible with IBM's CUSP and PCF products. The data can be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The CUSP/PCF OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CUSP/PCF OCV from the previous call is used as the ICV for this call.
IPS	Performs ciphering that is compatible with IBM's IPS product. The data may be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The IPS OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the IPS OCV from the previous call is used as the ICV for this call.
X9.23	Performs cipher block chaining with 1 to 8 bytes of padding. This is compatible with the requirements in ANSI standard X9.23. If the data is not in exact multiples of 8 bytes, X9.23 pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes. The plaintext is padded to the next multiple 8 bytes, even if this adds 8 bytes. An OCV is produced.
4700-PAD	Performs padding by extending the user's plaintext with the caller's specified pad character, followed by a one-byte binary count field that contains the total number of bytes added to the message. 4700-PAD pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes. An OCV is produced.
*ICV Selection (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. CONTINUE is valid only for processing rules CBC, IPS, and CUSP.
INITIAL	This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value.
*Encryption Algorithm (optional)*
DES	This specifies using the data encryption standard and ignoring the token marking.
TOKEN	This specifies using the data encryption algorithm in the DATA key token. TOKEN is the default.

These recommendations help the caller determine which encipher processing rule to use:

If you are exchanging enciphered data with a specific implementation, for example, CUSP or ANSI X9.23, use that processing rule.
If the ciphertext length must be equal to the plaintext length and the plaintext length cannot be a multiple of 8 bytes, use either the IPS or CUSP processing rule.

Cipher processing rules describes the cipher processing rules in detail.

pad_character

Direction	Type
Input	Integer

An integer, 0 to 255, that is used as a padding character for the 4700-PAD process rule (rule_array parameter).

chaining_vector

Direction	Type
Input/Output	String

An 18-byte field that ICSF 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 8 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

Direction	Type
Output	String

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

clear_text_id

Direction	Type
Input	Integer

For CSNBENC1/CSNEENC1 only, the ALET of the clear text to be enciphered.

cipher_text_id

Direction	Type
Input	Integer

For CSNBENC1/CSNEENC1 only, the ALET of the ciphertext that the application supplied.

Restrictions

The service will fail under these conditions:

If the key token contains double- or triple-length keys and triple-DES is not enabled.
If a token is marked CDMF.

Usage notes

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS.

You cannot destructively overlap the plaintext and ciphertext fields. For example:

cccccc
     pppppp  is supported.
cccccc
     pppppp  is not supported.

ppppppcccccc is supported.

P represents the plaintext and c represents the ciphertext.

The method used to produce the OCV is the same with the CBC, 4700-PAD, and X9.23 processing rules. However, that method is different from the method used by the CUSP and IPS processing rules.

Cipher processing rules discusses the cipher processing rules.

The Decipher callable services are described under Decipher (CSNBDEC or CSNBDEC1 and CSNEDEC or CSNEDEC1).

Access control point

The Encipher - DES access control point controls the function of this service.

Required hardware

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.

Table 2. Encipher required hardware
Server	Required cryptographic hardware	Restrictions
IBM System z9 EC IBM System z9 BC	Crypto Express2 Coprocessor
IBM System z10 EC IBM System z10 BC	Crypto Express2 Coprocessor Crypto Express3 Coprocessor
IBM zEnterprise 196 IBM zEnterprise 114	Crypto Express3 Coprocessor
IBM zEnterprise EC12 IBM zEnterprise BC12	Crypto Express3 Coprocessor Crypto Express4 CCA Coprocessor
IBM z13 IBM z13s	Crypto Express5 CCA Coprocessor