Entry Points

Communication

Method	Description
pivMiddlewareVersion()	Returns the PIV Middleware version string.
pivConnect()	Connects the client application to the PIV smart card application.
pivDisconnect()	Disconnects the client application from the PIV smart card application.

pivMiddlewareVersion()

Returns the PIV Middleware version string

Syntax:

Copy

PIV_RV pivMiddlewareVersion (
char * versionString)

Parameters:

versionstring

[inout] Pointer to a buffer containing the version of PIV Middleware. For SP 800-73-3 Part 3 conformant PIV Middleware, the parameter returns “800-73-3 Client API”.

Returns:

PIV_OK

versionString has been has been retrieved successfully.

PIV_INPUT_BYTES_MALFORMED

versionString could not be retrieved.

pivConnect()

Connects the client application to the PIV smart card application on a specific integrated circuit chip (ICC). If the smart card that is inserted in the reader and to which the method is attempting to connect does not contain a PIV smart card application, then the function fails with an error code. Otherwise, the function succeeds and the PIV smart card application (AID = [A0 00 00 03 08 00 00 10 00]) is selected.

Syntax:

Copy

PIV_RV pivConnect (
PIV_Bool sharedConnection, PIV_Byte *connectionDescription, PIV_ULong32 *pCDLength, PIV_CARDHANDLE *pCardHandle)

Parameters:

Parameters	Description
sharedConnection	[in] Boolean value that indicates whether other applications can establish concurrent connections with the PIV smart card application. If this parameter is true then the connection is shared, otherwise it is exclusive. Note: To be compatible with ActivClient, the installed connection must be shared.
connectionDescription	[inout]: Input: Pointer to a buffer containing a connection description BER-TLV data object. This buffer should conform to the format described in . This parameter must be large enough to hold the returned value. This parameter should never be NULL. Output: When the connection description is used to retrieve the list of readers (tag 0x81 and NULL length), the function updates the ConnectionDescription buffer with the list of readers. The format of the returned list is: The connectionDescription buffer length is indicated by the pCDLength parameter.
pCDLength	[inout] Input: Pointer to an unsigned long containing the connectionDescription buffer size. This parameter should never be NULL. Output: When tag 0x81 is used with a null length to get the reader list, the function returns the reader list length into this parameter. This value is used by the calling application to allocate the correct input buffer size if necessary.
pCardHandle	[out] Pointer to a PIV_CARD_HANDLE. If this function call succeeds, the returned CardHandle can be used in all subsequent calls to other PIV API functions. Otherwise the output value should not be used.

Returns

PIV_OK

The smart card is positioned in the reader and the reader returns a handle. Return Code: SCARD_S_SUCCESS from PC/SC.

PIV_CONNECTION_DESCRIPTION_MALFORMED

Either:

The content of the connectionDescription parameter does not conform to Table 11 of [SP 800-73].
The description buffer length as indicated by the pCDLength parameter is too small to hold the returned reader list.
When attempting to connect to the reader, PC/SC returned one of the following error codes:

SCARD_E_UNKNOWN_READER

SCARD_E_DUPLICATE_READER

PIV_CONNECTION_LOCKED

Either:

A shared connection exists and an exclusive connection was requested.
An exclusive connection exists and a shared/an exclusive connection was requested. Return Code: SCARD_E_SHARING_VIOLATION from PC/SC.

PIV_CONNECTION_FAILURE

This may have occurred because:

There is no smart card in the reader.
A wrong connection mode was specified (say, ISDN connection parameters for a PC/SC reader).
The PC/SC service was not started (perhaps because the reader is not connected to local host).

PC/SC return codes handled by the PIV API in its pivConnect() implementation, and mapped into the PIV_CONNECTION_FAILURE error code:

SCARD_E_NO_SMARTCARD

SCARD_E_UNKNOWN_CARD

SCARD_W_UNRESPONSIVE_CARD

SCARD_E_INVALID_ATR

SCARD_E_NO_SERVICE

SCARD_E_NO_READERS_AVAILABLE

SCARD_F_COM_ERROR

pivDisconnect()

Disconnects the PIV application programming interface from the PIV smart card application and the ICC containing the PIV smart card application.

Syntax

Copy

PIV_RV pivDisconnect (PIV_CARDHANDLE cardHandle)

Parameters

cardHandle

[in] Communication handle returned by a successful call to the pivConnect() function. After the call to pivDisconnect, this handle is undefined and should not be used in subsequent calls.

Returns

PIV_OK

The request to disconnect was successful.

PIV_INVALID_CARD_HANDLE

Either:

Function was called with an invalid smart card handle, or
Successful disconnect was already called with this smart card handle

Return code from PC/SC: SCARD_E_INVALID_HANDLE

PIV_CARD_READER_ERROR

Reader is not connected to the local host.
There is no smart card in the reader.
An event has occurred that prevents communication with the smart card.

The following return codes are the PC/SC return codes handled by the PIV API in its pivDisconnect() implementation and mapped into the PIV_CARD_READER_ERROR error code:

SCARD_F_COMM_ERROR

SCARD_W_UNPOWERED_CARD

SCARD_W_RESET_CARD

SCARD_W_REMOVED_CARD

SCARD_E_READER_UNAVAILABLE

Data Access

Method	Description
pivGetData()	Returns the entire data content of the named data object.
pivLogIntoCardApplication()	Authenticates the client application to the smart card application (for example, present a PIN to the smart card) and hence establishes the initial security status in the smart card application context.
pivLogoutOfCardApplication()	Resets the applications security status of the PIV smart card application.
pivSelectCardApplication()	Sets the currently selected smart card application.

pivGetData()

Returns the entire data content of the named data object.

Note: The HID Global implementation of pivGetData() does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before it calls this function.

Syntax

Copy

PIV_RV pivGetData (
PIV_CARDHANDLE cardHandle,
PIV_Byte *OID,
PIV_ULong32 oidLength,
PIV_Byte *data, PIV_ULong32 *pDataLength)

Parameters

Parameters	Description
cardHandle	[in] Communication handle returned by a successful call to the pivConnect() function.
OID	[in] Pointer to a byte string containing the ASN.1 identifier of the object whose data content is to be retrieved. See ASN.1 OID Identifiers for a list of supported identifiers. This parameter should never be NULL. The function fails if any other ASN.1 OID is used. This function fails if the smart card does not contain the object with the corresponding OID.
oidLength	[in] Unsigned long containing the OID buffer size. This parameter should never be NULL.
data	[out] Pointer to a buffer to be set by the function with the required data content. This pointer may be NULL if the calling application requires only the length of the data content. If this pointer is NULL, then the pDataLength pointer should not be NULL. Note: For performance purposes, HID Global middleware implements a secure data cache mechanism to store data read from the smart card into memory. This mechanism ensures that data is read only once from the smart card, even if the pivGetData() function is called twice in a row.
pDataLength	[inout] This parameter should never be NULL. Input: Pointer to an unsigned long containing the size of the data buffer. If data parameter is NULL, then the value pointed to by pDataLength may be NULL as well. Output: The pointed value is set by the function with the data content length. This parameter should be used by the calling application to allocate the correct input buffer size if necessary, before calling this function once again. Note: To retrieve the number of bytes required for the OID data (discovery mode), set the data parameter to NULL; this function sets the variable pointed to by pDataLength to the required length and returns PIV_INSUFFICIENT_BUFFER.If the data parameter is not NULL, the pDataLength parameter must not be NULL either.

Returns

Code	Description
PIV_OK	The OID is valid; an existing smart card handle is returned. Return code from smart card: 0x90 0x00.
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE.
PIV_CARD_READER_ERROR	The reader is not connected to the local host, or No smart card is in the reader, or An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivGetData() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE
PIV_INVALID_OID	The OID is not found in Table 6 of [SP 800-73].
PIV_DATA_OBJECT_NOT_FOUND	The OID refers to a data object not found on the smart card. Return code from smart card: 0x6A 0x82.
PIV_SECURITY_CONDITIONS_NOT_SATISFIED	Access to the smart card object denoted by OID is denied since security condition for its access not satisfied. Return code from smart card: 0x69 0x82.
PIV_INSUFFICIENT_BUFFER	The buffer supplied in the data parameter is too small. pDataLength contains the required size.

pivLogIntoCardApplication()

Establishes the application security status within the PIV smart card application, either by verifying the smart card holder PIV smart card application PIN or by performing an external authentication using the PIV smart card application administration key.

The HID Global implementation of pivLogIntoCardApplication() does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before it calls this function.

Syntax

Copy

PIV_RV pivLogIntoCardApplication (
PIV_CARDHANDLE cardHandle,
PIV_Byte *authenticators,
PIV_ULong32 pAuthLength)

Parameters

Parameters

Description

cardHandle

[in] Communication handle returned by a successful call to the pivConnect() function.

authenticators

[in] Pointer to a buffer containing a sequence of zero or more BER-TLV authenticator data objects. This buffer should conform to the format described in the Authenticator description section in [800-73-1] Table 10.

If the authenticators parameter is NULL, the AuthLength parameter must also be 0 and no authentication is performed. In this case, the function may return PIV_OK if no error condition occurs.

pAuthLength

[in] Unsigned long containing the authenticators buffer size. This parameter may be 0 if no authentication is to be performed; if this is the case, the function returns PIV_OK.

Returns

Code	Description
PIV_OK	Authenticators are well-formed; an existing smart card handle is returned. Return code from smart card: 0x90 0x00.
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE.
PIV_AUTHENTICATOR_MALFORMED	The authenticator does not conform to the format specified in Table 10 of [SP 800-73-1]. Return code from smart card: 0x6A 0x80 or 0x6A 0x88.
PIV_AUTHENTICATION_FAILURE	The reference data in the authenticator is not valid. Return code from smart card: 0x63Cx or 0x69 0x83.
PIV_AUTHENTICATION_FAILURE	The reference data in the authenticator is not valid. Return code from smart card: 0x63Cx or 0x69 0x83.
PIV_CARD_READER_ERROR	The reader is not connected to the local host, or No smart card in the reader, or An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivLogIntoCardApplication() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE

pivLogoutOfCardApplication()

Resets the application security status of the PIV smart card application. Access rights acquired by a previous call to the pivLogIntoCardApplication() are lost.

The HID Global implementation does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before calling this function.

Copy

PIV_RV pivLogoutOfCardApplication(
PIV_CARDHANDLE cardHandle)

Parameters

Parameter	Description
cardHandle	[in] Communication handle returned by a successful call to the pivConnect() function.
PIV_OK	An existing smart card handle is returned. Return code from smart card: 0x90 0x00
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE
PIV_CARD_READER_ERROR	The reader is not connected to the local host, or No smart card is in the reader, or An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivLogoutOfCardApplication() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE

pivSelectCardApplication()

Sets the currently selected smart card application. The call is successful if the given PIV smart card application is found; otherwise, an error code is returned.

Note: HID Global optimizes the implementation of this method so that if it is called multiple times once the application has been selected, it does not go to the card to select the application again. This means that invoking this method multiple times does not impact performance.Discovery mode is supported by this method; if the applicationProperties parameter is NULL, then this function sets the value pointed to by pAPLength to the required length of the applicationsProperties buffer and returns PIV_OK.

Syntax

Copy

PIV_RV pivSelectCardApplication (
PIV_CARDHANDLE cardHandle,
PIV_Byte *applicationAID,
PIV_ULong32 aidLength,
PIV_Byte *applicationProperties,
PIV_ULong32 *pAPLength)

Parameters

	Description
cardHandle	[in] Communication handle returned by a successful call to the pivConnect() function.
applicationAID	[in] Pointer to a buffer containing the AID of the PIV smart card application to select. It may be either a long AID including the version number or a short AID without version number. This parameter should never be NULL.
aidLength	[in] Unsigned long containing the applicationAID buffer size. This parameter should never be NULL.
applicationProperties	[out] Pointer to a buffer to be set by the function with the application properties of the specified smart card application. This pointer may be NULL if application properties are not required by the calling application. If this parameter is not NULL, then the pAPLength parameter should not be NULL either. If this pointer is NULL, discovery mode is triggered and the function returns PIV_INSUFFICIENT_BUFFER.
pAPLength	[inout] Input: Pointer to an unsigned long containing the size in bytes of the applicationProperties buffer. This parameter must not be NULL. Output: In discovery mode, the buffer to which this parameter points is set by the function with the length of the application properties. This information is used by the calling application to allocate the correct input buffer size, if necessary, before calling this function once again.

Returns

Code	Description
PIV_OK	An existing smart card handle and a valid application AID are returned. Return code from smart card: 0x90 0x00
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE
PIV_CARD_APPLICATION_NOT_FOUND	Application AID does not refer to an AID that the smart card supports. Return code from smart card: 0x6A 0x82
PIV_CARD_READER_ERROR	Reader is not connected to the local host, No smart card in the reader, or An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivSelectCardApplication() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE
PIV_INSUFFICIENT_BUFFER	pAPLength is NULL or applicationProperties is NULL or buffer is too small.

Cryptographic Operations

Method	Description
pivCrypt()	Performs a cryptographic operation such as encryption or signing.

pivCrypt()

Performs a cryptographic operation such as encryption or signing on a sequence of bytes.

The HID Global implementation does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before calling this function.

Syntax

Copy

PIV_RV pivCrypt (
PIV_CARDHANDLE cardHandle,
PIV_Byte algID,
PIV_Byte keyReference,
PIV_Byte *algInput,
PIV_ULong32 inputLength,
PIV_Byte *algOutput,
PIV_ULong32 *pOutputLength)

Parameters

Parameter	Description
cardHandle	[in] Communication handle returned by a successful call to the pivConnect() function.
algID	[in] Unsigned char containing the identifier of the cryptographic algorithm to be used for the cryptographic operation. The HID Global implementation supports all the algorithms listed in Table 7 of NIST [SP800-73-1] publication: • 05, 06, 07 for asymmetric algorithms. • 01, 02, 03, 04, 08, 09, 0A, 0B, 0C, 0D, 0E, 0F, 10, 11, 12, 13 for symmetric algorithms. • 00 for symmetric or asymmetric algorithm depending on the keyReference. Other values are rejected and the function returns an error.
keyReference	[in] Key reference value of the key to be used for the cryptographic operation. The HID Global implementation supports all the key reference values listed in Table 12 of the NIST [SP 800-73] publication other than 9A, 9B, 9C, and 9D. The HID Global implementation does support the value 9E. Other key reference values are rejected and the function returns an error.
algInput	[in] Pointer to a buffer containing the Dynamic Authentication Template to be sent to the smart card, including complete formatting and padding when necessary. For more information, see the Dynamic Authentication Template Format definition in Table 17 of [SP-800-73-1]. This parameter should never be NULL.
inputLength	[in] Unsigned long containing the algInput buffer size. This parameter should never be NULL.
algOutput	[out] Pointer to a buffer to be set by the function with the Dynamic Authentication Template returned by the smart card, including complete formatting. This parameter can be NULL, in which case the function returns PIV_INSUFFICIENT_BUFFER.
pOutputLength	[out] Pointer to an unsigned long containing the algOutput buffer size. This parameter can be NULL, in which case the function returns PIV_INSUFFICIENT_BUFFER.

Returns

Sequence of bytes output by the cryptographic operation.

Code	Description
PIV_OK	An existing smart card handle is returned. Return code from smart card: 0x90 0x00.
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE.
PIV_CARD_READER_ERROR	• The reader is not connected to the local host, or • No smart card is in the reader, or • An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivCrypt() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE
PIV_INPUT_BYTES_MALFORMED	The algInput and/or inputLength parameter was NULL. Return code from smart card: 0x6A 0x80
PIV_SECURITY_CONDITIONS_NOT_SATISFIED	The sign operation is protected and the application security status was not established accordingly by a successful call to pivLogIntoCardApplication(). This error code is also returned if the PIN is locked. Note: In case of mutual authentication or external authentication, when called to get the cryptogram, the pivCrypt function should not be called twice in a row. The second call will result in a PIV_SECURITY_CONDITIONS_NOT_SATISFIED error. Return code from smart card: 0x69 0x82 or 0x69 0x83

Credential Initialization and Administration

Method	Description
pivGenerateKeyPair()	Generates an asymmetric key pair from the PIV smart card application.
pivPutData()	Replaces the entire data content of the named data object with the provided data.

pivGenerateKeyPair()

Generates an asymmetric key pair in the currently selected application.

The HID Global implementation does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before it calls this function.

Syntax

Copy

PIV_RV pivGenerateKeyPair(
PIV_CARDHANDLE cardHandle,
PIV_Byte keyReference,
PIV_Byte cryptographicMechanism,
PIV_Byte *publicKey,
PIV_ULong32 *pKeyLength)

Parameters

Parameter	Description
cardHandle	[in] Communication handle returned by a successful call to the pivConnect() function.
KeyReference	[in] Key reference value of the key to be generated. The HID Global implementation supports all the key reference values listed in Table 12 of NIST [SP 800-73] publication, corresponding to asymmetric key pairs: 9A, 9C, 9D. The HID Global implementation supports value 9E. Other key reference values are rejected and the function returns an error.
CryptographicMechanism	[in] The type of the key pair to be generated. See NIST [SP 800-73] Cryptographic Mechanism Identifiers for the supported cryptographic mechanism identifiers.
publicKey	[out] Pointer to the buffer to be set by the function with the public key of the generated key pair. Format of the returned buffer is: This parameter can be NULL, in which case the function returns PIV_INSUFFICIENT_BUFFER and sets pKeyLength with the required buffer size.
pKeyLength	[out] Pointer to an unsigned long containing the size of the publicKey buffer. This parameter can be NULL, in which case the function returns PIV_INSUFFICIENT_BUFFER.

Returns

Code	Description
PIV_OK	An existing smart card handle is returned.
PIV_INVALID_CARD_HANDLE	Function was called with an invalid smart card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE
PIV_CARD_READER_ERROR	The reader is not connected to the local host, or No smart card is in the reader, or An event occurred that prevented communication with the smart card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivGenerateKeyPair() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE
PIV_INVALID_KEY_OR_KEYALG_COMBINATION	The value of the keyReference parameter is unsupported as an RSA key reference value. Return code from smart card: 0x6A 0x86
PIV_UNSUPPORTED_CRYPTOGRAPHIC_MECHANISM	The value of the cryptographicMechanism is not a supported value. Return code from smart card: 0x6A 0x80
PIV_SECURITY_CONDITIONS_NOT_SATISFIED	The generated key pair operation is protected and the application security status was not established by a successful call to thepivLogIntoCardApplication(). This error code is also returned if the PIN is locked. Return code from smart card: 0x69 0x82 or 0x69 0x83
PIV_INSUFFICIENT_BUFFER	The supplied output buffer is too small. pKeyLength contains the required buffer size.

pivPutData()

Replaces the entire data content of the named data object with the provided data. The HID Global implementation does not require the calling application to select the PIV smart card application (pivSelectCardApplication()) before it calls this function.

Syntax

Copy

PIV_RETURN pivPutData(
PIV_CARDHANDLE cardHandle,
PIV_Byte *OID,
PIV_ULong32 oidLength,
PIV_Byte *data,
PIV_ULong32 dataLength)

Parameters

Method	Description
cardHandle	[in] The communication handle returned by a successful call to the pivConnect() function.
OID	[in] Pointer to a null-terminated string containing the ASN.1 identifier of the object whose data content is to be replaced. Table 6 of NIST [SP 800-73] publication lists supported identifiers. See ASN.1 OID Identifiers for a list of supported identifiers. Any other ASN.1 OID is rejected and the function fails. If the object identified by the OID is valid according to the standard (defined in table 6), but is not present in the smart card, this function fails. This parameter should never be NULL.
oidLength	[in] Unsigned long containing the OID buffer size. This parameter should never be NULL.
data	[in] Pointer to a buffer containing the data to be used to replace the data content of the requested object. This parameter should never be NULL.
dataLength	[in] Unsigned long containing the data buffer size. This parameter should never be NULL.

Returns

Code	Description
PIV_OK	An existing smart card handle is returned. Return code from smart card: 0x90 0x00
PIV_INVALID_CARD_HANDLE	Function was called with an invalid card handle. Return code from PC/SC: SCARD_E_INVALID_HANDLE
PIV_CARD_READER_ERROR	The reader is not connected to the local host, or No card is in the reader, or An event occurred that prevented communication with the card. The PC/SC error codes that are mapped into PIV_CARD_READER_ERROR in the pivPutData() implementation: SCARD_F_COMM_ERROR SCARD_W_UNPOWERED_CARD SCARD_W_RESET_CARD SCARD_W_REMOVED_CARD SCARD_E_READER_UNAVAILABLE
PIV_INVALID_OID	The buffer pointed to by the OID parameter contains an OID unsupported by ASN.1 OID (see Table 6 of NIST [SP 800-73] publication or ASN.1 OID identifiers, above).
PIV_SECURITY_CONDITIONS_NOT_SATISFIED	The sign operation is protected but the application security status was not been established by a successful call to pivLogIntoCardApplication(). This error code is also returned if the PIN is locked. Return codes from smart card: 0x69 0x82 or 0x69 0x83
PIV_INSUFFICIENT_CARD_RESOURCE	The smart card does not have enough resources to process the operation. Return code from smart card: 0x6A 0x84