Parameters
The parameters for CSNDSYX.
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
A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1, 2, or 3.Direction: Input Type: Integer - rule_array
Keywords that provide control information to the verb. Each keyword is left-aligned in 8-byte fields and padded on the right with blanks. All keywords must be in contiguous storage. The rule_array keywords are described in Table 1.Direction: Input Type: String array Table 1. Keywords for Symmetric Key Export control information Keywords for Symmetric Key Export control information
Keyword Description Algorithm (One, optional) AES Export an AES key. If source_key_identifier is a variable-length symmetric key token or label, only the CKM_RAKW, PKOAEP2, and AESKW key formatting methods are supported. DES Export a DES key. This is the default. HMAC Export an HMAC key. Only the PKOAEP2 and AESKW key formatting methods are supported. Key-formatting method (One, required, see Table 2 and Table 3.) AESKW Specifies that the key is to be formatted using AESKW and placed in an external variable length CCA token. The transport_key_identifier must be an AES EXPORTER. This rule is not valid with the DES algorithm keyword or with AES DATA (version X'04') keys. AESKWCV Specifies to return the key formatted using the ANS X9.102 AESKW method creating a special variable-length symmetric key-token whose key type is DESUSECV. The AESKW payload that contains the DES key is encrypted by the AES EXPORTER key-encrypting key provided as the transport key, and returned in an external variable-length symmetric key-token with a token algorithm of DES. The DES control vector (with its key form bits masked to binary zeros to mask the key length) along with other significant key-token information is included in the associated data section of the variable-length symmetric key-token. Valid only with the DES algorithm, and only for a DES key in a fixed-length symmetric key-token. PKCSOAEP Specifies using the method found in RSA DSI PKCS #1V2 OAEP. See PKCS #1 hash formats. The default hash method is SHA-1. Use the SHA-256 keyword for the SHA-256 hash method. Use the SHA-384 keyword for the SHA-384 hash method. Use the SHA-512 keyword for the SHA-512 hash method. PKCS-1.2 Specifies using the method found in RSA DSI PKCS #1 block type 02 to recover the symmetric key. In the RSA PKCS #1 v2.0 standard, RSA terminology describes this as the RSAES-PKCS1-v1_5 format. See PKCS #1 hash formats. This method is deprecated and should not be used for any new development. PKOAEP2 Specifies that the key is formatted as defined in the RSA PKCS #1 v2.1 standard for the RSAES-OAEP encryption mechanism. Valid only with algorithm HMAC. See PKCS #1 hash formats. 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. CKM-RAKW Specifies to return the key in an external AES wrapped (PKCS#11) object. That is, the variable-length symmetric key-token will be returned in an output format corresponding to the output from PKCS#11 mechanism CKM_RSA_AES_KEY_WRAP. Valid only with the AES algorithm. See also Target RSA-AES-protected (PKCS #11) format. Hash method (One, optional for PKCSOAEP, required for PKOAEP2. Not valid with any other key formatting method. See also Restrictions) SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. Valid only with key-formatting methods PKCSOAEP or PKOAEP2. This is the default for PKCSOAEP. SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash. Valid only with key-formatting methods PKCSOAEP or PKOAEP2. SHA-384 Specifies to use the SHA-384 hash method to calculate the OAEP message hash. Valid only with key-formatting method PKOAEP2. SHA-512 Specifies to use the SHA-512 hash method to calculate the OAEP message hash. Valid only with key-formatting method PKOAEP2. 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. - source_key_identifier_length
The length of the source_key_identifier parameter. The minimum size is 64 bytes. If the source_key_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 725.Direction: Input Type: Integer - source_key_identifier
The key to be exported and wrapped by the transport_key_identifier. The key identifier is an operational token or the key label of an operational token in key storage.Direction: Input Type: String The key in the key identifier must match the algorithm in the rule_array. DES is the default algorithm.
For formatting method rules PKCSOAEP, PKCS-1.2, and ZERO-PAD, the source key is an AES or DES DATA key in a fixed-length key token.
For rule AESKWCV, the source key is a DES key of any type in a fixed-length key token.
For rules AESKW and PKOAEP2, the source key is an AES or HMAC key of any type in a variable-length key token.
For CKM-RAKW, the source key must be an AES CIPHER key in a variable-length symmetric key token.
If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key.
- transporter_key_identifier_length
The length of the transporter_key_identifier parameter. The maximum size is 9992 bytes for a TR-31 AES EXPORTER token, 3500 bytes for an RSA key token or 725 for an AES EXPORTER key token. The length must be 64 if transporter_key_identifier is a label.Direction: Input Type: Integer - transporter_key_identifier
Direction: Input Type: String The key to wrap the source key in a formatted data buffer or external key token. The key identifier is an operational token, the key label of an operational token in key storage, or an X.509 certificate containing the public key.
When the AESKW or AESKWCV key formatting method is specified, this parameter must be a CCA or TR-31 AES EXPORTER key token, an RSA token (or the X.509 certificate containing the RSA public key), or the label of such a token.
A CCA AES EXPORTER token must have the EXPORT bit on in the key-usage field. The key usage wrap algorithm control must match the algorithm of the source key. The key usage wrap class control must match the class of the source key.
A TR-31 AES EXPORTER token must have the following attributes:
- TR-31 key usage: K0
- Algorithm: A
- TR-31 mode of key use: E
When translating to the PKCS #11 format using the CKM-RAKW keyword, this parameter must be a CCA key token containing an RSA public key. See also Target RSA-AES-protected (PKCS #11) format.
The specified Key-formatting method determines whether a public- key or a key-encrypting key is required as the transport key. See Table 2 and Table 3.Certificates may be PEM-formatted EBCDIC text or DER-encoded. The certificate may either have no key usage attribute, or it must have the following usage: keyEncipherment.
When the identifier is an AES EXPORTER and the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key.
- enciphered_key_length
The length of the enciphered_key parameter. This variable is updated with the actual length of the generated enciphered key. The maximum size you can specify in this parameter is 3500 bytes.Direction: Input/Output Type: Integer - enciphered_key
A pointer to a string variable containing the key after it has been formatted and enciphered by the transport key. The enciphered key is returned either as an opaque data buffer or in an external variable-length symmetric key-token. For key-formatting method PKOAEP2, the key token has no key verification pattern.Direction: Output Type: String If you use the CKM-RAKW keyword, this buffer can contain an output format corresponding to the output from the PKCS #11 mechanism CKM_RSA_AES_KEY_WRAP.