Parameters

Edit online

The parameters for CSNDT34R.

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

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

rule_array

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 Receive
Keyword Meaning
Requested action (one, required).
2PASSRCV TR34 Key Transport (2-pass) KTKDH RECEIVE service.
1PASSRCV TR34 Key Transport (1-pass) KTKDH RECEIVE service.
Token type (one, optional).
CCA-TOK Specifies to create a CCA key token in the output_key_identifier. This is the default.
TR31-TOK Specifies to create a TR-31 key block in the output_key_identifier.
Note: If the input token uses wrapping method A or C, it cannot be returned as an internal TR-31 token. Only wrapping methods B and D can be internal TR-31 tokens.
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.
Freshness Indicator Usage (one, required with 1PASSRCV). Only valid with keyword 1PASSRCV.
TIME-CHK Specifies to check the timestamp in the input_freshness_indicator parameter against the timestamp in the KTKDH received in the input_token parameter. The verification step only checks that the timestamp in the KTKDH is newer than timestamp in the input_freshness_indicator parameter. The timestamp from the KTKDH is still returned in the output_freshness_indicator parameter.
TIMENONE Specifies to not check the timestamp in the input_freshness_indicator parameter against the timestamp in the KTKDH received in the input_token parameter. The timestamp from the KTKDH will be returned in the output_freshness_indicator parameter so that the application can verify the value.
Key Wrapping Method (one optional). Applicable only to DES algorithm imported keys. Not allowed with the TR31-TOK keyword.
USECONFG Specifies that the configuration setting for the default wrapping method is to be used to wrap the key. This is the default.
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 (one optional). Applicable only to DES algorithm imported keys. Not allowed with the TR31-TOK keyword.
ENH-ONLY Specify this keyword to indicate that the key once wrapped with the enhanced method cannot be wrapped with the CCA legacy method. This restricts translation to the CCA legacy method. If the keyword is not specified, translation to the CCA legacy method will be allowed. This turns on bit 56 in the control vector.
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.
Table 2. Input translation table for DES key usage
TR-31 mode of key use Key block version ID TR-31 mode of key use Rule-array keywords CCA key type and key-usage attributes of output key Offset (hex) Access control name
K0, K1 "A", "B", "C", "D" "E" N/A EXPORTER X'0248' TR-34 Key Receive – Permit DES EXPORTER
K0, K1 "A", "B", "C", "D" "D" N/A IMPORTER X'0249' TR-34 Key Receive – Permit DES IMPORTER
Table 3. Input translation table for AES key usage
TR-31 mode of key use Key block version ID TR-31 mode of key use Rule-array keywords CCA key type and key-usage attributes of output key Offset (hex) Access control name
K0 "D" "E" N/A EXPORTER 024A TR-34 Key Receive – Permit AES EXPORTER
"D" N/A IMPORTER X'024B' TR-34 Key Receive – Permit AES IMPORTER
K1 "D" "E" N/A EXPORTER + EXPTT31D X'024C' TR-34 Key Receive – Permit AES EXPORTER with EXPTT31D
"D" N/A IMPORTER + IMPTT31D X'024D' TR-34 Key Receive – Permit AES IMPORTER with IMPTT31D
input_token_length
The length of the input_token parameter in bytes. The maximum length is 9000 bytes.
input_token
The DER encoded TR-34 token object. The requested action keyword defines the object.
2PASSRCV
This parameter must contain the 2 pass key transport token received from the KDH (KTKDH).
1PASSRCV
This parameter must contain the 1 pass key transport token received from the KDH (KTKDH)
cred_kdh_length
The length of the cred_kdh parameter in bytes. The maximum length is 3500 bytes.
cred_kdh
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.
input_freshness_indicator_length
The length of the input_freshness_indicator parameter in bytes. The maximum length is 200 bytes.
The value is determined by the requested action keyword:
2PASSRCV
This parameter contains the length of the random number token received from the KRD (RTKRD).
1PASSRCV
This parameter contains the length of the ASCII timestamp for use in the key transport token. The value must be 13 or 15. When TIMENONE is passed, the value must be 0.
input_freshness_indicator
The freshness indicator. When the value of input_freshness_indicator_length is 0, this parameter is ignored.
The meaning is determined by the requested action keyword:
2PASSRCV
This parameter contains the DER encoded random number token received from the KRD (RT-KRD).
1PASSRCV
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, but will make no attempt to validate the timestamp against the clock inside the coprocessor.

private_key_identifier_length
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
The identifier of the private key used to decrypt the key block in the input 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.

output_key_identifier_length
The length of the output_key_identifier parameter, in bytes. On input, it specifies the length of the buffer for output_key_identifier and must be 64 bytes for DES keys, up to 725 bytes for AES keys, and up to 9992 bytes for TR-31 tokens. On output, it will contain the length of the token returned.
output_key_identifier
The received key token from the TR-34 key block. The output token will be a CCA or TR-31 internal key token containing the key received in the TR-34 key block.
output_freshness_indicator_length
The length of the output_freshness_indicator parameter, in bytes. On input, it specifies the length of the buffer for output_freshness_indicator and must be at least 15 bytes long. On output, it will contain the length of the indicator returned. When the requested action keyword is 2PASSRCV, the value must be 0.
output_freshness_indicator
The output freshness indicator. When the value of output_freshness_indicator_length is 0, this parameter is ignored.
When the requested action keyword is 1PASSRCV, this parameter contains the ASCII timestamp received in the key transport token received from the KDH. Two encodings are used for this parameter: UTCTime encoded as YYMMDDHHMMSSZ (13 bytes) and GeneralizedTime encoded as YYYYMMDDHHMMSSZ (15 bytes). Date ranges allowed for each format are:
UTCTime
Dates between 1 January 1970 and 31 December 2049 (inclusive).
GeneralizedTime
Dates between 1 January 2050 and 31 December 2105 (inclusive).
There will be an ASCII 'Z' character at the end. ICSF will verify that the timestamp returned is a valid timestamp from the key transport token received from the KDH (KT-KDH), but makes no attempt to validate the timestamp against the clock inside the coprocessor.
reserved_data_length
This parameter is reserved. The value must be zero.
reserved_data
This parameter is ignored.