Overview

Include Files Required

The necessary include files are located in the BSI/C/Headers folder of the distribution package.

How to Deploy

BSI API applications can be linked statically with the BSI API import library. The static libraries are located in the BSI/C/Libraries/x86 and BSI/C/Libraries/x64 folders of the distribution package.

Access Control Rules

An access method is an authentication method that must be verified by the smart card before access to card services is allowed. An access control rule is a set of access methods that are logically ORed and/or ANDed together.

Each smart card service is protected by specific access control rules. The set of access control rules is defined for each service during card issuance when the smart card is initialized. Each Provider Module offers a discovery function call that allows an application to discover which access control rules govern access to the services available in the module. The smart card will not provide services if the access control rules are not validated.

Establishing the Security Context

The Utility Provider Module of the BSI API provides the access control functions. The calling application must establish the security context by invoking the gscBsiUtilAcquireContext() function. The calling application is then responsible for releasing the security context using the gscBsiUtilReleaseContext() function.

External Authentication Access Control Rule Modes

  • Strong

  • Weak

Mode Description
Strong

From a security perspective, the Strong mode is preferred. Use this mode if the application has very high operational security requirements, where it is not acceptable to expose the external authentication key (for example, the application operates a Hardware Security Module (HSM)). Before calling the authentication function, the calling application should call the gscBsiGetChallenge() function provided by the Cryptographic Provider Module in order to get a challenge from the card.

To ensure that the authentication key never leaves the HSM, the calling application should perform the challenge encryption required by its HSM and provide the resulting cryptogram in the AuthValue member of the BSIAuthenticator structure.

Weak

Do not use this mode, it is documented only for backward compatibility.

In this mode, the external authentication key is passed to the BSI Provider in clear text by the calling application, then the BSI Provider encapsulates the external authentication transaction with the card or the applet.

The clear text key is provided in the Key member of the Authenticator structure (for further information, see section BSI Authenticator).

Access Method Types:

See section for a list of access method types.

Access Control Rule Types:

See section for a list of access control rule types. The GCAcr structure specifies the access control rules supported by the Generic Container Provider. The CRYPTOAcr structure specifies the ACR supported by the Cryptographic Provider.

Access Control Rule Values:

The following table lists access control rule values and explains how those values affect the corresponding service.

Mode Description

BSI_ACR_ALWAYS

Always. The service is provided without restrictions. No access control rule is required.

BSI_ACR_NEVER    

Never. The service can never be provided.

BSI_ACR_PIN

PIN Protected. The service is provided only if its associated PIN code has already been verified in the current card session.

BSI_ACR_PIN_ALWAYS

Always PIN Protected. The service is provided only if its associated PIN code is verified in the current card session immediately prior to service request.

BSI_ACR_PIN_THEN_XAUTH

PIN presentation followed by External Authentication.

BSI_ACR_UPDATE_ONCE

Not implemented.

BSI_ACR_XAUTH

External Authenticate. The service is provided only after a challenge/response exchange has been performed between the client application and the card. For possible operation modes, see section .

BSI_ACR_XAUTH_AND_PIN

External Authenticate and PIN. Either one of the two controls gives access to the corresponding service. This allows a validation of the card holder when a PIN PAD is available and for an external authentication when no PIN PAD is available.

BSI_ACR_XAUTH_OR_PIN

External Authenticate or PIN. Either one of the two controls gives access to the corresponding service. This allows a validation of the card holder when a PIN PAD is available and for an external authentication when no PIN PAD is available.

BSI_ACR_XAUTH_THEN_PIN

External Authenticate then PIN. You must chain External Authenticate method first, then the PIN protected method, both successfully, in order that access to the service be granted. This makes it possible to authenticate the application and the user of the application.

BSI_SECURE_CHANNEL_GP

 

Secure Channel Global Platform. The service is provided through a Secure Channel managed by the card’s Secure Messaging layer. The calling application must operate inside the gscBsiUtilPassthru() function.

BSI_SECURE_CHANNEL_ISO

Not implemented.

BSI_SECURE_CHANNEL_OP

Legacy ACR: use BSI_SECURE_CHANNEL_GP instead.

Secure Channel Access Control Rule:

The Secure Channel Access Control Rule requires that cryptographic operations be performed at the Application Protocol Data Unit (APDU) level. The BSI API offers a pass-through service that allows the calling application to send the correct APDU to the card to open the Secure Channel. As with other access controls, this rule is defined during card issuance.

Cryptographic Algorithms

The BSI API supports the following cryptographic algorithms:

  • DES ECB with a single length key size, 8 bytes.

  • Triple DES ECB with a double length key size, 16 bytes.

  • RSA_NO_PAD computation on the private key, Chinese Remainder Theorem.

Data Encoding

All NULL-terminated strings (parameters with prefix usz) contain only printable ASCII characters. You must encode all binary data in ASCII hexadecimal format. The length parameter for data should include the length of the encoded string plus one byte for the NULL terminator.

  • Example 1:

For example, the raw hexadecimal data 0x01, 0xFE, and 0x32 would be encoded as the string 01FE32. The length parameter associated with this buffer equals 7.

Note: The buffer string must be NULL terminated.

  • Example 2:

    The following call returns BSI_BAD_PARAM because value and value length are inconsistent (value length should be 7):

    gscBsiGcUpdateValue(hCard, uszAID, unAIDLen, ucTag, “01FE32”, 6)

Determining the Size of Buffer to Allocate

Some provider functions require the calling application to provide pre-allocated tables or buffers for the function output. For ASCII hex-encoded data, the length must include the NULL terminator. If the buffer passed is not large enough, the function returns the BSI_INSUFFICIENT_BUFFER error code.

In order to determine how big a buffer is needed, the calling application can call the function twice:

  1. If, in the first call, the calling application sets the buffer address parameter to NULL, the function places the number of bytes needed into the buffer size parameter.

  2. Then, before the second call, the calling application allocates a buffer of the appropriate size and calls the function with the address of this buffer.

Support for Multi-threading

This API is thread-safe. However, it provides no built-in multithreading methods. To perform operations simultaneously, the calling application must implement multiple threads.

Support for Concurrency

The PC/SC layer as leveraged by the ActivClient APIs supports transactions that serialize all operations from concurrent applications safely. ActivClient uses the PC/SC Transactions API to ensure card security and consistency.

For additional information, see http://msdn2.microsoft.com/En-US/library/aa379469.aspx.