3.1 Entry Points for Communication (was: PIV Card Application Card Commands for Data Access)

Before · SP 800-73-4

PIV Card Application Card Commands for Data Access

After · SP 800-73-5

PIV Card Application CardEntry CommandsPoints for Data AccessCommunication

Before · SP 800-73-4

After · SP 800-73-5

3.1.1. pivMiddlewareVersion

Purpose: Returns the PIV Middleware version string

Prototype: status_word pivMiddlewareVersion ( OUT version versionString );

Parameter: versionString

• For SP 800-73-5 Part 3 conformant PIV Middleware, the parameter returns “800-73-5 Client API” or “800-73-5 Client API with SM.”

• For SP 800-73-4 Part 3 conformant middleware, the parameter returns “800-73-4 Client API” or “800-73-4 Client API with SM.”

• Earlier versions with versionString (e.g., “800-73-3 Client API,” “800-73- 2 Client API,” and “800-78-1 Client API”) are discontinued as they do not conform to the requirements of FIPS 201-3.

Return Codes: PIV_OK

PIV Middleware that returns a versionString of “800-73-5 Client API with SM” and “800-73-4 Client API with SM” SHALL implement all PIV Middleware functions listed in Table 1 and be able to recognize and process all mandatory and optional PIV data objects. PIV Middleware that returns a versionString of “800-73-5 Client API” and “800-73-4 Client API” SHALL implement all PIV Middleware functions listed in Table 1 except for pivEstablishSecureMessaging and SHALL be able to recognize and process all mandatory and optional PIV data objects.

3.1.2. pivConnect

Purpose: Connects the client API to the PIV Card Application on a specific ICC.

Prototype: status_word pivConnect ( IN Boolean sharedConnection, INOUT sequence of bytes connectionDescription , INOUT LONG CDLength, OUT handle cardHandle );

Parameters: sharedConnection If TRUE, other client applications CAN stablish concurrent connections to the ICC. If FALSE and the connection is established, then the calling client application has exclusive access to the ICC.

connectionDescription A connection description data object (tag 0x7F21). See Table 2 . If the length of the value field of the ‘8x’ data object in the connection description data object is zero, then a list of the card readers of the type indicated by the tag of the ‘8x’ series data object and available at the ‘9x’ location is returned in the connectionDescription.

In order to provide sufficient space for the return value, the client application SHALL allocate a buffer of at least 2048 bytes for connectionDescription.

The connection description BER-TLV [ISO8825] used on the PIV client API SHALL have the structure described in Table 2 .

Table 2. Data objects in a connection description template (Tag 0x7F21)

Description Tag Comment Interface device – PC/SC ‘81’ Card reader name Interface device – SCP ‘82’ Card reader identifier on terminal equipment Interface device – EMR ‘83’ Contactless connection using radio transmission Interface device – IR ‘84’ Contactless connection using infrared transmission

Interface device – PKCS #11 ‘85’ PKCS #11 interface Interface device – CryptoAPI ‘86’ CryptoAPI interface Network node – Local ‘90’ No network between client application host and card reader host Network node – IP ‘91’ IP address of card reader host Network node – DNS ‘92’ Internet domain name of card reader host Network node – ISDN ‘93’ ISDN dialing number string of terminal equipment containing the card reader

At most one selection from the ‘8x’ series and one selection from the ‘9x’ series SHALL appear in the connection description template. For example, ‘7F 21 0C 82 04 41 63 6D 65 91 04 C0 00 02 17’ describes a connection to a generic card reader at internet address 192.0.2.23. In another example, ‘7F 21 0B 82 01 00 93 06 16 17 55 50 12 3F’ describes a connection to the subscriber identity module in the mobile phone at +1 617 555 0123.

When used as an argument to the pivConnect entry point on the PIV client API described in this section, an ‘8x’ series data object with zero length and a ‘9x’ series data object request the return of all available card readers of the described type on the described node. Thus, ‘7F 21 04 81 00 90 00’ would request a list of all available PC/SC card readers on the host on which the client application was running. CDLength Length of the card description parameter

cardHandle The returned opaque identifier of a communication channel to a particular ICC and, hence, of the card itself. cardHandle is used in all other entry points on the PIV client API to identify which card the functionality of the entry point should be applied to. Return Codes: PIV_OK PIV_CONNECTION_DESCRIPTION_MALFORMED PIV_CONNECTION_FAILURE PIV_CONNECTION_LOCKED

3.1.3. pivDisconnect

Purpose: Disconnect the PIV API from the PIV Card Application and the ICC that contains the PIV Card Application.

Prototype: status_word pivDisconnect ( IN handle cardHandle ); Parameters: cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect. The value of cardHandle is undefined upon return from pivDisconnect.

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_CARD_READER_ERROR

If secure messaging has been established, then the PIV Middleware SHALL zeroize the secure messaging session keys.