Generic Container Provider

A Generic Container is a protected storage area on a smart card.

The Generic Container (GC) Provider makes it possible to create, delete, read, and update collections of {tag, length, value} data items stored on a card within a container. Each of these actions is protected with specific access controls.

The Generic Container Provider is compatible with the Common Access Card (CAC) demographic information data and J.8 identity information data models. The BSI API GC services can be used to read this information.

The Generic Provider can also be used to read/store any other application-specific data such as health, certification, training, or biometric data or rosters.

Discovery Functions

The GC Provider offers a number of discovery functions to applications:

• Discover the list of data items managed by the container.

• Discover the properties of the container in terms of size, access control rules, and so on.

Differentiating Between Data Sets

Each container has its own set of access control rules for create, delete, read, and update operations. If data sets require different security settings, you must place them in separate containers with different access control rules. Within a container, different keys can be defined for read and write access. The available size of the container limits the number and the size of data items within the card.

Each data item in a Generic Container is tagged. This tag allows the GC Provider to access the data item value stored on the card. The Provider also offers the service of listing the tags managed by a container, thus allowing an application to discover what container is managed and to pick the value it needs by referring to it by its tag.

Access Control Rules

Before it calls any Generic Container Provider function, the client application must first establish a security context with the Generic Container Provider Module by:

• Calling the discovery function, gscBsiGcGetContainerProperties(), to return a GCAcr structure defining the access control rules for a GC service.

• Establishing the security context according to the retrieved ACR using the gscBsiUtilAcquireContext() function.

Compatibility with the Card Edge Interface

In order to use data stored in a Generic Container Applet instance that is accessible to GSI/XSI applications, the application must:

• Use the Card Edge API as specified in the GSC-IS standard documentation.

• Know the format of the data that is stored in the Generic Container, including:

• Byte order

• Single vs. multi-byte data storage

SIMPLE-TLV Data Object

Internal Tag Length Value (TLV) format is required to access the card services through the Card Edge directly. Each SIMPLE-TLV data object consists of two or three consecutive fields:

• TLV tag field

  The tag field identifies the data stored in the corresponding V buffer. The tag field T consists of a single byte encoding only a number between 1 and 254. No class or construction types are coded.

• TLV length field

  The length field consists of one or three consecutive bytes.

  The meaning of the length field changes depending upon the value of the leading byte in the length field:

  • If the leading byte of the length field is in the range from 00 to FE, the length field is the leading byte and consists of a single byte integer L with a value between 0 and 254.

    • If L is not equal to 0, the value field V consists of L consecutive bytes.

    • If L equals 0, or if a tag is omitted from its file or buffer, the data object is empty, and there is no value field for that tag.

  • If the leading byte equals FF, the length field continues through the two subsequent bytes, which encode an integer L with a value between 0 and 65,535. (The leading field is upper byte of the three-byte integer L.)

• The V field

  The V field contains the data item for the corresponding Tag. Its format and encoding is left to the calling application. Its length is defined by the L field.

Byte Order

The byte order in V depends upon the application.

T is always only 1 byte long.

In the L field, the byte ordering of multi-byte attributes is LSB first.

Generic Container Data Types and Structures

The Generic Container Provider operates on tagged data. The data structures it uses are:

• GCTag

• BSI_GCT

The container size structure is GCContainerSize. A pointer to a GCContainerSize, BSI_GC_SIZE_PTR, is also provided.

Function Summary

This section includes a full description of each function in the Generic Container Provider Module.

Access Control

Data Management Functions

Function Details

gscBsiGcDataCreate()

Creates a new data item {tag, length, value} in the specified container. In order to create a data item successfully, the client application must first establish a Security Context with the Generic Container Provider Module for the requested service: Create.

Syntax:

BSI_RETURN gscBsiGcDataCreate(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_GCT ucTag,
IN BSI_BYTE_PTR uszValue,
IN BSI_ULONG unValueLen);

Parameters:

Returns:

BSI_OK BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_IO_ERROR
BSI_NO_CARDSERVICE
BSI_NO_MORE_SPACE
BSI_SC_LOCKED
BSI_TAG_EXISTS
BSI_UNKNOWN_ERROR

gscBsiGcDataDelete()

Deletes the data item identified by a given tag and its associated value from the specified container. In order to delete a data item successfully, the client application must first establish a Security Context with the Generic Container Provider Module for the requested service: Delete.

Syntax:

BSI_RETURN gscBsiGcDataDelete (
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR pszAID,
IN BSI_ULONG unAIDLen,
IN BSI_GCT ucTag);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_BAD_TAG
BSI_CARD_REMOVED
BSI_IO_ERROR
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiGcGetContainerProperties()

This method returns three types of information:

• The Generic container size,

• The Generic container version,

• The Generic container access control rules for the GC services. The access control rules apply to all data items stored in the specified container.

Syntax:

BSI_RETURN gscBsiGcGetContainerProperties(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
OUT BSI_GC_ACR_PTR strctGCacr,
OUT BSI_GC_SIZE_PTR strctContainerSizes,
OUT BSI_BYTE_PTR containerVersion);

Parameters:

Returns:

BSI_OK
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_NO_CARDSERVICE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiGcReadTagList()

Retrieves the list of tags from the specified container.

In order to read a list of tags successfully, the client application must first establish a Security Context with the Generic Container Provider Module for the requested service: Read Tag List.

Syntax:

BSI_RETURN gscBsiGcReadTagList(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
INOUT BSI_GCT_PTR TagArray,
INOUT BSI_ULONG_PTR unNbTags);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_CARD_REMOVED
BSI_NO_CARDSERVICE
BSI_INSUFFICIENT_BUFFER
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiGcReadValue()

Returns the value identified by a given tag in a specific container.

In order to read the value identified by a given tag successfully, the client application must first establish a Security Context with the Generic Container Provider Module for the requested service: Read Value.

Syntax:

BSI_RETURN gscBsiGcReadValue(
IN BSI_CARD_HANDLE hCard,
IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_GCT ucTag,
INOUT BSI_BYTE_PTR uszValue,
INOUT BSI_ULONG_PTR unValueLen);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_BAD_TAG
BSI_CARD_REMOVED
BSI_INSUFFICIENT_BUFFER
BSI_NO_CARDSERVICE
BSI_IO_ERROR
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR

gscBsiGcUpdateValue()

Updates the value identified by a given tag in a specific container.

In order to update the value identified by a given tag successfully, the client application must first establish a Security Context with the Generic Container Provider Module for the requested service: Update Value.

Syntax:

BSI_RETURN gscBsiGcUpdateValue(
IN BSI_CARD_HANDLE hCard, IN BSI_BYTE_PTR uszAID,
IN BSI_ULONG unAIDLen,
IN BSI_GCT ucTag,
IN BSI_BYTE_PTR uszValue, IN BSI_ULONG unValueLen);

Parameters:

Returns:

BSI_OK
BSI_ACCESS_DENIED
BSI_BAD_AID
BSI_BAD_HANDLE
BSI_BAD_PARAM
BSI_BAD_TAG
BSI_CARD_REMOVED
BSI_IO_ERROR
BSI_NO_CARDSERVICE
BSI_NO_MORE_SPACE
BSI_SC_LOCKED
BSI_UNKNOWN_ERROR