Return Codes

The PIV API translates error codes returned by the PC/SC Microsoft API into PIV API error codes.

Return Code Description

PIV_OK

Successful return code.

PIV_AUTHENTICATION_FAILURE

Authentication failed.

PIV_AUTHENTICATOR_MALFORMED

The authenticator’s data objects to be used by the pivLogIntoCardApplication() function do not conform to the expected data format (Table 10 of [SP 800-73]).

PIV_CARD_APPLICATION_NOT_FOUND

Application AID does not refer to an AID that the card supports.

PIV_CARD_READER_ERROR

An unexpected APDU response or an unexpected response from the PC/SC layer was received. This usually happens when, for some reason, an event occurred that prevented communication with the card.

PIV_CONNECTION_DESCRIPTION_MALFORMED

The ConnectionDescription parameter in the function call does not conform to the required data format or the PC/SC returned one of the following error codes:

  • SCARD_E_UNKNOWN_READER

  • SCARD_E_DUPLICATE_READER

PIV_CONNECTION_FAILURE

There is no smart card in the reader or the smart card returned an unexpected answer or no answer at all or the PC/SC service is not started.

PIV_CONNECTION_LOCKED

An SCARD_E_SHARING_VIOLATION error was returned by PC/SC. Either:

  • A shared connection exists but an exclusive connection was requested, or

  • An exclusive connection exists but a shared/exclusive connection was requested.

PIV_INPUT_BYTES_MALFORMED

Incorrect input data format (Table 17 of [SP 800-73]).

PIV_INSUFFICIENT_BUFFER

Supplied output buffer too small.

PIV_INVALID_CARD_HANDLE

The communication handle is invalid. This generally happens when a function was called with an invalid card handle or when the smart card has been removed from the reader. The error corresponds to SCARD_E_INVALID_HANDLE from PC/SC.

PIV_INVALID_KEY_OR_KEYALG_COMBINATION

Inconsistency in pivGenerateKeyPair() input parameters.

PIV_INVALID_KEYREF_OR_ALGORITHM

Unsupported key reference value or unsupported cryptographic mechanism for a general authenticate operation, either by the standard (Table 12 of [SP 800-73]) or by the card.

PIV_INVALID_OID

Object identifier is not one defined in ASN.1 OID (Table 6 of [SP 800-73]).

PIV_SECURITY_CONDITIONS_NOT_SATISFIED

This error code occurs if you do not have the AR to perform the operation. For example, you need to perform an external authenticate to generate a key. It is not limited to the PIN AR.

PIV_UNSUPPORTED_CRYPTOGRAPHIC_MECHANISM

The cryptographic mechanism value is not one of the algorithm identifiers found in Table 7 of [SP 800-73] or supported by the card.