Parameters

Edit online

The parameters for CSNDPKT.

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. The value must be in the range 1 - 3.
rule_array
The process rules for the verb. The keyword must be in eight bytes of contiguous storage, left-aligned, and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for PKA Key Translate control information
Keyword Description
Process rules (one of the following Process subgroup rules is required).
Translation rules
CKM-RAKW Specifies the translation of an external CCA key token containing an RSA or ECC private key into an external encrypted PKCS #11 object.

The target transport key is an RSA CCA public key to wrap the ephemeral AES key that wraps the private key in the object.
EMVCRT This keyword indicates translating an external RSA CRT key into EMV CRT format and wrapping with TDES-ECB.

The XLATE bit (bit 22) must be set in the target_transport_key control vector if using a CCA KEK.
EMVDDA This keyword indicates translating an external RSA CRT key into EMV DDA format and wrapping with TDES-CBC.

The XLATE bit (bit 22) must be set in the target_transport_key control vector if using a CCA KEK.
EMVDDAE This keyword indicates translating an external RSA CRT key into EMV DDAE format and wrapping with TDES-ECB.

The XLATE bit (bit 22) must be set in the target_transport_key control vector if using a CCA KEK.
SCCOMCRT This keyword indicates translating the key into the smart card Chinese Remainder Theorem format.
SCCOMME This keyword indicates translating the key into the smart card Modulus-Exponent format.
SCVISA This keyword indicates translating the key into the smart card Visa proprietary format.
Conversion rules
COMP-TAG Convert the source_key into a compliant-tagged token.

When the input key type is not RSAAESC2 or RSAAESM2, the following rules apply:

  • When key-usage KM-ONLY is enabled, the token will be converted to a compliant-tagged RSAAESC2 or RSAAESM2 with key-usage U-KEYENC enabled.
  • When key-usage SIG-ONLY is enabled, the token will be converted to a compliant-tagged RSAAESC2 or RSAAESM2 with key-usage U-DIGSIG enabled.
  • For all other key-usages, use INTUSCHG to set the desired usage prior to using COMP-TAG.
EXTDWAKW Specifies that the source key is an external DES wrapped token to be converted to an AESKW wrapped token.
INTDWAKW Specifies that the source key is an internal DES wrapped token to be converted to an AESKW wrapped token.
INTUSCHG Change the usage attributes of the key. Requires keyword group PKA Key Usage Control.

Not valid if the input key is compliant-tagged.
Compliant checking rules
COMP-CHK Check if the source_key can have the compliant tag.
Certificate validation method (One required when the input is an X.509 certificate and when using COMP-CHK. Otherwise, not allowed).
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 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.
Export rules
ECC-AES1 Export an ECC key into a token wrapped by a CCA or TR-31 AES key-encrypting key. The CCA AES key must be an EXPORTER with WR-ECC enabled in key usage field 3, high-order byte (bit 4). See also AESKW key format for external keys.

The TR-31 AES key must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E
QSA-AES1 Export a quantum-safe key (PQC key), such as an ML-KEM or ML-DSA key, into a token wrapped by a CCA or TR-31 AES key-encrypting key. The CCA AES key must be an EXPORTER with WR-QSA enabled in key usage field 3, high-order byte (bit 5). See also AESKW key format for external keys.

The TR-31 AES key must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E
EMV DDA encrypted key part data format (One, optional). Only valid with output format keyword EMVDDA or EMVDDAE.
EMV1 Original EMV DDA output format. This is the default.
EMVLENBT Modified EMV DDA output format, which includes a length byte that becomes part of the encrypted key part section. The length byte, which replaces a post-padding byte of X’00’ that EMV1 uses, is prefixed to the clear key part. This length is valued to the number clear key-part bytes and does not include any pad bytes.
Format restriction (One, optional). Only valid with token type keyword EXTDWAKW or INTDWAKW.
FR-NONE Specifies to not restrict the private key to be used by a particular digital-signature hash formatting method. The key is usable for any method. This is the default.
FR-I9796 Specifies to render the private key usable only with the digital-signature hash formatting method ISO-9796.
FR-X9.31 Specifies to render the private key usable only with the digital-signature hash formatting method X9.31.
FR-ZPAD Specifies to render the private key usable only with the digital-signature hash formatting method ZERO-PAD.
FR-PK10 Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-1.0.
FR-PK11 Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-1.1.
FR-PSS Specifies to render the private key usable only with the digital-signature hash formatting method PKCS-PSS.
PKA key usage control Only valid with INTUSCHG. The keywords specified reflect the only usage attributes that will be enabled in the output key token. All other usage attributes will be disabled.
U-DIGSIG Digital Signature usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U-DIGSIG flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or SIG-ONLY flag is enabled in the input key token.
U-NONRPD Non-Repudiation usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U-NONRPD flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or SIG-ONLY flag is enabled in the input key token.
U-KCRTSN keyCertSign usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U- KCRTSN flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or SIG -ONLY flag is enabled in the input key token.

U-CRLSN Certificate Revocation List Sign usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U-CRLSN flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or SIG -ONLY flag is enabled in the input key token.
U-KEYENC Key Encipherment usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U- KEYENC flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or KM -ONLY flag is enabled in the input key token.
U-DATENC Data Encipherment usage is allowed. >

When input key type is RSAAESC2 or RSAAESM2, requires that the U- DATENC flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or KM-ONLY flag is enabled in the input key token.
U-KEYAGR Key agreement usage is allowed.

When input key type is RSAAESC2 or RSAAESM2, requires that the U- KEYAGR flag is enabled in the input key token.

When input key type is not RSAAESC2 or RSAAESM2, requires that the KEY-MGMT or KM -ONLY flag is enabled in the input key token.
Key agreement control (One, Optional). Only valid with U-KEYAGR.
U-ENCONL

Only encipher operations are allowed during key agreement key establishment protocols.

When input key type is RSAAESC2 or RSAAESM2, the U-DECONL must not be enabled in the input key token.
U-DECONL

Only decipher operations are allowed during key agreement key establishment protocols.

When input key type is RSAAESC2 or RSAAESM2, the U-ENCONL must not be enabled in the input key token.

source_key_length
The length of the source_key parameter. The maximum size is 8000 bytes.
source_key

The key identifier of the RSA, ECC, or PQC private key to be processed. For translation, the key is an external key token wrapped with a CCA or TR-31 DES key-encrypting key. For OPK conversion, the token may be internal or external. External tokens are wrapped with a CCA or TR-31 DES key-encrypting key. When an internal token is specified, the transport keys are not used. For export to AESKW external format, the token is an internal token.

When keyword INTUSCHG is specified, this must be an internal RSA private key token.

When keyword COMP-CHK or INTUSCHG is specified, this must be an RSA private key token with private key section X'08', X'30', or X'31'.

When keyword CKM-RAKW is specified, this must be an external RSA private key token with private key section X'08', X'30', or X'31' or an external ECC private key token with private key section X'20'. Compliance tagged key tokens are not supported.

When translating with the CKM-RAKW keyword specified for an RSA key, the private-key section must have translation control of XLATE-OK (offset 50 in the private-key section).

When translating with the CKM-RAKW keyword specified for an ECC key, the private-key section must have translation control of XLATE-OK (offset 08 in the private-key section).

source_transport_key_length
Length in bytes of the source_transport_key parameter. When the source_transport_key parameter contains a label, the length must be 64. When the processing rule is INTDWAKW, INTUSCHG, COMP-TAG, ECC-AES1, or QSA-AES1, the value must be zero. Otherwise, the value must be between the actual length of the token and 9992.
source_transport_key

The key identifier of the key to unwrap the source key. The key identifier is an operational CCA or TR-31 token or the key label of such a token in key storage. This key is used to unwrap the input PKA key token specified with parameter source_key.

For ECC and RSA (RSA-AESC, RSAAESC2, RSA-AESM, or RSAAESM2) key tokens, this is a CCA or TR-31 AES token. If using a CCA token, it must be an AES EXPORTER or IMPORTER key with the TRANSLAT key usage attribute. If using a TR-31 token, it must also be an AES EXPORTER or IMPORTER, meaning it must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E

For other RSA key tokens, this is a CCA or TR-31 DES token. If using a CCA token, it must be a DES EXPORTER or IMPORTER key with the XLATE control vector attribute. See Required commands for details on the type of transport key that can be used. If using a TR-31 token, it must also be a DES EXPORTER or IMPORTER, meaning it must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: T
  • TR-31 mode of key use: D or E

When the source_transport_key_length is zero, this parameter is ignored.

target_transport_key_length
Length in bytes of the target_transport_key parameter. If the target_transport_key parameter contains a label, the length must be 64. When the processing rule is INTDWAKW, INTUSCHG, COMPCHK, or COMP-TAG, the value must be zero. Otherwise, the value must be between the actual length of the token and 9992.
target_transport_key
This field contains an internal token either in the form of a CCA token or a TR-31 token (both AES or DES), or the label of a CCA or TR-31 AES or DES key-encrypting key. This key is used to wrap the output RSA key returned with the target_key_token parameter. See Required commands for details on the type of transport key that can be used.

When the processing rule is EMVCRT, EMVDDA, EMVDDAE, SCCOMCRT, SCCOMME, or SCVISA, the key is a DES IMPORTER or EXPORTER.

For a TR-31 DES key token, this means that it must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: T
  • TR-31 mode of key use: D or E

For a CCA DES token it must have the XLATE control vector attribute.

When the processing rule is EXTDWAKW, the key is an AES IMPORTER or EXPORTER.

For a TR-31 AES key token, this means that it must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E

For a CCA AES token it must have the TRANSLAT key usage attribute.

When the processing rule is CKM-RKAW, this parameter must be a CCA key token containing an RSA public key with a modulus bit length of 2048, 3072, or 4096. The key will wrap the ephemeral AES key that wraps the private key.

For export to AESKW external format, the key is an AES EXPORTER.

For a TR-31 AES key token, this means that it must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A
  • TR-31 mode of key use: D or E

For a CCA AES token it must have the WR-QSA or WR-ECC bit enabled in key-usage field 3, high-order byte.

When the target_transport_key_length is zero, this parameter is ignored.

target_key_token_length
Length in bytes of the target_key_token parameter. On output, the value in this variable is updated to contain the actual length of the target_key_token produced by the verb. The maximum length is 8000 bytes.
target_key_token
This field contains the RSA key in the smart card format specified in the rule_array parameter, and is protected by the key-encrypting key specified in the target_transport_key parameter. This is not a CCA key token, and cannot be stored in the key storage.

When converting to an AES OPK format, the token is a CCA key token wrapped by a CCA or TR-31 AES key-encrypting key (EXTDWAKW) or an internal token (INTDWAKW).

When the INTUSCHG keyword is specified, the output is an internal RSA private key token with private key section X'30' and associated data version X'04' (RSAAESM2) or an internal RSA private key token with private key section X'31' and associated data version X'05' (RSAAESC2). Internal tokens may be stored in the PKDS.

When translating to a non-CCA smart card format, the key token is wrapped with the CCA or TR-31 key-encrypting key specified in the target_transport_key parameter. The key token is not a CCA key token and cannot be stored in the PKDS.

When the processing rule is CKM_RAKW, the output is a structure containing the AES ephemeral key wrapped by the RSA public key specified in the target_transport_key parameter and the wrapped private key.