Parameters

The parameters for CSNBT31P.

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:	Input/Output
Type:	Integer

A pointer to an integer variable containing the number of 8-byte elements in the rule_array parameter. This value must be a minimum of 1 and a maximum of 20. On input, specify the maximum number of usable rule array elements that are allocated. On output, the verb sets the value to the number of keywords returned to the application.

rule_array


Direction:	Output
Type:	String array

A pointer to a string variable containing an array of keywords. On output, each element in the array will contain a valid keyword that is left-aligned and padded on the right as needed with space characters. The returned rule array keywords are described in Table 1:

Table 1. Keywords for the TR31 Key Token Parse verb
Keywords for the TR31 Key Token Parse verb
Keyword	Meaning
EXTERNAL	The key block header Key Context field at offset 14 contains "0x32", meaning *Exchange* only, treated as external.
INTERNAL	The key block header Key Context field at offset 14 contains “0x31”, meaning *Storage* only, treated as internal.
STOREXCH	The key block header Key Context field at offset 14 contains “0x30”, meaning *Storage* or *Exchange*, treated as external.

tr31_key_length


Direction:	Input
Type:	Integer

A pointer to an integer variable containing the number of bytes of data in the tr31_key variable. Specify a length that is greater than or equal to the size of the key block. The verb determines the actual length of the key by parsing its contents.

tr31_key


Direction:	Input
Type:	String

A pointer to a string variable containing the TR-31 key block to be disassembled.

key_block_version


Direction:	Output
Type:	String

A pointer to a string variable. The verb copies the one byte found in the key block version ID field of the input key block to this variable.

Note that if the verb finds a proprietary key block version ID, the verb treats it as an invalid value, because the verb is not capable of disassembling a key block that has a proprietary ID. This variable is not updated if a processing error occurs.

key_block_length


Direction:	Output
Type:	Integer

A pointer to an integer variable. The verb parses the 2-byte numeric ASCII key block length field from the input key block, converts the string value into an integer, and returns the integer in this variable. This value must be less than or equal to the tr31_key_length input variable.

key_usage


Direction:	Output
Type:	String

A pointer to a string variable. The verb copies the two bytes found in the key usage field of the input key block to this variable.

algorithm


Direction:	Input
Type:	String

A pointer to a one-byte string identifying the cryptographic algorithm the wrapped key is to be used with. The value is read from the TR-31 key block header. The verb does not treat a proprietary algorithm value as an error.

mode


Direction:	Output
Type:	String

A pointer to a one-byte string variable containing the TR-31 mode of use for the key contained in the block. The value is obtained from the TR-31 header. The mode of use describes what operations the key can perform, within the limitations specified with the key usage value. For example, a key with usage for data encryption can have a mode to indicate that it can be used only for encryption, decryption, or both.

This pointer must be non-NULL and point to application storage with at least the size given by the byte count noted. The storage is updated with the noted value on a successful return from this verb, and unchanged otherwise.

key_version_number


Direction:	Output
Type:	String

A pointer to a 2-byte string variable obtained from the TR-31 header, which can be used for one of three purposes, or can be unused.

If both bytes are X'30' ("0"), then key versioning is unused for this key. In this case, the second byte is not examined and can contain any value.
If the first byte is X'63' ("c"), then the block contains a component of a key which must be combined with other components in order to form the complete key. TR-31 does not define the method through which the components are combined. TR-31 specifies that local rules are used for that purpose.
In this case, the second byte is not examined and can contain any value.
If the first byte is anything other than the two values above, then the 2-byte key version value is an identifier of the version of the key that is carried in the block. This key version value can be used by an application, for example, to ensure that an old version of a key is not reentered into the system.

exportability


Direction:	Output
Type:	String

A pointer to a one-byte string variable containing the key exportability value from the TR-31 header. This value indicates whether the key can be exported from this system, and if so specifies conditions under which export is permitted. The following three values are possible:

If the value is X'4E' ("N"), then the key is not exportable.
If the value is X'53' ("S"), then the key is exportable under any key-encrypting key.
If the value is X'45' ("E"), then the key is exportable only under a trusted key-encrypting key. TR 31 defines such a trusted key as either one that is encrypted under the HSM master key or one that is itself contained in a TR-31 key block. CCA does not support KEKs that are wrapped in TR-31 key blocks.

num_opt_block


Direction:	Output
Type:	Integer

A pointer to an integer value containing the number of optional blocks that are part of the TR-31 key block. Information about each optional block can be obtained using the TR31 Optional Data Read verb. In this verb, use the number of optional blocks acquired with this verb to obtain a list of the IDs and lengths for each optional block. Then, use those lists to read the data from each desired block.