Symmetric Key Encipher (CSNBSYE or CSNBSYE1 and CSNESYE or CSNESYE1)
Use the symmetric key encipher callable service to encipher data using one of the supported modes. ICSF supports several processing rules to encipher data. You choose the type of processing rule that the Symmetric Key Encipher callable service should use for the 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 plaintext may be any length. The ciphertext will be between 1 and 8 bytes longer than the plaintext. 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 plaintext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The ciphertext will have the same length as the plaintext.
- CBC-CS
- For cipher block chaining. The plaintext 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 plaintext can be of any length. The ciphertext will have the same length as the plaintext.
- CFB-LCFB
- Performs cipher feedback encryption with the segment size set by the caller. The plaintext can be of any length. The ciphertext will have the same length as the plaintext.
- CTR
- Performs counter mode encryption. The ciphertext can be any length. The plaintext will have the same length as the ciphertext.
- CUSP
- For cipher block chaining. The plaintext can be of any length. The ciphertext will have the same length as the plaintext.
- ECB
- Performs electronic code book encryption. The plaintext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The ciphertext will have the same length as the plaintext.
- GCM
- Perform Galois/Counter mode encryption, which provides both confidentiality and authentication for the plaintext and authentication for the additional authenticated data (AAD). The plaintext can be of any length. The ciphertext will have the same length as the plaintext. Additionally, the authentication tag will be verified before any data is returned.
- IPS
- For cipher block chaining. The plaintext can be of any length. The ciphertext will have the same length as the plaintext.
- OFB
- Perform output feedback mode encryption. The plaintext can be of any length. The ciphertext will have the same length as the plaintext.
- PKCS-PAD
- For cipher block chaining. The plaintext may be any length. The ciphertext will be between 1 and 8 bytes longer than the plaintext. 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 tolerate chaining produce 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.
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.
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 CSNBSYE and CSNBSYE1
- CSNBSYE requires the cleartext and ciphertext to reside
in the caller's primary address space. Also, a program using CSNBSYE
adheres to the IBM Common Cryptographic Architecture: Cryptographic
Application Programming Interface.
The callable service name for AMODE(64) invocation is CSNESYE.
- CSNBSYE1 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 CSNBSYE1 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 CSNBSYE1, clear_text_id and cipher_text_id are access list entry token (ALET) parameters of the data spaces containing the cleartext and ciphertext.
The callable service name for AMODE(64) invocation is CSNESYE1.
Format
CALL CSNBSYE(
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,
clear_text_length,
clear_text,
cipher_text_length,
cipher_text,
optional_data_length,
optional_data)
CALL CSNBSYE1(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
length,
key_identifier,
key_parms_length,
key_parms,
block_size,
initialization_vector_length,
initialization_vector,
chain_data_length,
chain_data,
clear_text_length,
clear_text,
cipher_text_length,
cipher_text,
optional_data_length,
optional_data,
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/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 Encipher 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 CBC mode (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). The key_parms_length and key_parms parameters 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 ECB mode (electronic codebook). The text length must be a multiple of the block size for the specified algorithm. GCM GCM mode (Galois/Counter Mode). The key_parms_length and key_parms parameters 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 the optional_data_length and optional_data parameters. Input text may be any length. GCM-LG Processing is similar to the GCM rule. Use only when either clear_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 generated. 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) not necessarily in exact multiples of the block length (8 bytes for DES and 16 bytes for AES). PKCS-PAD always pads the plaintext so that the ciphertext produced is an exact multiple of the block length and longer than the plaintext. X9.23 CBC mode (cipher block chaining) for 1 to 8 bytes of padding added according to ANSI X9.23. Input text may be any length. Key Rule (optional) KEY-CLR This specifies that the key parameter contains a clear key value. KEY-CLR is the default. 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.
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 E. 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 encryption, 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.When deciphering the text, you must specify this same length.- 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 generated. 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.
- key_parms
-
Direction Type Input/Output 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 blocksize, 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 will contain the generated authentication tag for the provided plaintext (plain_text parameter) and additional authenticated data (optional_data parameter).
- For all other processing rules, this field is ignored.
- block_size
-
Direction Type Input Integer This parameter contains the processing size of the text block in bytes. This value will be algorithm specific.
- 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 to decipher 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, the chain_data field must be at least 16 bytes in length. The OCV is the first 8 bytes in the chain_data.
- clear_text_length
-
Direction Type Input Integer The length of the cleartext. A zero value in the clear_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. For the processing rules that support partial blocks (or segments for CFB-LCFB), it is recommended that the final block (or segment) be the only one that is partial. Having a partial block in the middle is not a supported operation as defined by the standards documents and may not be portable to other encryption systems.
- clear_text
-
Direction Type Input String The text to be enciphered.
- cipher_text_length
-
Direction Type Input/Output Integer On input, this parameter specifies the size of the storage pointed to by the cipher_text parameter. On output, this parameter has the actual length of the text stored in the buffer addressed by the cipher_text parameter.
- cipher_text
-
Direction Type Output String The enciphered 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), and may be any length, including zero. For all other processing rules, this field is ignored.
- optional_data
-
Direction Type Input String Optional data required by a specified algorithm. 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 when deciphering the text using Symmetric Key Decipher.
- clear_text_id
-
Direction Type Input Integer For CSNBSYE1 only, the ALET of the clear text to be enciphered.
- cipher_text_id
-
Direction Type Input Integer For CSNBSYE1 only, the ALET of the ciphertext that the application supplied.
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 encryption, 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 the 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 clear_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.
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 |
- Authenticated Key Export - DRVTXKEY
- Authenticated Key Export - EXPTSK
- Authenticated Key Export - SETSNKEY
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.
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. |
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. |
Crypto Express8 CCA Coprocessor |
X9.143 key blocks support requires the CCA release 8.1 or later licensed internal code (LIC). |
Related information
pppppp
cccccc is not supported.
cccccc
pppppp is 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 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.