About the BSI API

HID ActivClient BSI is the HID implementation of the BSI 2.1 specification.

The BSI API is used by legacy applications to access the services provided by applets stored on a supported smart card or key.

Note:

We strongly recommend using higher-level cryptographic APIs, such as PKCS#11 or the Microsoft Cryptography API, to interact with smart cards and keys. The BSI API is considered a legacy API and, compared to these other APIs, provides full support only for CAC-compliant cards.

ActivClient BSI v9.7

Support for read operations
Support for APDU pass-through

BSI API Coverage

Note: A limitation of the current BSI version is that its functions are not thread-safe. Although the functions can be called from different threads, the application must ensure that no functions operating on the same handle are executed concurrently.

Supported functions

Unless otherwise noted, the functions conform to the BSI 2.1 specification.

The following tables list the implementation status of BSI API functions and any relevant compatibility notes.

Utility Provider Functions

Utility Provider Functions
Function	Description	Supported
gscBsiUtilGetVersion	Returns the BSI implementation version.	Yes
gscBsiUtilGetReaderList	Retrieves the list of available readers.	Yes
gscBsiUtilConnect	Establishes a logical connection with a card in a specified reader.	Yes
gscBsiUtilDisconnect	Terminates a logical connection to a card.	Yes
gscBsiUtilGetCardStatus	Checks whether the card is inserted and powered up in the reader.	Yes
gscBsiUtilGetCardProperties	Retrieves ID and capability information for the card.	Yes¹
gscBsiUtilGetExtendedErrorText	Returns implementation specific error message for the last error.	Yes
gscBsiUtilBeginTransaction	Starts an exclusive transaction with the smart card.	Yes^{2, 3}
gscBsiUtilEndTransaction	Completes a previously started transaction.	Yes
gscBsiUtilPassthru	Sends a raw APDU to the card.	Yes
gscBsiUtilAcquireContext	Establishes an authenticated session with the card.	Yes⁴
gscBsiUtilReleaseContext	Terminates a session with the card.	Yes
¹ The card ID returned is the hex-encoded serial number of the card. ² Only blocking transactions are supported, i.e. the second parameter must be TRUE. ³ Although the specification requires “nested” gscBsiUtilBeginTransaction calls to return BSI_NOT_TRANSACTED errors, ActivClient instead returns BSI_OK and requires the same number of gscBsiUtilEndTransaction calls to release the transaction. ⁴ The authenticator data (PINs, etc.) must be provided as hex-encoded ASCII strings. This differs from the specification, which requires the data to be provided as an arbitrary sequence of bytes.

Generic Container Provider Functions

Function	Description	Supported
gscBsiGcDataCreate	Creates a new data item in a container.	No
gscBsiGcDataDelete	Deletes a data item from a container.	No
gscBsiGcGetContainerProperties	Retrieves the properties (ACRs, sizes, versions) of the specified container.	Yes
gscBsiGcReadTagList	Returns the tags of items in a container.	Yes¹
gscBsiGcReadValue	Returns a data item from a container.	Yes
gscBsiGcUpdateValue	Updates a data item in a container.	No
¹ Some cards may allow unauthenticated users to retrieve a list of items while requiring authentication to read the item data. This behavior is not supported; authentication is also required for listing the items.

Cryptographic Provider Functions

Function	Description	Supported
gscBsiPkiCompute	Performs a private key computation on a message digest.	Yes¹
gscBsiPkiGetCertificate	Reads a certificate from the card.	Yes¹
gscBsiGetCryptoProperties	Retrieves Access Control Rules and key length of a given private key.	Yes²
gscBsiGetChallenge	Retrieves a randomly generated challenge from the card.	No
gscBsiSkiInternalAuthenticate	Computes a symmetric key cryptogram in response to a challenge.	No
¹ Although the standard requires the input and output data to be in binary form, the ActivClient BSI implementation requires the data to be hex-encoded. ² Although the standard requires that the size of the keys be specified in bits, the ActivClient BSI implementation reports the sizes in bytes.