Parameters

The parameter definitions for CSNDT34D.

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	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. The value must be in the range 5 - 11.

rule_array


Direction	Type
Input	Character

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 1. Keywords for TR-34 Key Distribution
Keywords for TR-34 Key Distribution. This table contains two columns: Keyword and Meaning, and it contains rows for Requested action (one, required), Public key infrastructure usage (one, optional), Source key algorithm (one, required), and Key block version (one required).
Keyword	Meaning
*Requested action (one, required).*
2PASSCRE	TR34 Key Transport (2-pass) KTKDH CREATE service.
1PASSCRE	TR34 Key Transport (1-pass) KTKDH CREATE service.
*Public key infrastructure usage (one, optional).*
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 required for compliance-tagged key token export with TR-34 services. 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 algorithm (one, required).*
SKEY-DES	Specifies that the source_key_identifer is a DES key. If the source_key_identifier is external then the unwrap_kek_identifier is also a DES key.
SKEY-AES	Specifies that the source_key_identifer is an AES key. If the source_key_identifier is external then the unwrap_kek_identifier is also an AES key.
*Key block version (one, required).* Specifies which version of the TR-31 key block to use. However, this value has no impact to the wrapping of the TR-34 key block or format of the key block. Choose this value for compatibility with the target KRD.
VARXOR-A	Specifies to use TR-31 Key Block Version ID of "A" (X'41'). This is typically a DES version.
VARDRV-B	Specifies to use TR-31 Key Block Version ID of "B" (X'42'). This is typically a DES version.
VARXOR-C	Specifies to use TR-31 Key Block Version ID of "C" (X'43'). This is typically a DES version.
VARDRV-D	Specifies to use TR-31 Key Block Version ID of "D" (X'44'). This is typically for AES or DES.
*EncryptedContent format (one, optional).* TR-34-2012 in examples B.8 and B.9 places the EncryptedContent according to X9.73, after the ContentEncryptionAlgorithmIdentifier. TR-34-2019 has changed this, introducing a small incompatibility, placing the EncryptedContent as the last field inside of the ContentEncryptionAlgorithmIdentifier. Check with your ATM vendor to ensure that you are using the correct option.
T34-2012	Builds the EncryptedContentInfo section of the EnvelopedData of the output_token according to the sample description in X9 TR-34-2012 sections B.8 and B.9. The EncryptedContent appears after the ContentEncryptionAlgorithmIdentifier. This keyword impact applies to either the 1PASSCRE or 2PASSCRE output_token as the compatibility issue applies to both. This is the default.
T34-2019	Builds the EncryptedContentInfo section of the EnvelopedData of the output_token according to the sample description in X9 TR-34-2019 sections B.8 and B.9. The EncryptedContent appears inside the ContentEncryptionAlgorithmIdentifier. This keyword impact applies to either the 1PASSCRE or 2PASSCRE output_token as the compatibility issue applies to both.
*SignedAttributes order* (one, optional). TR-34-2012 and TR-34-2019 define a SignedAttributes object that is part of the Signer Info, in the output_token parameter. The SignedAttributes object is a Set-of as defined in ITU T-REC-X.690.201508. The components of a Set-of are meant to be ordered by increasing size. Some ATM vendors implemented the Set-of object with a static order of components matching the order shown in the TR-34-2012 (repeated in TR-34-2019), in section B.9.1. Check with your ATM vendor to ensure you are using the correct option. Only valid with 2PASSCRE.
SASORTSZ	Use the flexible ordering for Set-of components as defined in ITU T-REC-X.690.201508, which requires order by increasing size. This is the default.
SASORTEX	Use the static ordering shown in the parsed example of TR-34-2012 in section B.9.1.
*CRL expiration date checking* (one, optional).
CRLEXPCK	CRL Expiration Check - Check the expiration date of the certificate revocation list (CRL) in the crl parameter and return an error if the CRL is expired. This is the default.
CRLEXPAL	CRL Expiration Allow - Check the expiration date of the certificate revocation list (CRL) in the crl parameter and return an informational message if the CRL is expired.
*KRD certificate date checking* (one, optional).
RCTEXPCK	KRD Certificate Expiration Check - Check the expiration date of the key receiving device (KRD) certificate and return an error if the certificate is expired. This is the default.
RCTEXPAL	KRD Certificate Expiration Allow - Check the expiration date of the key receiving device (KRD) certificate and return an informational message if the certificate is expired.

Table 2. TR-31 key usage value for output key block
TR-31 key usage value for output key block (one required). The TR-34 key transport key block contains a TR-31 key header contains the key usage.
Keyword	TR-31 key usage	CCA key types	Meaning
TR-31 key usage value for output key block (one required). The TR-34 key transport key block contains a TR-31 key header contains the key usage.
KEK	"K0"	IMPORTER or EXPORTER DES or AES.	Specifies to export a key-encrypting key (KEK) to an external TR-31 key block. You must select one TR-31 mode of key use keyword from Table 1 with this usage keyword. The table shows all the supported translations for key usage keyword KEK. It also shows the access control commands that must be enabled in the active role to use the combination of inputs shown.
KEK-WRAP	"K1"	IMPORTER or EXPORTER DES or AES. AES must have TR-31 wrap permission.	AES must have TR-31 wrap permission. Specifies to export a TR-31 key block protection key (KEK-WRAP) to an external TR-31 key block. You must select one TR-31 mode of key use keyword from Table 1 with this usage keyword. The table shows all the supported translations for key usage keyword KEK-WRAP. It also shows the access control commands that must be enabled in the active role to use the combination of inputs shown.

Table 3. TR-31 mode of key use
TR-31 mode of key use (one required). Only those TR-31 modes shown are supported. Modes requested must match or be included in the capabilities of the key being exported. For example, DEC-ONLY and GENVER cannot be used if the exported key has ENC-ONLY capability.
Keyword	TR-31 key usage	CCA key types	Meaning
*TR-31 mode of key use (one required).* Only those TR-31 modes shown are supported. Modes requested must match or be included in the capabilities of the key being exported. For example, DEC-ONLY and GENVER cannot be used if the exported key has ENC-ONLY capability.
DEC-ONLY	"D"	KEK, KEK-WRAP	Specifies to decrypt and unwrap only.
ENC-ONLY	"E"	KEK, KEK-WRAP	Specifies to encrypt and wrap only.

Table 4. TR-31 exportability
TR-31 exportability (one, optional). Use to set exportability field in TR-31 key block. Defines whether the key may be transferred outside the cryptographic domain in which the key is found.
Keyword	TR-31 mode	Meaning
TR-31 exportability (one, optional). Use to set exportability field in TR-31 key block. Defines whether the key may be transferred outside the cryptographic domain in which the key is found.
EXP-ANY	"E"	Specifies that the key in the TR-31 key block is exportable under a key-encrypting key in a form that meets the requirements of X9.24 Parts 1 or 2. This is the default.
EXP-TRST	"S"	Specifies that the key in the TR-31 key block is sensitive, exportable under a key-encrypting key in a form not necessarily meeting the requirements of X9.24 Parts 1 or 2. Note: A TR-31 key block with a key block version ID of "B" or "C" and an exportability field value of "E" cannot be wrapped by a key-encrypting key that is wrapped in ECB mode (legacy wrap mode). This is because ECB mode does not comply with ANS X9.24 Part 1.
EXP-NONE	"N"	Specifies that the key in the TR-31 key block is non-exportable.

The following tables map the CCA key types for the DES and AES keys to the corresponding allowed key usage keywords and mode of use keywords, as well as the access control points that are required.

Table 5. Export translation table for DES keys in TR-34 key blocks
Export translation table for DES keys in TR-34 key blocks.
CCA key type (and required attributes)	Key usage keyword	Key block protection method keyword	TR-31 mode of key use keyword	Offset (hex)	Access control name
Security note: The TR-31 modes requested must match or be included in the capabilities of the key being exported. For example, DEC-ONLY and GENVER cannot be used if the exported key has ENC-ONLY capability.
DES EXPORTER	KEK ("K0")	VARXOR-A, VARDRV-B, VARXOR-C, VARDRV-D	ENC-ONLY ("E")	0242	TR-34 Key Distribution - Permit DES EXPORTER to K0 or K1
DES EXPORTER	KEK-WRAP ("K1")	VARXOR-A, VARDRV-B, VARXOR-C, VARDRV-D	ENC-ONLY ("E")	0242	TR-34 Key Distribution - Permit DES EXPORTER to K0 or K1
DES IMPORTER	KEK ("K0")	VARXOR-A, VARDRV-B, VARXOR-C, VARDRV-D	DEC-ONLY ("D")	0243	TR-34 Key Distribution - Permit DES IMPORTER to K0 or K1
DES IMPORTER	KEK-WRAP ("K1")	VARXOR-A, VARDRV-B, VARXOR-C, VARDRV-D	DEC-ONLY ("D")	0243	TR-34 Key Distribution - Permit DES IMPORTER to K0 or K1

Table 6. Export translation table for AES keys in TR-34 key blocks
Export translation table for AES keys in TR-34 key blocks.
CCA key type (and required attributes)	Key usage keyword	Key block protection method keyword	TR-31 mode of key use keyword	Offset (hex)	Access control name
Security note: The TR-31 modes requested must match or be included in the capabilities of the key being exported. For example, DEC-ONLY and GENVER cannot be used if the exported key has ENC-ONLY capability.
AES EXPORTER	KEK ("K0")	VARDRV-D	ENC-ONLY ("E")	0244	TR-34 Key Distribution - Permit AES EXPORTER to K0
AES EXPORTER (EXPTT31D)	KEK-WRAP ("K1")	VARDRV-D	ENC-ONLY ("E")	0245	TR-34 Key Distribution - Permit AES EXPORTER to K1
AES IMPORTER	KEK ("K0")	VARDRV-D	DEC-ONLY ("D")	0246	TR-34 Key Distribution - Permit AES IMPORTER to K0
AES IMPORTER (IMPTT31D)	KEK-WRAP ("K1")	VARDRV-D	DEC-ONLY ("D")	0247	TR-34 Key Distribution - Permit AES IMPORTER to K1

source_key_identifier_length


Direction	Type
Input	Integer

Specifies the length in bytes of the source_key_identifier parameter. 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 9992.

source_key_identifier


Direction	Type
Input/Output	String

The identifier of the key to be exported using the TR-34 protocol. The key identifier is a CCA or TR-31 internal or external token or the label of an operational token in key storage. If the source key is an external token, an identifier for the KEK that wraps the source key must be passed in the unwrap_kek_identifier parameter.

The control vector of a DES token or the key usage field of an AES token must not indicate that the key in the token is a partial key. Partial keys are not exportable using TR-34.

If the source key is a CCA token it must be an IMPORTER or EXPORTER type. If the source key is a TR-31 token it must have the following attributes:

TR-31 key usage: K0 or K1
Algorithm: T or A
TR-31 mode of key use: D or E
Exportable: E or S

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

unwrap_kek_identifier_length


Direction	Type
Input	Integer

Specifies the length in bytes of the unwrap_kek_identifier parameter. When the source_key_identifier is an internal key, the value must be 0. When the unwrap_kek_identifier contains a label, the length must be 64. Otherwise, the value must be between the actual length of the token and 9992.

unwrap_kek_identifier


Direction	Type
Input/Output	String

The identifier of the wrapping key of the source key identifier when the source key is an external token. The key identifier is an operational token or the key label of an operational token in key storage.

When the unwrap_kek_identifier_length is zero, this parameter is ignored.

When the wrapping key is a CCA token, it must be a CCA DES key of type EXPORTER or OKEYXLAT, or a CCA AES key with type EXPORTER.

When the wrapping key is a TR-31 token, it must be a TR-31 DES or AES token with the following attributes (K0 TR-31 key usage if source key is a CCA token):

TR-31 key usage: K0 or K1
Algorithm: A or T
TR-31 mode of key use: E

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

freshness_indicator_length


Direction	Type
Input	Integer

The length of the freshness_indicator parameter in bytes. The maximum length is 200 bytes.

The value is determined by the requested action keyword:

2PASSCRE: This parameter contains the length of the random number token received from the KRD (RTKRD).
1PASSCRE: This parameter contains the length of the ASCII timestamp for use in the key transport token. The value must be 13 or 15.

freshness_indicator


Direction	Type
Input	String

The freshness indicator. The meaning is determined by the requested action keyword:

2PASSCRE

This parameter contains the DER encoded random number token received from the KRD (RT-KRD).

1PASSCRE

This parameter contains an ASCII timestamp for use in the key transport token. The timestamp is encoded as a SigningTime object in the token (OID of iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9) signing-time(5)}, defined in IETF RFC 2985). Two input encodings are accepted for this parameter, UTCTime encoded as YYMMDDHHMMSSZ (13 bytes) and GeneralizedTime encoded as YYYYMMDDHHMMSSZ (15 bytes). Date ranges allowed for each format are:

GeneralizedTime: Dates between 1 January 2050 and 31 December 2105 (inclusive).
UTCTime: Dates between 1 January 1950 and 31 December 2049 (inclusive).

There must be an ASCII 'Z' character at the end. CCA verifies that timestamps passed with either encoding are valid timestamps. CCA makes no attempt to validate the timestamp against the clock inside the coprocessor.

crl_length


Direction	Type
Input	Integer

The length of the crl parameter in bytes. The maximum length is 6000 bytes. The value of the crl_length must be balanced against the length of the other parameters. All parameters must fit within the limits of one call to the Crypto Express adapter and must be less than 11,500 bytes.

crl


Direction	Type
Input	String

The certificate revocation list (CRL) from the certificate authority the is in common with the KRD for the requested service. The CRL may be in DER or PEM format.

cred_kdh_length


Direction	Type
Input	Integer

The length of the cred_kdh parameter in bytes. The maximum length is 3500 bytes.

cred_kdh


Direction	Type
Input	String

The X.509 certificate that is the credential of the KDH for the requested service. The certificate may be in DER or PEM format.

Note: This service is acting as the KDH so the cred_kdh is not expected to validate against the internal PKI of the adapter.

cred_krd_length


Direction	Type
Input	Integer

The length of the cred_kdh parameter in bytes. The maximum length is 3500 bytes.

cred_krd


Direction	Type
Input	String

The X.509 certificate that is the credential of the KRD for the requested service (the CredKRD). The certificate may be in DER or PEM format.

The usage attributes in the X.509 certificate must allow keyEncipherment. The public key will be extracted and used to encrypt the ephemeral key wrapping key that protects the TMK that is being transported

Note: This service is acting as the KDH so the cred_krd is normally expected to validate against the internal PKI of the adapter. Use the PKI-NONE keyword to override this validation,

private_key_identifier_length


Direction	Type
Input	Integer

The length of the private_key_identifier parameter. If the private_key_identifier contains a label, the value must be 64. Otherwise, the value must be between the actual length of the token and 3500.

private_key_identifier


Direction	Type
Input	String

The identifier of the private key used to sign the output token. The key identifier is an operational RSA secure token or the label of such a token in key storage.

The key usage of the token must allow digital signature. Retained private keys are not supported in this service.

key_version_number


Direction	Type
Input	String

The two-byte value to be copied into the Key Version Number field of the output TR-31 key block. If no key version number is needed, the value must be EBCDIC ("00"). The value is not allowed to indicate a partial key.

opt_blocks_length


Direction	Type
Input	Integer

The length of the opt_blocks parameter in bytes. If no optional data is to be included in the TR-31 key block, this parameter must be set to zero.

opt_blocks


Direction	Type
Input	String

The optional block data to be included in the output TR-31 key block. The optional block data is prepared using the TR-31 Optional Data Build callable service and must be in ASCII. This parameter is ignored if opt_blocks_length is zero.

output_token_length


Direction	Type
Input/Output	Integer

The length of the output_token parameter in bytes. The maximum length is 9000 bytes. On input, the value is the size of the buffer to receive the output_token. On output, the value is the actual size of the data returned in the output_token parameter.

output_token


Direction	Type
Output	String

The generated DER encoded TR-34 token.

2PASSCRE: This parameter will contain the 2 pass TR-34 key transport token (KTKDH).
1PASSCRE: This parameter will contain the 1 pass TR-34 key transport token (KTKDH).

reserved_data_length


Direction	Type
Input/Output	Integer

This parameter is reserved. The value must be zero.

reserved_data


Direction	Type
Input/Output	String

This parameter is ignored.