Parameters

Edit online

The parameters for CSNDSYG.

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 elements in the rule_array variable. This value must be 1 - 7.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. The recovery method is the method to use to recover the symmetric key. Each keyword is left-aligned in an 8-byte field and padded on the right with blanks. All keywords must be in contiguous storage. The rule_array keywords are described in Table 1.
Table 1. Keywords for Symmetric Key Generate control information

Keywords for Symmetric Key Generate control information
Keyword Description
Algorithm (One, optional)
AES Specifies to generate a CCA or TR-31 AES key.
DES Specifies to generate a CCA or TR-31 DES key. This is the default.
Key-formatting method (One required)
PKA92 Specifies the key-encrypting key is to be encrypted under a PKA96 RSA public key according to the PKA92 formatting structure.
PKCSOAEP Specifies to use the method found in RSA DSI PKCS #1V2 OAEP. Supported by the DES and AES algorithms. The default hash method is SHA-1. Use the SHA-256 keyword for the SHA-256 hash method.
PKCS-1.2 Specifies the method found in RSA DSI PKCS #1 block type 02. In the RSA PKCS #1 v2.0 standard, RSA terminology describes this as the RSAES-PKCS1-v1_5 format. This method is deprecated and should not be used for any new development.
ZERO-PAD The clear key is right-aligned in the field provided, and the field is padded to the left with zeros up to the size of the RSA encryption block (which is the modulus length). This method is deprecated and should not be used for any new development.
Key length (One, optional use with PKA92)
SINGLE-R Generates a key-encrypting key that has equal left and right halves allowing it to perform as a single-length key. Valid only for the recovery method of PKA92.
Key length (One, optional use with PKCSOAEP, PKCS-1.2, or ZERO-PAD)
SINGLE, KEYLN8 Generates a single-length DES key. This is the default for DES keys.
DOUBLE Generates a double-length DES key. Valid only for DES keys.
KEYLN16 Generates a double-length DES DATA key. This is the default for AES keys.
KEYLN24 Generates a triple-length DES DATA key. Valid only for AES keys
KEYLN32 Generates a 32-byte AES key. Valid only for AES keys
Encipherment method for the local enciphered copy of the key (One, optional for use with PKCSOAEP, PKCS-1.2, and ZERO-PAD)
EX The DES enciphered key is enciphered by a CCA or TR-31 EXPORTER key that is provided through the key_encrypting_key_identifier parameter.
IM The DES enciphered key is enciphered by a CCA or TR-31 IMPORTER key that is provided through the key_encrypting_key_identifier parameter.
OP The DES enciphered key is enciphered by the master key. The key_encrypting_key_identifier parameter is ignored. This is the default.
Key-wrapping method (One, optional). Not valid when the local_enciphered_key_identifier parameter contains a TR-31 token.
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 Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard.
WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens.
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) This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary zeros.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method after it has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.
Hash method (Optional). Valid only with keyword PKCSOAEP.
SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. This is the default.
SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash.
Certificate validation method (One required when the input is an X.509 certificate. Otherwise, must not be specified.)
RFC-2459 Attempt to validate the certificate using the semantics of RFC-2459.
RFC-3280 Attempt to validate the certificate using the semantics of RFC-3280
RFC-5280 Attempt to validate the certificate using the semantics of RFC-5280
RFC-ANY Attempt to validate the certificate using first the semantics of RFC-2459, then RFC-3280, and then RFC-5280. If the certificate is not compliant with any RFC, the first error encountered (from RFC-2459 processing) is returned.
Public key infrastructure usage (one optional when the input is an X.509 certificate. Otherwise, must not be specified).
PKI-CHK Specifies that the X.509 certificate for the other party (KRD) is to be validated against the trust chain of the PKI hosted in the adapter. This requires that the CA credentials have been installed using the Trusted Key Entry (TKE) workstation.

This is the default.
PKI-NONE Specifies that the X.509 certificate for the other party (KRD) is not to be validated against the trust chain of the PKI hosted in the adapter. This is suitable if the certificate has been validated using host-based PKI services.
key_encrypting_key_identifier
Direction: Input/Output
Type: String

The label or internal token of a CCA or TR-31 key-encrypting key to wrap the generated key. The key identifier is a variable-length operational key token or key block or the 64-byte label of an operational token or block in key storage.

The maximum length of the key token or block is 9992 bytes.

  • When the rule_array specifies IM and DES, the key identifier is a:
    • 64-byte CCA DES key token of key type IMPORTER.
    • Variable-length TR-31 DES key block of an importer key-encrypting key with key usage: K0 or K1, algorithm: T, and TR-31 mode of key use: D.
  • When the rule_array specifies EX and DES, the key identifier is a:
    • 64-byte CCA DES key token of key type EXPORTER.
    • Variable-length TR-31 DES key block of an importer key-encrypting key with key usage: K0 or K1, algorithm: T, and TR-31 mode of key use: E.
  • When the rule_array specifies IM and AES, the key identifier is a:
    • 64-byte CCA AES key token of key type IMPORTER.
    • Variable-length TR-31 AES key block of an importer key-encrypting key with key usage: K0 or K1, algorithm: A, and TR-31 mode of key use: D.
  • When the rule_array specifies EX and AES, the key identifier is a:
    • 64-byte CCA AES key token of key type EXPORTER.
    • Variable-length TR-31 AES key block of an importer key-encrypting key with key usage: K0 or K1, algorithm: A, and TR-31 mode of key use: E.
    • Otherwise, the parameter is ignored.

Notes:

  • K0 is required to wrap non-TR-31 key blocks.
  • K1 is required to wrap TR-31 key blocks.
RSA_public_key_identifier_length
Direction: Input
Type: Integer
The length of the RSA_public_key_identifier parameter. If the RSA_public_key_identifier parameter is a label, this parameter specifies the length of the label. The maximum size is 9992 bytes.
RSA_public_key_identifier
Direction: Input
Type: String
The token, or label, of the RSA public key to be used for protecting the generated symmetric key.
local_enciphered_key_identifier_length
Direction: Input/Output
Type: Integer
The length of the local_enciphered_key_identifier. This field is updated with the actual length of the local_enciphered_key_identifier that is generated. The maximum length is 9992 bytes. However, this value should be 64 for a key label or a CCA DES key-token. For TR-31 key-tokens this value should be the length in bytes of the buffer for the local_enciphered_key_identifier parameter.
local_enciphered_key_identifier
Direction: Input/Output
Type: String
A pointer to a string variable containing either a key label or a key token. For CCA tokens, the control vector for the local key is taken from the identified key token. On output, the generated key is inserted into the identified key token.

Beginning with CCA Release 8.2, you can specify a variable-length AES skeleton token or a TR-31 key block.

On input, you must specify a token type consistent with your choice of local-key encryption and algorithm. If you specify IM or EX type, you must specify an external fixed-length DES key-token, or an external variable-length AES key-token, or a TR-31 key block. Otherwise, specify an internal fixed-length AES or DES key-token or an internal variable-length AES key-token, a TR-31 key token, or a null fixed-length key-token.

If you want your output to be a TR-31 token, then the input must be a TR-31 skeleton token. Otherwise, if a CCA token or a NULL token is input, then a CCA token will contain the output.

When PKCSOAEP, PKCS-1.2, or ZERO-PAD is specified, a DATA key is returned. A null key-token can be specified. In this case, a default AES or DES DATA key is returned. For an internal key (OP), a default DATA control vector is returned in the key token. For an external key (IM or EX), the control vector is set to binary zero. Beginning with CCA Release 7.5, a variable-length AES CIPHER or MAC skeleton token may be specified.

When using the PKA92 keyword, specify a compliant-tagged key on input to generate a compliant-tagged output key.

Table 2. Requirements for the key identifier

Requirements for the key identifier
Rule array keyword Desired output identifier
CCA 64-byte DES key token CCA variable-length AES key token TR-31 key block
PKA92 64-byte internal operational or skeleton token of a DES IMPORTER or EXPORTER key. N/A N/A
DES with PKCSOAEP PKCS-1.2 ZEROPAD 64-byte null. N/A Skeleton block of a DES data-encrypting key (key usage D0, algorithm T, and mode use B, D or E).
AES with PKCSOAEP PKCS-1.2 ZEROPAD 64-byte null. Skeleton token of an AES CIPHER or MAC key. Skeleton block of an AES data-encrypting key (key usage D0, algorithm A, and mode use B, D or E).
RSA_enciphered_key_length
Direction: Input/Output
Type: Integer
The length of the RSA_enciphered_key parameter. This verb updates this with the actual length of the RSA_enciphered_key it generates. The maximum size is 3500 bytes.
RSA_enciphered_key
Direction: Input/Output
Type: String
A pointer to a string variable containing the generated RSA-enciphered key returned by the verb. If you specify PKCSOAEP, PKCS-1.2, or ZERO-PAD, on input specify a null key token. If you specify PKA92, on input specify an internal (operational) CCA DES key-token.