TR-31 Optional Data Build (CSNBT31O and CSNET31O)

A TR-31 key block can hold optional fields which are securely bound to the key block using the integrated MAC. The optional blocks may either contain information defined in the TR-31 standard, or they may contain proprietary data.

Use the TR-31 Optional Data Build callable service to construct the optional block data structure for a TR-31 key block. It builds the structure by adding one optional block with each call, until your entire set of optional blocks have been added.

With each call, the application program provides a single optional block by specifying its ID, its length, and its data in parameters opt_block_id, opt_block_length, and opt_block_data respectively. Each subsequent call appends the current optional block to any preexisting blocks in the opt_blocks parameter. On the first call to the callable service, opt_blocks is typically empty.

The callable service name for AMODE(64) is CSNET31O.

Format

CSNBT31O(
         return_code,
         reason_code,
         exit_data_length,	
         exit_data,
         rule_array_count,
         rule_array,
         opt_blocks_bfr_length,
         opt_blocks_length,
         opt_blocks,
         num_opt_blocks,
         opt_block_id,
         opt_block_data_length,
         opt_block_data )

Parameters

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return and reason codes lists the reason codes.

exit_data_length

Direction	Type
Ignored	Integer

This field is ignored. It is recommended to specify 0 for this parameter.

exit_data

Direction	Type
Ignored	String

This field is ignored.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 0 since no keywords are currently defined for this callable service.

rule_array

Direction	Type
Input	String

The rule_array contains keywords that provide control information to the callable service. There are no rule_array keywords currently defined for this callable service.

opt_blocks_bfr_length

Direction	Type
Input	Integer

This parameter specifies the length of the buffer passed with the opt_blocks parameter. This length is used to determine if it would overflow the buffer size when adding a new optional block to the current contents of the buffer.

opt_blocks_length

Direction	Type
Input/Output	Integer

This parameter specifies the actual length of the set of optional blocks currently contained in the opt_blocks buffer. On output, it is updated with the length after the callable service has added the new optional block.

opt_blocks

Direction	Type
Input/Output	String

This parameter specifies a buffer containing the set of optional blocks being built. In the first call, it will generally be empty. The callable service will append one optional block to the buffer with each call. Parameter opt_blocks_bfr_length specifies the total length of this buffer, and an error will be returned if this length would be exceeded by adding the optional block in parameter opt_block_data to the current contents. This parameter is encoded in ASCII on both input and output.

num_opt_blocks

Direction	Type
Output	Integer

This parameter contains the number of optional blocks contained in the structure returned in parameter opt_blocks. This is provided as an output parameter so that it can subsequently be used as an input to the TR-31 Export callable service.

opt_block_id

Direction	Type
Input	String

This parameter specifies a two-byte value which is the identifier (ID) of the optional block passed in parameter opt_block_data.

opt_block_data_length

Direction	Type
Input	Integer

This parameter specifies the length of the data passed in parameter opt_block_data. Note that it is valid for this length to be zero; an optional block can have an ID and a length, but no data.

opt_block_data

Direction	Type
Input	String

This parameter specifies a buffer where the application passes the data for the optional block that is to be added to those already in the buffer in parameter opt_blocks. The length of this data is specified in parameter opt_block_data_length.

Restrictions

None.

Usage notes

Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see EBCDIC and ASCII Default Conversion Tables). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification.

Note that the Padding Block, ID “PB” is not allowed to be added by the user. A Padding Block of the appropriate size, if needed, will be added when building the TR-31 key block in TR-31 Export. If the TR-31 Export callable service encounters a padding block in the optional block data, an error will occur.

Required hardware

No cryptographic hardware is required by this callable service.