Symmetric Key Decipher (CSNBSYD or CSNBSYD1 and CSNESYD or CSNESYD1)

Use the symmetric key decipher callable service to decipher data using one of the supported modes. ICSF supports several processing rules to decipher data. You choose the type of processing rule that the Symmetric Key Decipher callable service should use for block chaining. See Modes of operation for more information.

For any processing rule that indicates that the plaintext can be any length, this length applies to the overall length of the input data. ICV selection rules FIRST and MIDDLE always require the input text to be a multiple of the block size (segment size for CFB-LCFB).

Processing Rule: Purpose
ANSI X9.23: For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES). The plaintext will be between 1 and 8 bytes shorter than the ciphertext. This process rule always pads the plaintext during encryption so that ciphertext produced is an exact multiple of the block size, even if the plaintext was already a multiple of the blocksize.
CBC: For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext.
CBC-CS: For cipher block chaining. The ciphertext must be at least the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext. ICSF implements CBC-CS1 which preserves block ordering.
CFB: Performs cipher feedback encryption with the segment size equal to the block size. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext.
CFB-LCFB: Performs cipher feedback encryption with the segment size set by the caller. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext.
CTR: Performs counter mode decryption. The ciphertext can be any length. The plaintext will have the same length as the ciphertext.
CUSP: For cipher block chaining. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext.
ECB: Performs electronic code book encryption. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext.
GCM: Perform Galois/Counter mode decryption, which provides both confidentiality and authentication for the plaintext and authentication for the additional authenticated data (AAD). The ciphertext can be any length. The plaintext will have the same length as the ciphertext. Additionally, the authentication tag will be verified before any data is returned.
IPS: For cipher block chaining. The ciphertext can be any length. The plaintext will have the same length as the ciphertext.
OFB: Perform output feedback mode encryption. The ciphertext can be any length. The plaintext will have the same length as the ciphertext.
PKCS-PAD: For cipher block chaining. The ciphertext must be an exact multiple of the block size (8 bytes for DES and 16 bytes for AES). The plaintext will be between 1 and the blocksize (8 bytes for DES, 16 bytes for AES) bytes shorter than the ciphertext. This process rule always pads the ciphertext so that ciphertext produced is an exact multiple of the blocksize, even if the plaintext was already a multiple of the blocksize.

The Advanced Encryption Standard (AES) and Data Encryption Standard (DES) are supported. AES encryption uses a 128-, 192-, or 256-bit key. DES encryption uses a 56-, 112-, or 168-bit key. See the processing rule descriptions for limitations. For each algorithm, certain processing rules are not allowed. See the rule_array parameter description for more information.

All modes except ECB use an initial chaining vector (ICV) in their processing.

All modes that utilize chaining produce a resulting chaining value called the output chaining vector (OCV). The application can pass the OCV as the ICV in the next decipher call. This results in record chaining.

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

The key may be specified as a clear key value, an internal clear key token, or the label name of a clear key or an encrypted key in the CKDS.

Choosing between CSNBSYD and CSNBSYD1

CSNBSYD and CSNBSYD1 provide identical functions. When choosing which service to use, consider this:

CSNBSYD requires the ciphertext and plaintext to reside in the caller's primary address space. Also, a program using CSNBSYD adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface.
The callable service name for AMODE(64) invocation is CSNESYD.
CSNBSYD1 allows the ciphertext and plaintext to reside either in the caller's primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBSYD1 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.
For CSNBSYD1, cipher_text_id and clear_text_id are access list entry token (ALET) parameters of the data spaces containing the ciphertext and plaintext.

The callable service name for AMODE(64) invocation is CSNESYD1.

Format

CALL CSNBSYD(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             key_parms_length,
             key_parms,
             block_size,
             initialization_vector_length,
             initialization_vector,
             chain_data_length,
             chain_data,
             cipher_text_length,
             cipher_text,
             clear_text_length,
             clear_text,
             optional_data_length,
             optional_data)

CALL CSNBSYD1(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             key_parms_length,
             key_parms,
             block_size,
             initialization_vector_length,
             initialization_vector,
             chain_data_length,
             chain_data,
             cipher_text_length,
             cipher_text,
             clear_text_length,
             clear_text,
             optional_data_length,
             optional_data,
             cipher_text_id,
             clear_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/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 assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return/reason codes lists the reason codes.

exit_data_length

Direction	Type
Ignored	Integer

This field is ignored. It is recommended to specify 0 for this parameter.

exit_data

Direction	Type
Ignored	String

This field is ignored.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. The value may be 1, 2, 3 or 4.

rule_array

Direction	Type
Input	String

An array of 8-byte keywords providing the processing control information. The keywords must be in contiguous storage, left-justified and padded on the right with blanks.

Table 1. Symmetric Key Decipher Rule Array Keywords
Keyword	Meaning
*Algorithm (required)*
AES	Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. The block size is 16 bytes. The key length may be 16, 24, or 32 bytes. The chain_data field must be at least 32 bytes in length. The OCV is the first 16 bytes in the chain_data. AES does not support the CUSP, IPS, or X9.23 processing rules.
DES	Specifies that the Data Encryption Standard (DES) algorithm is to be used. The algorithm, DES or TDES, will be determined from the length of the key supplied. The key length may be 8, 16, or 24. The block size is 8 bytes. The chain_data field must be at least 16 bytes in length. The OCV is the first eight bytes in the chain_data. DES does not support the CTR or GCM processing rules.
*Processing Rule (optional)* Rules CBC-CS, CUSP, IPS, PKCS-PAD, and X9.23 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. The text length must be a multiple of the block size for the specified algorithm. CBC is the default value.
CBC-CS	CBC mode (cipher block chaining) with ciphertext stealing. The text length must be at least the block size for the specified algorithm.
CFB	CFB mode (cipher feedback) that is compatible with IBM's Encryption Facility product. Input text may be any length.
CFB-LCFB	CFB mode (cipher feedback). This rule allows the value of s (the segment size) to be something other than the block size (s is set to the block size with the CFB processing rule). key_parms_length and key_parms are used to set the value of s. Input text may be any length.
CTR	CTR mode (counter mode). Input text may be any length.
CUSP	CBC mode (cipher block chaining) that is compatible with IBM's CUSP and PCF products. Input text may be any length.
ECB	Performs electronic code book encryption. The text length must be a multiple of the block size for the specified algorithm.
GCM	GCM (Galois/Counter Mode). key_parms_length and key_parms are used to indicate the length of the tag (the value t) on input and contain the tag on output. Additional Authenticated Data (AAD) is contained in optional_data_length and optional_data. Input text may be any length. GCM does not support chaining, so CONTINUE and FINAL are not allowed for the ICV Selection rule.
GCM-LG	Processing is similar to the GCM rule. Use only when either cipher_text_length or optional_data_length are greater than or equal to 256 MiB (2^28 bits) and legacy authentication tags from ICSF FMID HCR77A1 and lower prior to APAR OA46558 are to be verified.
IPS	CBC mode (cipher block chaining) that is compatible with IBM's IPS product. Input text may be any length.
OFB	OFB mode (output feedback). Input text may be any length.
PKCS-PAD	CBC mode (cipher block chaining) but the ciphertext must be an exact multiple of the block length (8 bytes for DES and 16 bytes for AES). The plaintext will be 1 to 8 bytes shorter for DES and 1 to 16 bytes shorter for AES than the ciphertext.
X9.23	CBC mode (cipher block chaining) for 1 to 8 bytes of padding dropped from the output clear text.
*Key Rule (optional)*
KEY-CLR	This specifies that the key parameter contains a clear key value. KEY-CLR is the default value.
KEYIDENT	This specifies that the key_identifier field will be an internal clear token, or the label name of a clear key or encrypted key in the CKDS. Normal CKDS labelname syntax is required.
*ICV Selection (optional)*
INITIAL	This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value. INITIAL is not valid with processing rule GCM.
CONTINUE	This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. CONTINUE is not valid for processing rules ECB, GCM, or X9.23.
FINAL	This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. Using FINAL indicates that this call contains the last portion of data. FINAL is valid for processing rules CBC-CS, CFB, CFB-LCBF, CTR, and OFB.
ONLY	This specifies taking the initialization vector from the initialization_vector parameter and that the entirety of the data to be processed is in this single call. ONLY is valid for processing rules CBC-CS, CFB, CFB-LCFB, CTR, GCM, and OFB.

key_identifier_length

Direction	Type
Input	Integer

The length of the key_identifier parameter.

For the KEY-CLR keyword, this parameter is the length in bytes of the clear key value only. The maximum size is 256 bytes.

For the KEYIDENT keyword, this parameter value must be 64.

key_identifier

Direction	Type
Input/Output	String

For the KEY-CLR keyword, this specifies the cipher key. The parameter must be left justified.

For the KEYIDENT keyword, this specifies an internal clear token, or the label name of a clear key or an encrypted key in the CKDS. Normal CKDS label name syntax is required.

The key algorithm may be DES or AES. The key type must be DATA for AES fixed-length key tokens, DATA or CIPHER for DES fixed-length key tokens, or CIPHER for variable-length AES key tokens.

For X9.143 (TR-31) key blocks, the identifier is the label of a variable-length key block of an AES, DES, or TDES data-encrypting key: key usage D0, algorithm A, D, or T, and mode use is B or D. IBM optional block "10" is required.

Notes:

To use a fixed-length DES or AES encrypted key in the CKDS, the ICSF segment of the CSFKEYS class general resource profile associated with the specified key label must contain SYMCPACFWRAP(YES). For more information, see z/OS Cryptographic Services ICSF Administrator's Guide.
To use an encrypted variable-length AES CIPHER key token, the key token must allow decryption, the cipher mode is being used, and export to the CPACF protected key format. For information on creating key tokens with the specified attributes, see Key Token Build2 (CSNBKTB2 and CSNEKTB2). See the CKDS KEYS utility Key Attributes panel for information on the current attributes of a CKDS key.
To use an encrypted data-encryption key in a TR-31 key block, the CPACF export control attribute must be enabled in the IBM optional block '10'.

key_parms_length

Direction	Type
Input	Integer

The length of the key_parms parameter.

For the CFB-LCFB and CTR processing rules, this length must be 1.
For the GCM processing rule, this is the length in bytes of the authentication tag to be verified. Valid lengths are 4, 8, 12, 13, 14, 15, 16. Using a length of 4 or 8 is strongly discouraged.
For all other processing rules, this field is ignored.

You must specify the same length used when enciphering the text.

key_parms

Direction	Type
Input	String

This parameter contains key-related parameters specific to the encryption algorithm and processing mode.

For the CFB-LCFB processing rule, this 1-byte field specifies the segment size in bytes. Valid values are 1 to the block size, inclusive. The block size is eight for DES and sixteen for AES.
For the CTR processing rule, this 1-byte field specifies the number of low order bytes of the counter to be incremented. The remaining upper order bytes are the nonce. Valid values are 1 to the block size, inclusive. The blocksize is sixteen for AES.
For the GCM processing rule, this contains the authentication tag for the provided ciphertext (cipher_text parameter) and additional authenticated data (optional_data parameter).
For all other processing rules, this field is ignored.

For the modes where key_parms is used, you must specify the same key_parms used when enciphering the text using the Symmetric Key Encipher.

block_size

Direction	Type
Input	Integer

This parameter contains the processing size of the text block in bytes. This value will be algorithm specific. Be sure to specify the same block size as used to encipher the text.

initialization_vector_length

Direction	Type
Input	Integer

The length of the initialization_vector parameter. This parameter is ignored for the ECB processing rule. For the GCM processing rule, NIST recommends a length of 12, but tolerates any non-zero length. For all other processing rules, the length should be equal to the block length for the algorithm specified.

initialization_vector

Direction	Type
Input	String

The initialization chaining value. You must use the same ICV that was used to encipher the data. This parameter is ignored for the ECB processing rule.

chain_data_length

Direction	Type
Input/Output	Integer

The length of the chain_data parameter. On output, the actual length of the chaining vector will be stored in the parameter. This parameter is ignored if the ICV selection keyword is ONLY.

For AES, this length must be at least 32 bytes. For DES, this length must be at least 16 bytes.

chain_data

Direction	Type
Input/Output	String

This field is used as a system work area for the chaining vector. Your application program must not change the data in this string. The chaining vector holds the output chaining vector from the caller.

The direction is output if the ICV selection keyword is INITIAL. This parameter is ignored if the ICV selection keyword is ONLY.

The mapping of the chain_data depends on the algorithm specified. For AES, the chain_data field must be at least 32 bytes in length. The OCV is in the first 16 bytes in the chain_data. For DES, chain_data field must be at least 16 bytes in length. The OCV is the first 8 bytes in the chain_data.

cipher_text_length

Direction	Type
Input	Integer

The length of the ciphertext. A zero value in the cipher_text_length parameter is not valid except with the GCM processing rule when performing a GMAC operation. The length must be a multiple of the algorithm block size for the CBC, ECB, and PKCS-PAD processing rules, but may be any length with the other processing rules.

cipher_text

Direction	Type
Input	String

The text to be deciphered.

clear_text_length

Direction	Type
Input/Output	Integer

On input, this parameter specifies the size of the storage pointed to by the clear_text parameter, which must be at least the same size as the cipher_text_length. On output, this parameter has the actual length of the text stored in the clear_text parameter.

If process rules PKCS-PAD or X9.23PAD are used, the clear_text_length returned will be less than the cipher_text_length since padding bytes are removed.

clear_text

Direction	Type
Output	String

The deciphered text the service returns.

optional_data_length

Direction	Type
Input	Integer

The length of the optional_data parameter. For the GCM processing rule, this parameter contains the length of the Additional Authenticated Data (AAD). For all other processing rules, this field is ignored.

optional_data

Direction	Type
Input	String

Optional data required by a specified algorithm or processing mode. For the GCM processing rule, this parameter contains the Additional Authenticated Data (AAD). For all other processing rules, this field is ignored.

You must specify the same optional_data used when enciphering the text using Symmetric Key Encipher.

cipher_text_id

Direction	Type
Input	Integer

For CSNBSYD1 only, the ALET of the ciphertext to be deciphered.

clear_text_id

Direction	Type
Input	Integer

For CSNBSYD1 only, the ALET of the clear text supplied by the application.

Usage notes

SAF may be invoked to verify the caller is authorized to use the specified key label stored in the CKDS.
To use a fixed-length DES or AES encrypted key in the CKDS, the ICSF segment of the CSFKEYS class general resource profile associated with the specified key label must contain SYMCPACFWRAP(YES). For more information, see z/OS Cryptographic Services ICSF Administrator's Guide.
To use an encrypted variable-length AES CIPHER key token, the key token must allow decryption, the cipher mode is being used, and export to the CPACF protected key format.
No pre- or post-processing exits are enabled for this service.
The master keys need to be loaded only when using this service with encrypted key labels.
The AES algorithm will use hardware if it is available. Otherwise, clear key operations will be performed in software.
AES has the same availability restrictions as triple-DES.
This service will fail if execution would cause destructive overlay of the cipher_text field.

Access control points

When the label of an encrypted key is specified for the key_identifier parameter, the appropriate access control point must be enabled.

Table 2. Required access control points for Symmetric Key Decipher
Key algorithm	Access control point
Crypto Express5 and earlier CCA coprocessors
AES	High-performance secure AES keys
DES	High-performance secure DES keys
Crypto Express6 and later CCA coprocessors
All	Authenticated Key Export - EXPTSK

For AES CIPHER keys (CEX6C and later), the following access controls must be enabled:

Authenticated Key Export - DRVTXKEY
Authenticated Key Export - EXPTSK
Authenticated Key Export - SETSNKEY

These access controls should be enabled by default, but Authenticated Key Export - EXPTSK may not be enabled and will cause return codes that are misleading.

Required hardware

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. The CCA releases used in the table are described in CCA release levels.

Table 3. Symmetric Key Decipher required hardware
Server	Required cryptographic hardware	Restrictions
IBM z14 IBM z14 ZR1	CP Assist for Cryptographic Functions Crypto Express5 CCA Coprocessor Crypto Express6 CCA Coprocessor	Encrypted keys require a Crypto express coprocessor. Encrypted variable-length AES CIPHER key tokens require a CEX6C. Triple-length DES DATA keys with a non-zero control vector require a CEX6C with the November 2018 or later licensed internal code (LIC). DES CIPHER key tokens require a CEX6C with the P41458.002 or later MCL. Compliant-tagged key tokens require a CEX6C with the July 2019 or later licensed internal code (LIC). X9.143 key blocks are not supported.
IBM z15 IBM z15 T02	CP Assist for Cryptographic Functions Crypto Express5 CCA Coprocessor	Compliant-tagged key tokens are not supported. Encrypted keys require a Crypto express coprocessor. DES and AES CIPHER key tokens and triple-length DES DATA keys with a non-zero control vector are not supported. X9.143 key blocks are not supported.
IBM z15 IBM z15 T02	CP Assist for Cryptographic Functions Crypto Express6 CCA Coprocessor Crypto Express7 CCA Coprocessor	Encrypted keys require a Crypto express coprocessor. X9.143 key blocks are not supported.
IBM z16 IBM z16 A02	CP Assist for Cryptographic Functions Crypto Express6 CCA Coprocessor Crypto Express7 CCA Coprocessor	Encrypted keys require a Crypto express coprocessor. X9.143 key blocks are not supported.
IBM z16 IBM z16 A02	Crypto Express8 CCA Coprocessor	X9.143 key blocks support requires the CCA release 8.1 or later licensed internal code (LIC).

Related information

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

pppppp
     cccccc  is supported. 

cccccc
     pppppp  is not supported.

ppppppcccccc is supported.

p represents the plaintext and c represents the ciphertext.

Cipher processing rules discusses the cipher processing rules.