Data Types and Structures

Data types and other structures used by the BSI API are described in this section.

Basic Types

These types must be used for parameters passed to the BSI functions.

Type	Sample code
BSI_ULONG	typedef unsigned long BSI_ULONG
BSI_BYTE	typedef unsigned char BSI_BYTE
BSI_BYTE_PTR	typedef BSI_BYTE BSI_BYTE_PTR
BSI_INT	typedef BSI_ULONG BSI_INT
BSI_UINT	typedef BSI_ULONG BSI_UINT
BSI_CHAR	typedef char BSI_CHAR

BSI Return Type

All BSI functions return error codes of this type.

BSI_RETURN

Copy

Sample code:

typedef BSI_ULONG BSI_RETURN

Card Connection Types

Use this type for card connection handle parameters required by BSI functions.

BSI_CARD_HANDLE

Copy

Sample code:

typedef BSI_ULONG BSI_CARD_HANDLE

BSI_CARD_HANDLE_PTR

Copy

Sample code:

typedef BSI_CARD_HANDLE * BSI_CARD_HANDLE_PTR

Generic Container Types

GCContainerSize

Copy

typedef struct strctContainerSizes {
BSI_ULONG unMaxNbDataItems;
BSI_ULONG unMaxValueStorageSize;
} GCContainerSize;
typedef GCContainerSize BSI_GC_SIZE;
typedef BSI_GC_SIZE BSI_PTR BSI_GC_SIZE_PTR;

Fields:

unMaxNbDataItems

unsigned long. Maximum number of {tag, length, value} data items a given Generic Container instance can hold.

unMaxValueStorageSize

unsigned long. The maximum size of the value buffer of the container.

Generic Container Data Identification Types

The Generic Container data identification types are:

GCTag

The type for Generic Container tags. Provided for backward compatibility. Use BSI_GCT instead.

typedef BSI_BYTE GCTag

BSI_GCT

GSC-IS 2.1 Generic Container tag type definition.

typedef GCtag BSI_GCT

Access Control Rule Structures

BSIAuthenticator

The BSIAuthenticator structure defines an access method. Client applications use this structure to establish a security context with the card. This structure contains the access method type and its associated authenticator. An array of BSIAuthenticator structures defines an access control rule and is provided as a parameter to the gscBsiUtilAcquireContext() function. The gscBsiUtilAcquireContext() function extracts the authenticators from the structure and passes them to the card applet for verification.

To release the access rights acquired, use the gscBsiUtilReleaseContext() function.

For further information see Data Encoding, External Authentication Access Control Rule Modes, and the gscBsiGetChallenge() method.

Copy

typedef struct {
BSI_ULONG unAccessMethodType; BSI_ULONG unKeyIDOrReference;
BSI_BYTE uszAuthValue [BSI_AUTHENTICATOR_MAX_LEN]; BSI_ULONG unAuthValueLen;
} BSIAuthenticator;
typedef BSIAuthenticator* BSI_AUTH_PTR

The below table mentions the access method type and its details.

Field or Method Type	Description	Value
unAccessMethodType	BSI_ULONG. Access method type. This parameter must correspond to the one returned by the ACR discovery function provided by the Provider Module: gscBsiGcGetContainerProperties() for the Generic Container Provider Module. gscBsiGetCryptoProperties() for the Cryptographic Provider Module	Either BSI_AM_PIN or BSI_AM_XAUTH. If the usAuthValue parameter is set to the external authentication key to be used in the Provider's weak mode or to the external authentication cryptogram used in provider’s strong mode, the unAccessMethodType field should be set to BSI_AM_XAUTH.
unKeyIDOrReference	BSI_ULONG. Key identifier or reference of the authenticator. Use this field to distinguish between multiple authenticators with the same access method type.	If the usAuthValue parameter is set to the External Authentication key to be used in the Provider's weak mode or to the External Authentication cryptogram used in provider’s strong mode, the unKeyIDOrReference field should be set to the value returned by the ACR discovery function.
usAuthValue	char. ASCII hex-encoded. This parameter holds the value of the authenticator.	The values this field can take are: PIN code. In this case, the unAccessMethodType field of this structure should be set to BSI_AM_PIN. The External Authentication cryptogram used in provider’s strong mode. In this case, you must call the gscBsiGetChallenge() function prior to obtaining the context. or The External Authentication key to be used in the Provider's weak mode. In this case, the unAuthValueLen field of this structure should be set to 0. Note: If the unAuthValueLen field is set to 0, then this field is ignored.
unAuthValueLen	BSI_ULONG. Authenticator value length.	The values this field can take are: If unAccessMethodType is BSI_AM_PIN, if unAuthValueLen is set to 0, the usAuthValue is ignored and the BSI API implementation displays a user interface that allows user to enter the PIN code. Otherwise, set unAuthValueLen to the ASCII encoded PIN code length (including the NULL terminator). If unAccessMethodType is BSI_AM_XAUTH, if unAuthValueLen is set to 0, the authentication is assumed to be performed using weak mode. If unAuthValueLen is non-zero, the authentication is assumed to be performed using strong mode. Set this value to the length of the ASCII-encoded cryptogram (including NULL terminator).

BSIAcr

The BSIAcr structure is the ACR type returned by the gscBsiGcGetContainerProperties() and gscBsiGetCryptoProperties() ACR discovery methods. It is used by the application to discover which access controls protect various card services.

This structure is part of the BSI_GC_ACR and BSI_CRYPTO_ACR structures.

Copy

#define MaxNbAM 4
typedef struct strctBSIAcr {
BSI_ULONG unACRType;
BSI_ULONG unKeyIDOrReference[MaxNbAM]; BSI_ULONG unAuthNb;
BSI_ULONG unACRID;
} BSIAcr;

Fields

unACRType

BSI_ULONG. Access control type.

Values:

See possible values in Access Control Rule Types (ACRType).

unKeyIDOrReference

BSI_ULONG. Array of keyIDOrReferences that contains the key identifier or reference for each access method contained in the ACR in order of appearance. These key references are used when calling the gscBsiUtilAcquireContext() function to establish the Security Context.

unAuthNb

BSI_ULONG. The number of access methods logically combined in the ACR.

unACRID

Not used.

GCAcr

Structure indicating access control conditions for all Generic Container operations:

Create Container
Delete Container
Read Tag
Read Value
Update Value

For further information, see the Government Smart Card Interoperability Specification GSC-IS v2.1https://www.nist.gov/publications/government-smart-card-interoperability-specification-version-21, section 4.6.3.

Copy

typedef struct strctGCacr {
BSIAcr strctCreateACR;
BSIAcr strctDeleteACR;
BSIAcr strctReadTagListACR;
BSIAcr strctReadValueACR;
BSIAcr strctUpdateValueACR;
} GCacr;
typedef GCacr GCAcr;
typedef GCAcr BSI_GC_ACR;
typedef BSI_GC_ACR BSI_PTR BSI_GC_ACR_PTR;

CRYPTOAcr

Structure indicating access control conditions for all cryptographic operations:

Get challenge
Internal authenticate
PKI compute
Create container
Delete container
Read tag list
Read value
Update value

For further information, see the Government Smart Card Interoperability Specification GSC-IS v2.1 https://www.nist.gov/publications/government-smart-card-interoperability-specification-version-21, section 4.7.5.

Copy

typedef struct strctCRYPTOacr {
BSIAcr strctGetChallengeACR;
BSIAcr strctInternalAuthenticateACR;
BSIAcr strctPkiComputeACR;
BSIAcr strctCreateACR;
BSIAcr strctDeleteACR;
BSIAcr strctReadTagListACR;
BSIAcr strctReadValueACR;
BSIAcr strctUpdateValueACR;
} CRYPTOacr;
typedef CRYPTOacr CRYPTOAcr;
typedef CRYPTOAcr BSI_CRYPTO_ACR;
typedef BSI_CRYPTO_ACR * BSI_CRYPTO_ACR_PTR;