Utility Provider

The Utility Provider is used to get access to services in the other BSI providers. For example, in order to invoke the gscBSIGC...() and gscBSIPKI...() methods, an application first has to invoke gscBsiUtilAcquireContext().

Access Control Rules

No specific access control rule is required to use the Utility Provider. Most Utility Provider Module functions do not need a Security Context. For example, the function gscBsiUtilAcquireContext() need not be called before calling one of the Utility Provider Module functions.

Return Codes

For further information, see section Return Codes or Table 4-1 in section 4.4 of Government Smart Card Interoperability Specification GSC-IS v2.1 https://www.nist.gov/publications/government-smart-card-interoperability-specification-version-21.

Function Summary

Method Description

gscBsiUtilAcquireContext()

Establishes the Security Context required by an SKI, GC, or Cryptographic Provider Module.

gscBsiUtilBeginTransaction()

Initiates an exclusive transaction with card.

gscBsiUtilConnect()

Connects to the card.

gscBsiUtilDisconnect()    

Disconnects from the card.

gscBsiUtilEndTransaction()

Completes a previously started exclusive transaction.

gscBsiUtilGetCardProperties()

Retrieves card information, such as the serial number and card capabilities.

gscBsiUtilGetCardStatus()

Retrieves the status of the card whose handle is specified.

gscBsiUtilGetExtendedErrorText()

Retrieves additional information about an error.

gscBsiUtilGetReaderList()

Retrieves reader list.

gscBsiUtilGetVersion()    

Retrieves version of Utility Provider.

gscBsiUtilPassthru()

Sends an APDU to the card or applet and returns its response.

gscBsiUtilReleaseContext()

Releases previously established Security Context.

Function Details

gscBsiUtilAcquireContext()

Establishes the security context required by the SKI, PKI or GC Provider Module by executing the Access Control Rule (ACR) specific to that service.

This ACR is defined as a list of BSIAuthenticator structures. Each structure defines an access method. A successful call to gscBsiUtilAcquireContext() grants access rights for functions called after it.

Syntax:

Copy
BSI_RETURN gscBsiUtilAcquireContext(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_AUTH_PTR pstrAuthenticator,
IN BSI_ULONG unAuthNb);

Parameters:

Parameters Description
hCard [in] Card connection handle that was returned by a successful call to the gscBsiUtilConnect() function.
uszAID

[in] ASCII hex encoded AID value of the applet instance corresponding to the Provider Module providing the requested protected service.

unAIDLen

[in] Length of the AID value including the NULL terminator.

pstrAuthenticator

[in] Array of structures containing authenticators specifying the access control rule required to access a service. Each authenticator corresponds to an ACR returned by the ACR discovery function provided by each Provider Module:

  • gscBsiGcGetContainerProperties() for the Generic Container Provider Module (GC applets).

  • gscBsiGetCryptoProperties() for the Cryptographic Provider Module (PKI or SKI applets).

unAuthNb

[in] Number of BSIAuthenticator structures contained in the pstrAuthenticator array. This permits authenticator chaining.

If two authentication methods are chained, as with XAUTH_THEN_PIN, then set this parameter to 2. The provider is responsible for verifying the authentication methods in sequence.

Returns:

BSI_OK if successful.

Copy
BSI_ACR_NOT_AVAILABLE
BSI_BAD_AID
BSI_BAD_AUTH
BSI_BAD_HANDLE
BSI_CARD_REMOVED
BSI_PIN_BLOCKED
BSI_UNKNOWN_ERROR

gscBsiUtilBeginTransaction()

Starts an exclusive transaction with card.

Syntax:

Copy
BSI_RETURN gscBsiUtilBeginTransaction(
IN BSI_BYTE_PTR hCard,
IN BOOL blType);

Parameters:

Parameters Description
hCard [in] Card connection handle that was obtained by a successful call to the gscBsiUtilConnect() function.
blType

[in] Specifies the type of transaction call:

  • TRUE transaction in blocking mode.

  • FALSE transaction in non-blocking mode.

    Note: Only blocking mode transactions are supported. Do not set the blType parameter to FALSE. If you do, the function returns BSI_NO_SPSSERVICE and no transaction is started.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_NO_SPSSERVICE
BSI_NOT_TRANSACTED
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiUtilConnect()

Establishes a connection with the card that is currently inserted in the specified reader so that you can communicate with the card. Returns an error if no smart card is inserted.

Syntax:

Copy
BSI_RETURN gscBsiUtilContext(
IN BSI_BYTE_PTR uszReaderName,
IN BSI_ULONG unReaderNameLen,
OUT BSI_CARD_HANDLE_PTR hCard);

Parameters:

Parameters Description
uszReaderName [in] MBCS-formatted name of the reader that contains the card to which to connect. This parameter can be NULL, in which case the function connects to the first reader in which it detects a smart card inserted.
unReaderNameLen

[in] Length in bytes, including the NULL terminator of the reader name containing the card to which to connect. This parameter is ignored if the reader name is null.

If unReaderNameLen is 0, then the function connects to the first reader in which it detects a smart card inserted.

hCard [out] Card connection handle returned by the function. The hCard handle returned is required in all other BSI API functions that communicate with the card.

Returns:

Copy
BSI_OK if successful.
BSI_BAD_PARAM
BSI_CARD_ABSENT
BSI_TIMEOUT_ERROR
BSI_UNKNOWN_ERROR
BSI_UNKNOWN_READER

gscBsiUtilDisconnect()

Releases the connection handle established with the card using gscBsiUtilConnect().

Syntax:

Copy
BSI_RETURN gscBsiUtilDisconnect(
IN BSI_CARD_HANDLE hCard);

Parameters:

hCard

[in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function. After this call, the card connection handle is no longer valid and should not be used in subsequent calls to other functions.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_CARD_REMOVED
BSI_UNKNOWN_ERROR

gscBsiUtilEndTransaction()

Completes a previously started exclusive transaction that allows other blocked applications to begin or resume interactions with the card.

Syntax:

Copy
BSI_RETURN gscBsiUtilEndTransaction(
IN BSI_CARD_HANDLE hCard);

Parameters:

hCard

[in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_NO_SPSSERVICE
BSI_NOT_TRANSACTED
BSI_UNKNOWN_ERROR

gscBsiUtilGetCardProperties()

Retrieves card CUID and capability.

Syntax:

Copy
BSI_RETURN CALLBACK gscBsiUtilGetCardProperties(
IN BSI_CARD_HANDLE hCard,
INOUT BSI_BYTE_PTR uszCCCUniqueID,
INOUT BSI_ULONG_PTR punCCCUniqueIDLen,
OUT BSI_ULONG_PTR punCardCapability);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function
uszCCCUniqueID [in, out] Buffer for Card Capability Container version. Returned buffer is empty in this version.
punCCCUniqueIDLen [in, out] Card Capability Container unique ID length. 0 in this version.
punCardCapability

[out] Card capabilities. The value returned is a bitwise OR of one or more of the following constants:

#define BSI_GCCDM 0x00000001

#define BSI_SKI 0x00000002

#define BSI_PKI 0x00000004

#define BSI_SKI_EXT 0x00000010

#define BSI_PKI_EXT 0x00000020

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiUtilGetCardStatus()

Checks whether a given card handled is associated with a card that is inserted into a powered-up reader.

Syntax:

Copy
BSI_RETURN gscBsiUtilGetCardStatus(
IN BSI_CARD_HANDLE hCard);

Parameters:

hCard

[in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.

Returns:

BSI_OK

Card is present, powered up, and was not removed since the handle was acquired.

BSI_BAD_HANDLE

Supplied handle is incorrect.

BSI_CARD_REMOVED

Card was present but is present no longer.

BSI_UNKNOWN_ERROR

gscBsiUtilGetExtendedErrorText()

Retrieves additional information about the error code returned by last function call.

Syntax:

Copy
BSI_RETURN CALLBACK gscBsiUtilGetExtendedErrorText(
IN BSI_CARD_HANDLE hCard,
OUT BSI_CHAR uszErrorText[BSI_ERROR_TEXT_LEN]);

Parameters:

hCard

[in] This parameter is not used.

uszErrorText

[out] Fixed length buffer containing an implementation specific error text string.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_NO_TEXT_AVAILABLE

gscBsiUtilGetReaderList()

Retrieves a list of readers.

Syntax:

Copy
BSI_RETURN gscBsiUtilGetReaderList(
INOUT BSI_BYTE_PTR puszReaderList,
INOUT BSI_ULONG_PTR punReaderListLen);

Parameters:

Parameters Description
puszReaderList

[in, out] Multi-string (MBCS formatted) list of reader names. Each reader name is terminated with a ‘\0’ character and two ‘\0’ characters end the list. The calling application must pre-allocate this buffer.

For further information, see Determining the Size of Buffer to Allocate.

punReaderListLen

[in] Size in bytes of the buffer pointed to by puszReaderList parameter.

[out] Set by the function in bytes for the buffer to allocate to receive the reader list.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_INSUFFICIENT_BUFFER
BSI_UNKNOWN_ERROR

gscBsiUtilGetVersion()

Retrieves version of the Utility Provider.

Syntax:

Copy
BSI_RETURN gscBsiUtilGetVersion(
OUT unsigned char *uszVersion,
INOUT unsigned long *unVersionLength);

Parameters:

Parameters Description
uszVersion

[out] Version of the Provider in the format “major,minor,revision,build_number”. Version is a null-terminated ASCII-encoded string. The calling application must pre-allocate this buffer.

See Determining the Size of Buffer to Allocate.

unVersionLength [in, out] Length of version string.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM 
BSI_INSUFFICIENT_BUFFER 
BSI_UNKNOWN_ERROR

gscBsiUtilPassthru()

Provides a passthrough service so an application can send APDUs to an applet instance while still using the provider’s other services. The application can use the passthrough to establish a Global Platform (GP) secure channel with the card.

Note: Using an APDU may cause side effects in ActivClient. In particular, changing the PIN or ActivClient buffers using the BSI API pass-through is not recommended because it may desynchronize the values cached by ActivClient and result in an inconsistent state.

Syntax:

Copy
BSI_RETURN gscBsiUtilPassthru(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszCardCommand,
IN BSI_ULONG unCardCommandLen,
INOUT BSI_BYTE_PTR pusCardResponse,
INOUT BSI_ULONG_PTR unCardResponseLen);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszCardCommand [in] Binary, ASCII hex-encoded APDU command to be sent to the card by the calling application. This allows an application to enforce APDU level security like a secure channel.
unCardCommandLen [in] Length of APDU command, including the NULL terminator to be sent to the card by the calling application.
pusCardResponse

[in, out] APDU response returned by the card to the calling application. Buffer must be pre-allocated by the caller with a fixed size of (255+2)*2 + 1.

This size is defined by ISO 7816-4 and it includes a status word and a NULL terminator. The APDU value is binary data and the returned data is ASCII hex encoded.

unCardResponseLen [in, out] Length of the APDU response, including the NULL terminator returned by the card.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiUtilReleaseContext()

Releases the Security Context previously established with a call to the gscBsiUtilAcquireContext() function and loses the corresponding access rights.

Syntax:

Copy
BSI_RETURN gscBsiUtilReleaseContext(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] ASCII hex-encoded AID value of the applet instance used in the gscBsiUtilAcquireContext() call.
unAIDLen [in] Length of the AID value including the NULL terminator.

Returns:

BSI OK if successful.

Copy
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

Extended Functionality

HID Global provides additional functionality with the following four functions that are not part of the BSI API specification.

gscXsiUtilGetCardATR()

Retrieves the card's ATR (Answer To Reset). The ATR contains information used to identify a card.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilGetCardATR(
IN BSI_CARD_HANDLE hCard,
INOUT BSI_BYTE_PTR pusATR,
INOUT BSI_ULONG *punATRLen);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
pusATR

[in, out] Buffer to be filled by the function with the card ATR. The calling application must pre-allocate this buffer. The returned buffer is not ASCII hex-encoded.

For further information, see Determining the Size of Buffer to Allocate.

punATRLen [in, out] Pointer to an unsigned long integer to be set by the function with the returned value length.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscXsiUtilGetCuid()

Retrieves the card’s unique identifier computed from Chip Identifiers.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilGetCuid(
IN BSI_CARD_HANDLE hCard,
INOUT BSI_BYTE_PTR pusSerialNumber,
INOUT BSI_ULONG_PTR punSerialNumberLen);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
pusSerialNumber

[in, out] Buffer to be filled by the function with the card's unique identifier computed from Chip identifiers. The calling application must pre-allocate this buffer.

The returned buffer is not ASCII hex-encoded.

For further information, see Determining the Size of Buffer to Allocate.

punSerialNumberLen [in, out] Pointer to an unsigned long integer to be set by the function with the returned value length.

Returns:

BSI OK if successful.

Copy
BSI_CARD_REMOVED
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_INSUFFICIENT_BUFFER
BSI_UNKNOWN_ERROR

gscXsiUtilGetIdentifier()

Returns a card identifier. Each card identifier is unique among all smart cards, whatever the card type. The identifier value may be different from the value returned by gscXsiUtilGetCuid(), depending upon the card profile.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilGetIdentifier(
IN BSI_CARD_HANDLE hCard,
INOUT BSI_BYTE_PTR pusIdentifier,
INOUT BSI_ULONG_PTR punIdentifierLen );

Parameters:

Parameters Description
hCard [in] Smart card connection handle returned by a successful call to the gscBsiUtilConnect() function.
pusIdentifier

[in, out] Buffer to be filled by the function with the card's unique identifier. The calling application must pre-allocate this buffer. The returned buffer is not ASCII hex-encoded.

For further information, see Determining the Size of Buffer to Allocate.

punIdentifierLen [in, out] Pointer to an unsigned long integer to be set by the function with the returned value length.

Returns:

BSI_OK if successful.

Copy
BSI_CARD_REMOVED
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_INSUFFICIENT_BUFFER
BSI_UNKNOWN_ERROR

gscXsiUtilChangePIN()

Change the card’s PIN code.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilChangePIN(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_BYTE_PTR usOldPIN,
IN BSI_ULONG unOldPINLen,
IN BSI_BYTE_PTR uszNewPIN,
IN BSI_ULONG unNewPINLen);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] ASCII hex-encoded AID value of the PIN applet managing the PIN code to be changed.
unAIDLen [in] Length of the PIN applet AID value including the NULL terminating character.
usOldPIN [in] Old PIN code value. This parameter must be ASCII hex encoded.
unOldPINLen [in] Length of old PIN code including the NULL terminating character.
usNewPIN [in] New PIN code value. This parameter shall be ASCII hex encoded.
unNewPINLen [in] Parameter length of new PIN code including the NULL terminating character.

Returns:

BSI_OK if successful.

Copy
BSI_ACR_NOT_AVAILABLE
BSI_BAD_AID
BSI_BAD_AUTH
BSI_BAD_HANDLE
BSI_CARD_REMOVED
BSI_PIN_BLOCKED
BSI_UNKNOWN_ERROR

gscXsiUtilIsPINVerified()

Checks if the PIN code is verified. (Verifies that a PIN code is already validated.)

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilIsPINVerified(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
OUT int* pnLeftPINTries);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] ASCII hex-encoded AID value of the PIN applet managing the PIN code to be changed.
unAIDLen [in] Length of the PIN applet AID value including the NULL terminating character.
pnLeftPINTries [out] Pointer to an unsigned long integer to be set by the function with the number of remaining wrong attempts before the card’s PIN code is locked. If the PIN is already verified, then this parameter is set to -1.

Returns:

BSI OK if successful.

Copy
BSI_ACR_NOT_AVAILABLE
BSI_BAD_AID
BSI_BAD_AUTH
BSI_BAD_HANDLE
BSI_CARD_REMOVED
BSI_PIN_BLOCKED
BSI_UNKNOWN_ERROR

gscXsiNotifySynchronizationStart()

Starts to notify synchronization

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiNotifySynchronizationStart(
IN BSI_CARD_HANDLE hCard);

Parameters:

hCard

[in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_BAD_HANDLE
BSI_UNKNOWN_ERROR

gscXsiNotifySynchronizationEnd()

Stops to notify synchronization

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiNotifySynchronizationEnd(
IN BSI_CARD_HANDLE hCard);

Parameters:

hCard

[in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_BAD_HANDLE
BSI_UNKNOWN_ERROR

gscXsiUtilGetCardManagerState()

Retrieves the Card Manager state.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilGetCardManagerState (
IN BSI_CARD_HANDLE hCard
OUT BSI_INT_PTR piState);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
piState [out] Pointer to the retrieved card manager state: BSI_CARD_OP_READY or BSI_CARD_LOCKED.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_BAD_HANDLE
BSI_CARD_LOCKED
BSI_CARD_REMOVED
BSI_UNKNOWN_ERROR

gscXsiUtilGetForceChangePIN()

Retrieves the Force Change PIN flag.

Syntax:

Copy
BSI_RETURN CALLBACK gscXsiUtilGetForceChangePIN(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
OUT BOOL* pbForceChangePIN);

Parameters:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] ASCII hex-encoded AID value of the PIN applet managing the PIN status to be checked.
unAIDLen [in] Length of the PIN applet AID value including the NULL terminating character.
pbForceChangePIN [out] ] Pointer to bool to be set by the function with the Force Change PIN flag value.

Returns:

BSI_OK if successful.

Copy
BSI_BAD_PARAM
BSI_BAD_HANDLE
BSI_BAD_AID
BSI_CARD_REMOVED
BSI_UNKNOWN_ERROR