BaselineWatch
Desk
Your fleet and your work Fleetyour releases and the hardware they run onTriagewhat needs a decisionWatchlistthe products and platforms you runSaved searchesthe lists you come back to
This instance Sourceswhat is read, how often, under what termsDigestthe daily or weekly summary, and alerts
How it is drawn Appearancethe look and the colour schemeBrandingthe mark this instance wears
Owner sign-in

3.2 Entry Points for Data Access (was: PIV Card Application Card Commands for Authentication)

NIST PIV and digital identity SP 800-73-5 against SP 800-73-4
All changes in this version
modified 3 Client Application Programming Interface part of 3

Title changed

Before · SP 800-73-4

PIV Card Application Card Commands for Authentication

After · SP 800-73-5

PIV Card Application CardEntry CommandsPoints for AuthenticationData Access

Control changed

Before · SP 800-73-4

After · SP 800-73-5

3.2.1. pivSelectCardApplication

Purpose: Set the PIV Card Application as the currently selected card application and establish the PIV Card Application’s security state.

Prototype: status_word pivSelectCardApplication ( IN handle cardHandle , IN sequence of byte applicationAID, IN LONG aidLength, OUT sequence of byte applicationProperties, INOUT LONG APLength );

Parameters: cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect

aidLength Length of the PIV Card Application AID

applicationAID The AID of the PIV Card Application that is to become the currently selected card application

applicationProperties The application properties of the selected PIV Card Application; see SP 800-73-5 Part2, Table 3

APLength As an input, length of the buffer allocated for applicationProperties; as an output, length of the application properties

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_CARD_APPLICATION_NOT_FOUND PIV_CARD_READER_ERROR PIV_INSUFFICIENT_BUFFER

If the length of application properties is longer than the buffer allocated by the client application, then the PIV Middleware SHALL return PIV_INSUFFICIENT_BUFFER but SHALL still set APLength to the length of the application properties.

3.2.2. pivEstablishSecureMessaging

Purpose: Establish secure messaging with the PIV Card Application.

Prototype: status_word pivEstablishSecureMessaging ( IN handle cardHandle , );

Parameters: cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_CARD_READER_ERROR PIV_SM_FAILED

After successful execution of the key establishment protocol, the PIV Middleware SHALL perform all subsequent GET DATA, VERIFY, and GENERAL AUTHENTICATE commands over secure messaging with the exception of any subsequent uses of the GENERAL AUTHENTICATE command to perform the key establishment protocol. 3.2.3. pivLogIntoCardApplication

Purpose: Set the security state within the PIV Card Application.

Prototype: status_word pivLogIntoCardApplication ( IN handle cardHandle , IN sequence of byte authenticators, IN LONG AuthLength ); Parameters: cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect

authenticators A sequence of zero or more BER-TLV-encoded authenticators to be used to authenticate and set the security state/status in the PIV Card Application context.

The authenticator BER-TLV used on the PIV client API SHALL have the structure described in Table 3 .

AuthLength Length of the authenticator template.

Table 3. Data objects in an authenticator template (Tag '67')

Description Tag M/O Comment Reference data '81' M Value of the PIV Card Application PIN, Global PIN, or pairing code, as described in Sec. 2.4.3 of SP 800-73-5 Part2, or OCC data, as described in Sec. 5.5.2 of [SP800-76] Key reference '83' M See Table 4 of SP 800-73-5 Part1 for PIV Card Application PIN, Global PIN, pairing code, and OCC key reference values

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_AUTHENTICATOR_MALFORMED PIV_AUTHENTICATION_FAILURE PIV_SECURITY_CONDITIONS_NOT_SATISFIED PIV_CARD_READER_ERROR PIV_SM_FAILED

The PIV Middleware SHALL NOT submit authenticators to the PIV Card over a contactless interface without secure messaging. If secure messaging has not been established, then the pivLogIntoCardApplication function SHALL return PIV_SECURITY_CONDITIONS_NOT_SATISFIED . 3.2.3.1. pivGetData

Purpose: Return the entire data content of the named data object.

Prototype: status_word pivGetData ( IN handle cardHandle , IN string OID , IN LONG oidLength, OUT sequence of byte data, INOUT LONG DataLength );

Parameters:

cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect

OID Object identifier of the object whose data content is to be retrieved coded as a string (e.g., “2.16.840.1.101.3.7.2.96.80”). See SP 800-73-5 Part1, Table 3.

oidLength Length of the object identifier.

data Retrieved data content.

DataLength As an input, length of the buffer allocated for data. As an output, length of the data retrieved from the PIV Card.

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_INVALID_OID PIV_DATA_OBJECT_NOT_FOUND PIV_SECURITY_CONDITIONS_NOT_SATISFIED PIV_CARD_READER_ERROR PIV_SM_FAILED PIV_INSUFFICIENT_BUFFER

If the length of the retrieved data is longer than the buffer allocated by the client application, then the PIV Middleware SHALL return PIV_INSUFFICIENT_BUFFER but SHALL still set DataLength to the length of the retrieved data. If the PIV Card Application returns a zero-length data object, then the PIV Middleware SHALL return PIV_DATA_OBJECT_NOT_FOUND .

3.2.4. pivLogoutOfCardApplication

Purpose: Reset the application security state/status of the PIV Card Application. Prototype: status_word pivLogoutOfCardApplication ( IN handle cardHandle );

Parameters: cardHandle Opaque identifier of the card to be acted upon as returned by pivConnect. The cardHandle remains valid after execution of this function.

Return Codes: PIV_OK PIV_INVALID_CARD_HANDLE PIV_CARD_READER_ERROR