TR31 Optional Data Read (CSNBT31R)
Use the TR31 Optional Data Read verb to either obtain information about all of the optional blocks in the header of an external TR-31 key block, or obtain the length and data of the specified optional block.
To disassemble the part of the header that is not optional, use the TR31 Key Token Parse verb. Neither verb performs any cryptographic services, and both disassemble a key block in application storage. The validity of the key block is verified as much as can be done without performing any cryptographic services.
A TR-31 key block contains an unencrypted header that can include one or more optional blocks. All parts of the header are securely bound to the key block using the integrated MAC.
Optional blocks in a key block must each be identified by a unique 2-byte ID. The value of an ID must either be defined by TR-31 or be a numeric value, otherwise the key block is invalid. Numeric IDs are reserved for proprietary use. For more information, see X9 TR-31 2010: Interoperable Secure Key Exchange Block Specification for Symmetric Algorithms.
- Use the tr31_key parameter to identify the TR-31 key block that this verb is to process.
- Call the TR31 Key Token Parse verb to parse the TR-31 key block. See TR31 Key Token Parse (CSNBT31P). Upon successful completion:
- Set the value of the tr31_key_length variable to the value returned by CSNBT31P in its tr31_key_length variable.
- Set the value of the num_opt_blocks variable to the value returned by CSNBT31P in its num_opt_blocks variable.
- Allocate a string buffer in bytes for the opt_block_ids and an integer buffer in bytes for the opt_block_lengths variables. These buffers must be at least two times the value of the num_opt_blocks variable.
- Specify a rule-array keyword of INFO to obtain information about the optional blocks in the key block. The opt_block_id, opt_block_data_length, and opt_block_data parameters are ignored.
- Call the TR31 Optional Data Read verb to read data from the TR-31 key block. Upon successful completion, the verb returns an array of optional block IDs in the opt_block_ids variable, and an array of lengths for the optional block IDs in the opt_block_lengths variable. The IDs and lengths are returned in same order as the optional blocks appear in the header of the TR-31 key block.
- Determine which ID of the unique IDs contained in the opt_block_ids
variable is to be obtained from the TR-31 key block. Set the opt_block_id
variable to this 2-byte value. Set the value of the opt_block_data_length
variable to the corresponding length from the opt_block_lengths variable.
Note: The offset used to locate the ID in the opt_block_ids variable has the same value as the offset for the corresponding length in the opt_block_lengths variable.
- Allocate a buffer in bytes for the opt_block_data variable that is at least the value of the opt_block_data_length variable.
- Specify a rule-array keyword of DATA to obtain the length and data of the specified optional block. The num_opt_blocks and the opt_block_ids parameters are ignored.
- Call the TR31 Optional Data Read verb. Upon successful completion, the verb returns the data of the specified optional block in the opt_block_data variable. The verb updates the opt_block_data_length variable to the number of bytes returned in the opt_block_data variable.
This verb does not perform cryptographic services on any key value. You cannot use this verb to change a key or to change the control vector related to a key.