Parameters
The parameters for CSNBKTP2.
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.
- key_token_length
A pointer to an integer variable containing the number of bytes of data in the key_token variable.Direction: Input Type: Integer - key_token
A pointer to a string variable containing an external or internal variable-length symmetric key-token to be disassembled. This parameter must not point to a key label.Direction: Input Type: String - key_type
A pointer to a string variable containing a keyword for the key type of the input key. The keyword is 8 bytes in length and is left-aligned and padded on the right with space characters. Valid key_type keywords are shown here:Direction: Output Type: String CIPHER DESUESCV DKYGENKY EXPORTER IMPORTER MAC PINCALC PINPROT PINPRW SECMSGKey types are described in Types of keys.
- rule_array_count
A pointer to an integer variable containing the number of 8-byte elements in the rule_array variable. The minimum returned value is 3, and the maximum returned value is approximately 50. To determine the exact count required, and also the required lengths of the other string variables, specify a value of zero. This causes the verb to return all count and length values without updating any string variables.Direction: Input/Output Type: Integer On output, the variable is updated with the actual count of the rule-array keywords. An error is returned if a key token cannot be parsed or any of the output buffers are too small.
- rule_array
A pointer to a string variable containing an array of keywords. The keywords are 8 bytes in length, and are left-aligned and padded on the right with space characters. The returned rule array keywords express the contents of the token.Direction: Output Type: String array While Key Token Build2 (CSNBKTB2) assembles an internal variable-length symmetric key-token in application storage from information that you supply via the key words in the verb's rule_array parameter, Key Token Parse2 disassembles an input key-token into separate pieces of information which are stored in this verb's rule_array as output. Some of the keywords of Key Token Build2 and Key Token Parse2 therefore have the same meaning.
Table 1. Keywords for Key Token Parse2 Keywords for Key Token Parse2
Keyword Description Header section Token identifier (one required) EXTERNAL Specifies to disassemble an external variable-length symmetric key-token. INTERNAL Specifies to disassemble an internal variable-length symmetric key-token. Wrapping information section Key status (one returned). Refer to the key_material_state variable for additional details. NO-KEY Key token does not contain a key. The payload variable is empty. KEY Key token contains a partial or complete key. The payload variable contains the clear or encrypted key. Key verification pattern (KVP) type Note: Not a keyword. Value returned in key_verification_pattern_type variable.KVP Note: Not a keyword. Value returned in key_verification_pattern variable.Encrypted section key-wrapping method Note: Not a keyword. Value returned in key_wrapping_method variable.Hash algorithm used for wrapping Note: Not a keyword. Value returned in key_hash_algorithm variable.Associated data section Type of algorithm for which the key can be used (one returned) AES Specifies the AES algorithm. DES Specifies the DES algorithm. HMAC Specifies the HMAC algorithm. Key type Note: Not a keyword. Value returned in key_type variable.Key-usage field keywords depend on key type: - Key type
- Reference
- CIPHER
- Refer to Table 1.
- DESUESCV
- No key-usage field keywords.
- DKYGENKY
- Refer to Table 2.
- EXPORTER
- Refer to Table 4.
- IMPORTER
- Refer to Table 5.
- MAC
- For AES token algorithm, refer to Table 6. For HMAC token algorithm, refer to Table 7.
- PINCALC
- Refer to Table 8.
- PINPROT
- Refer to Table 10.
- PINPRW
- Refer to Table 11.
- SECMSG
- Refer to Table 13.
Key-management field 1, high order byte Symmetric-key export control (one returned, all key types) NOEX-SYM Prohibit export using symmetric key. XPRT-SYM Allow export using symmetric key. Unauthenticated asymmetric-key export control (one returned, all key types) NOEXUASY Prohibit export using an unauthenticated asymmetric key. XPRTUASY Allow export using unauthenticated asymmetric key. Authenticated asymmetric-key export control (one returned, all key types) NOEXAASY Prohibit export using authenticated asymmetric key. XPRTAASY Allow export using authenticated asymmetric key. Key-management field 1, low-order byte DES-key export control (one returned, AES algorithm only) NOEX-DES Prohibit export using DES key XPRT-DES Allow export using DES key. AES-key export control (one returned, AES algorithm only) NOEX-AES Prohibit export using AES key. XPRT-AES Allow export using AES key. RSA-key export control (one returned, AES algorithm only) NOEX-RSA Prohibit export using RSA key XPRT-RSA Allow export using RSA key. NOEX-RAW Prohibit export using raw key XPRT-RAW Allow export using raw key. Key-management field 2, high order byte Key completeness (one returned, all key types) MIN3PART Key if present is incomplete. Key requires at least 2 more parts. MIN2PART Key if present is incomplete. Key requires at least 1 more part. MIN1PART Key if present is incomplete. Key can be completed or have more parts added. KEYCMPLT Key if present is complete. No more parts can be added. Key-management field 2, low-order byte Security history (one returned, all key types) UNTRUSTD Key was encrypted with an untrusted KEK. WOTUATTR Key was in a format without type/usage attributes. WWEAKKEY Key was encrypted with key weaker than itself. NOTCCAFM Key was in a non-CCA format. WECBMODE Key was encrypted in ECB mode. Key-management field 3, high order byte Pedigree original rules (one returned, all key types) POUNKNWN Unknown. POOTHER Other. Method other than those defined here, probably used in UDX. PORANDOM Randomly generated. POKEYAGR Established by key agreement such as Diffie-Hellman. POCLRKC Created from cleartext key components. POCLRKV Entered as a cleartext key value. PODERVD Derived from another key. POKPSEC Cleartext keys or key parts that were entered at TKE and secured from there to the target card. Key-management field 3, low-order byte Pedigree current rule (one returned, all key types) PCUNKNWN Unknown. PCOTHER Other. Method other than those defined here, probably used in UDX. PCRANDOM Randomly generated. PCKEYAGR Established by key agreement such as Diffie-Hellman. PCCLCOMP Created from cleartext key components. PCCLVAL Entered as a cleartext key value. PCDERVD Derived from another key. PCMVARWP Imported from CCA version X'05' variable-length symmetric key-token with pedigree field. PCMVARNP Imported from CCA version X'05' variable-length symmetric key-token with no pedigree field. PCMWCV Imported from CCA key-token that contained a nonzero control vector. PCMNOCV Imported from CCA key-token that had no control vector or contained a zero control vector. PCMT31WC Imported from a TR-31 key block that contained a control vector (ATTR-CV option). PCMT31NC Imported from a TR-31 key block that did not contain a control vector. PCMPK1-2 Imported using PKCS 1.2 RSA encryption. PCMOAEP Imported using PKCS OAEP encryption. PCMPKA92 Imported using PKA92 RSA encryption. PCMZ-PAD Imported using RSA ZERO-PAD encryption. PCCNVTWC Converted from a CCA key-token that contained a nonzero control vector. PCCNVTNC Converted from a CCA key-token that had no control vector or contained a zero control vector. PCKPSEC Cleartext keys or key parts that were entered at TKE and secured from there to the target card. PCXVARWP Exported from CCA version X'05' variable-length symmetric key-token with pedigree field. PCXVARNP Exported from CCA version X'05' variable-length symmetric key-token with no pedigree field. PCXOAEP Exported using PKCS OAEP encryption. Optional clear key or encrypted AESKW payload section Payload Note: Not a keyword. Value returned in the payload variable.- key_material_state
A pointer to an integer variable containing the indicator for the current state of the key material. The valid values are:Direction: Output Type: Integer - 0
- No key present (internal or external)
- 1
- Key is clear (internal), payload bit length is clear-key bit length
- 2
- Key is encrypted under a KEK (external)
- 3
- Key is encrypted under the master key (internal)
- payload_bit_length
A pointer to an integer variable containing the number of bits in the token payload. If no key is present, the returned value is 0.Direction: Input/Output Type: Integer If a clear key is present, the returned value is in the following range:- AES
- 128, 192, or 256
- HMAC
- 80 - 2048
- payload
A pointer to a string variable containing the key material payload. The payload parameter must be addressable up to the nearest byte boundary above the payload_bit_length if the payload_bit_length is not a multiple of 8. This field will contain the clear key or the encrypted key material.Direction: Output Type: String - key_verification_pattern_type
A pointer to an integer variable containing the indicator for the type of key verification pattern used. The valid values are:Direction: Output Type: Integer - 0
- No KVP
- 1
- AESMK (8 left-most bytes of SHA-256 hash(X'01' || clear AES MK))
- 2
- KEK VP (8 left-most bytes of SHA-256 hash(X'01' || clear KEK))
- key_verification_pattern_length
A pointer to an integer variable containing the number of bytes of data in the key_verification_pattern parameter. The valid values are 0, 8, or 16. The value 16 is reserved.Direction: Input/Output Type: Integer - key_verification_pattern
A pointer to a string variable containing the key verification pattern (KVP) of the key-encrypting key used to wrap this key. If the key_verification_pattern_type value indicates that a key verification pattern is present, the pattern will be copied from the token, otherwise this variable is empty.Direction: Output Type: String - key_wrapping_method
A pointer to an integer variable containing the indicator for the encrypted section key-wrapping method used to protect the key payload. The valid values are:Direction: Output Type: Integer - 0
- NONE (for clear keys or no key)
- 2
- AESKW (for external or internal key wrapped with an AES KEK)
- 3
- PKOAEP2 (for external tokens wrapped with an RSA public key)
- key_hash_algorithm
A pointer to an integer variable containing the indicator for the hash algorithm used for wrapping in the key token. The valid values are as follows:Direction: Output Type: Integer Hash algorithms for the Key Token Parse2 verb
Value Hash algorithm Key-wrapping method X'00' (clear key) X'02' (AESKW) X'03' (PKOAEP2) 0 No hash X 1 SHA-1 X 2 SHA-256 X X 4 SHA-384 X 8 SHA-512 X - key_name_length
A pointer to an integer variable containing the number of bytes of data in the key_name variable. The returned value can be 0 or 64.Direction: Input/Output Type: Integer - key_name
A pointer to a string variable containing the optional key label to be stored in the associated data structure of the key token. If there is no key name, then this variable is empty.Direction: Output Type: String - TLV_data_length
A pointer to an integer variable containing the number of bytes of data in the TLV_data variable. The returned value is currently always zero.Direction: Input/Output Type: Integer - TLV_data
A pointer to a string variable containing the optional tag-length-value (TLV) section. This field is currently unused.Direction: Output Type: String - user_associated_data_length
The user_associated_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the user_associated_data variable. The returned value is 0 - 255.Direction: Input/Output Type: Integer - user_associated_data
A pointer to a string variable containing the user-associated data to be stored in the key token. This user-definable data is cryptographically bound to the key if it is encrypted. If there is no user-defined associated data, this variable is empty.Direction: Output Type: String - verb_data_length
A pointer to an integer variable containing the number of bytes of data in the verb_data variable. The returned value is zero if the returned key_type variable is not DKYGENKY. Otherwise the value can be greater than zero and is a multiple of 8.Direction: Input/Output Type: Integer - verb_data
A pointer to a string variable containing any related key-usage field keywords of an AES DKYGENKY key for the for the type of key to be diversified:Direction: Output Type: String Meaning of verb_data keywords for DKYGENKY type of key to diversify
DKYGENKY type of key to diversify Meaning of verb_data keywords D-CIPHER Key usage fields for AES CIPHER key. D-EXP Key usage fields for AES EXPORTER key. D-IMP Key usage fields for AES IMPORTER key. D-MAC Key usage fields for AES MAC key. D-PPROT Key-usage fields for AES PINPROT key. D-PCALC Key-usage fields for AES PINCALC key. D-PPRW Key-usage fields for AES PINPRW key. D-SECMSG Key-usage fields for AES SECMSG key.