Parameters

Edit online

The parameters for CSNDRKX.

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
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of keywords in the rule_array variable. This number must be 0, 1 or 2.
rule_array
Direction: Output
Type: String array
The rule_array is an array of keywords. The keywords must be 8 bytes of contiguous storage with the keyword left-justified in its 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Remote Key Export control information

Keywords for Remote Key Export control information
Keyword Description
Key wrapping method (Optional)
USECONFG This is the default. Specifies to wrap the key using the configuration setting for the default wrapping method. The default wrapping method configuration setting may be changed using the TKE. This keyword is ignored for AES keys.
WRAP-ENH Specifies that the new enhanced wrapping method is to be used to wrap the key.
WRAP-ECB Specifies that the original wrapping method is to be used.
WRAPENH2 Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only for TRIPLE or TRIPLE-O. This method requires CV bit 56 = B’1’ (ENH-ONLY). This is the default for TRIPLE and TRIPLE-O.
WRAPENH3 Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and the SHA-256 hashing algorithm. This keyword sets CV bit 56 = B’1’ (ENH-ONLY), which is required for the WRAPENH3 wrapping method.
Translation control (Optional, valid only for enhanced wrapping)
ENH-ONLY Specify this keyword to indicate that the key once wrapped with the enhanced method cannot be wrapped with the original method. This restricts translation to the original method.
trusted_block_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the trusted_block_identifier variable. The maximum length is 3500 bytes.
trusted_block_identifier
Direction: Input
Type: String
A pointer to a string variable containing a trusted block key-token of an internal trusted block, or the key label of a trusted block key-token record of an internal trusted block. It is used to validate the public-key certificate and to define the rules for key generation and key export.
certificate_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the certificate variable. The maximum length is 5000 bytes.

It is an error if the certificate_length variable is 0 and the trusted block’s asymmetric encrypted output key format in the rule section selected by the rule_id variable indicates PKCS-1.2 output format or RSA-OAEP output format.

If the certificate_length variable is 0 or the trusted block’s asymmetric encrypted output key format in the rule section selected by the rule_id variable indicates no asymmetric key output, the certificate is ignored.

certificate
Direction: Input
Type: String
A pointer to a string variable containing a public-key certificate. The certificate must contain the public-key modulus and exponent in binary form, as well as a digital certificate. The certificate must verify using the root public key that is in the trusted block pointed to by the trusted_block_identifier parameter.
Note: After the hash is computed over the certificate data specified by offsets 28 and 32, the hash is BER encoded by pre-pending these bytes:

X'30213009 06052B0E 03021A05 000 414'

See PKCS #1 hash formats.
certificate_parms_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the certificate_parms variable. The length must be 36 bytes if the certificate_length variable is 0, else the length must be 0.
certificate_parms
Direction: Input
Type: String
A pointer to a string variable containing a structure for identifying the location and length of values within the public-key certificate pointed to by the certificate parameter. If the value of the certificate_length variable is 0, then the information in this variable is ignored but the variable must be declared. The format of the certificate_parms variable is defined in Table 2.
Table 2. Keywords for Remote Key Export certificate_parms parameter

Keywords for Remote Key Export certificate_parms parameter
Offset (bytes) Length (bytes) Description
0 4 Offset of modulus
4 4 Length of modulus
8 4 Offset of public exponent
12 4 Length of public exponent
16 4 Offset of digital signature
20 4 Length of digital signature
24 1 Identifier for hash algorithm. The following values are defined:
Identifier
Hash algorithm
X'01'
SHA-1
X'02'
MD5 (Currently not supported)
X'03'
RIPEMD-160 (Currently not supported)
25 1 Identifier for digital signature hash formatting method used. The following values are defined:
Identifier
Hash formatting method
X'01'
PKCS-1.0
X'02'
PKCS-1.1
X'03'
X9.31 (Currently not supported)
X'04'
ISO-9796 (Currently not supported)
X'05'
ZERO-PAD (Currently not supported)
26 2 Reserved, must be binary zeros
28 4 Offset of first byte of certificate data hashed to compute the digital signature
32 4 Length of certificate data hashed to compute the digital signature
Note: The modulus, exponent, and signature values can have bit lengths that are not multiples of 8; each of these values is right-aligned and padded on the left with binary zeroes to make it an even number of bytes in length.
transport_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the transport_key_identifier variable. The length must be 0 or 64 bytes.
transport_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing a KEK key-token, or a key label of a KEK key-token record. The KEK is either an internal CCA DES key-token (key type IMPORTER or EXPORTER), or an external version X'10' (RKX) DES key-token. It is used to encrypt a key exported by the verb.

When the symmetric encrypted output key format flag of the selected rule indicates return an RKX key-token, this parameter is ignored but must be declared.

  • If this parameter points to a CCADES key-token, the token must be of key type IMPORTER or EXPORTER.
  • If the source_key_identifier parameter identifies an internal CCA DES key-token, the token must be of key type EXPORTER.

For more information on RKX key tokens, see External RKX DES key tokens.

rule_id_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the rule_id variable. The length must be eight bytes.
rule_id
Direction: Input
Type: String
A pointer to a string variable that identifies the rule in the trusted block to be used to control key generation or export. The trusted block can contain multiple rules, each of which is identified by a unique rule ID value.
importer_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the importer_key_identifier variable. The length must be 0 or 64 bytes.
importer_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing an IMPORTER KEK key-token or a label of an IMPORTER KEK key-token record. This KEK is used to decipher the key pointed to by the source_key_identifier parameter.

This variable is ignored if the verb is used to generate a new key, or the source_key_identifier variable contains either an RKX key token or an internal CCA DES key-token. For more information on RKX key tokens, see External RKX DES key tokens.

source_key_identifier_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the source_key_identifier variable. The length must be 0 or 64 bytes.
source_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing a DES key-token or a label of a DES key-token record. The key token contains the key to be exported, and must meet one of these criteria:
  • It is a single-length or double-length external CCA DES key-token.
  • It is a single-length or double-length internal CCA DES key-token.
  • It is a single-length, double-length, or triple-length RKX key-token.
Note:
  1. If the key token is a CCA DES key-token, its XPORT-OK control vector bit (bit 17) must be B'1', or else the export will not be allowed.
  2. If a DES key-token has three 8-byte key parts, the parts are considered unique if any two of the three key parts differ.
asym_encrypted_key_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the asym_encrypted_key variable. On output, the variable is updated with the actual length of the asym_encrypted_key variable. The input length must be at least the length of the modulus in bytes of the public-key in the certificate variable.
asym_encrypted_key
Direction: Output
Type: String
A pointer to a string variable containing a generated or exported clear key returned by the verb. The clear key is encrypted by the public (asymmetric) key provided by the certificate variable.
sym_encrypted_key_identifier_length
Direction: Input/Output
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the sym_encrypted_key_identifier variable. On output, the variable is updated with the actual length of the sym_encrypted_key_identifier variable. The input length must be a minimum of 64 bytes.
sym_encrypted_key_identifier
Direction: Output
Type: String
A pointer to a string variable. On input, the sym_encrypted_key_identifier variable must contain either a key label of a CCA DES key-token record or an RKX key-token record, or be filled with binary zeros.

On output, the verb produces a CCA DES key-token or an RKX key-token, depending on the value of the symmetric encrypted output key format value of the rule section within the trusted_block_identifier variable. The key token produced contains either a generated or exported key encrypted using the key-encrypting key provided by the transport_key_identifier variable.

  • If the output is an external CCA DES key-token:
    1. If a common export key parameters subsection (X'0003') is present in the selected rule, the control vector (CV) is copied from the subsection into the output CCA DES key-token. Otherwise, the CV is copied from source key-token.
    2. If a transport key variant subsection (X'0001') is present in the selected rule, the key is multiply enciphered under the transport key XORed with the transport key variant from the subsection. Otherwise, the key is multiply enciphered under the transport key XORed with binary zero
    3. XORs the CV in the token with the encrypted result from the previous step.
    4. Stores the previous result in the token and updates the TVV.
  • If the output is an (external) RKX key-token:
    1. Encrypts the key using a variant of the trusted block MAC key.
    2. Builds the token with the encrypted key and the rule_id variable.
    3. Calculates the MAC of the token contents and stores the result in the token.

If the sym_encrypted_key_identifier variable is a key label on input, on output the key token produced by the verb is stored in DES key-storage and the variable remains the same. Otherwise, on output the variable is updated with the key token produced by the verb, provided the field is of sufficient length.

extra_data_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the extra_data variable. The length must be less than or equal to the byte length of the certificate public key modulus minus the generated/exported key length minus 42 (X'2A'), which is the OAEP overhead. For example, if the public key in the certificate has a modulus length of 1024 bits (128 bytes), and the exported key is single length, then the extra data length must be less than or equal to 128 minus 8 minus 42, which equals 78.
extra_data
Direction: Input
Type: String
A pointer to a string variable containing extra data to be used as part of the OAEP key-wrapping process. The extra_data variable is used when the output format for the RSA-encrypted key that is returned in the asym_encrypted_key variable is RSA-OAEP; otherwise, it is ignored.
Note: The RSA-OAEP format is specified as part of the rule in the trusted block.
key_check_parameters_length
Direction: Input
Type: Integer
A pointer to an integer variable containing the number of bytes of data in the key_check_parameters variable. The length must be 0.
key_check_parameters
Direction: Input
Type: String
Reserved for future use.
key_check_value_length
Direction: Input/Output
Type: Integer
A pointer to a string variable containing the number of bytes of data in the key_check_value variable. On output, and if the field is of sufficient length, the variable is updated with the actual length of the key_check_value variable.
key_check_value
Direction: Output
Type: String
A pointer to a string variable containing the result of the key-check algorithm chosen in the rule section of the selected trusted block. See Encrypt zeros DES-key verification algorithm and Modification Detection Code calculation. When the selected key-check algorithm is to encrypt an 8-byte block of binary zeros with the key, and the generated or exported key is:
  • Single length
    1. A value of 0, 1, or 2 is considered insufficient space to hold the output encrypted result, and the verb returns an error.
    2. A value of 3 returns the leftmost three bytes of the encrypted result if the key_check_value_length variable is 3 or greater. Otherwise, an error is returned.
    3. A value of 4 - 8 returns the leftmost four bytes of the encrypted result if the key_check_value_length variable is 4 or greater. Otherwise, an error is returned.
  • Double length or triple length

    The verb returns the entire 8-byte result of the encryption in the key_check_value variable if the key_check_value_length variable is 8 or more. Otherwise, an error is returned.

When the selected key-check algorithm is to compute the MDC-2 hash of the key, and the generated or exported key is single length, the 8-byte key is made into a double-length key by replicating the key halves. This is because the MDC-2 calculation method does no padding, and requires that the data be a minimum of 16 bytes and a multiple of eight bytes. If the generated or exported key is double length or triple length, the key is processed as is. The verb returns the 16-byte hash result of the key in the key_check_value variable if the key_check_value_length variable is large enough, else an error is returned.