Data Types and Structures
Data types and other structures used by the PIV API are described in this section.
Basic Types
The HID Global implementation follows the C language binding of basic types defined in 800-85A.
PIV_Bool
Boolean.
typedef unsigned char PIV_Bool
PIV_Byte
Byte.
typedef unsigned char PIV_Byte
PIV_CARDHANDLE
Specify a type for the card connection handle managed by PIV.
typedef unsigned long PIV_CARDHANDLE
PIV_RV
Type used for all PIV API functions’ return value.
typedef unsigned long PIV_RV
PIV_ULong32
Unsigned Long.
typedef unsigned long PIV_ULong32
Connection Description Buffer
This section provides a detailed description of the ConnectionDescription pivConnect() function parameter. This parameter, defined in [SP800-73-1] section 5.4.Table 11, represents a BER-TLV buffer containing the connection description data to be used to connect to the PIV API card application.
The connection description V-Buffer consists of an ordered sequence of tags and values. Each tag labels a specific type of information about the connection. Each tag is followed by a length indicating the length of the value buffer corresponding to that tag, and then a value buffer that indicates the actual value of the information for the corresponding tag.
Tags
The HID Global implementation supports the following tags:
-
0x81: PC/SC tag
-
0x90: Network node tag
In the case of the 0x90 tag, the HID Global implementation ignores the length and value buffers that follow the 0x90 tag.
Other tags are rejected by the pivConnect() function. An error is returned depending of the tag value:
-
If the value of the unsupported tag is a value described in NIST [SP 800-73] publication (0x82, 0x83, 0x84, 0x85, 0x86, 0x91, 0x92, 0x93), then the function returns PIV_CONNECTION_FAILURE.
-
In all other cases, the function returns PIV_CONNECTION_DESCRIPTION_MALFORMED.
The presence of both tags (0x81 and 0x90) in the connection description is mandatory. This implies a minimum size for the input buffer of 7 bytes.
Obtaining the List of Smart Card Readers
The ConnectionDescription buffer should be formatted as shown in the following illustration when used to retrieve the list of smart card readers that are connected to the PC:
