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

Method Description
gscBsiGcGetContainerProperties()

A container may contain multiple data items each identified by a tag.

The access control applies to all data items stored in this container. This function retrieves access conditions that enable reading and updating of tags and their values for the specified container.

Access conditions returned are shared by all data items present in the container. Retrieves container sizes.

Data Management Functions

Method Description

gscBsiGcDataCreate()    

Creates a new data item in a specific container. This will store a value and a tag.

gscBsiGcDataDelete()    

Deletes a data item from the specified container.

gscBsiGcReadTagList()

Retrieves the list of tags from the specified container.

gscBsiGcReadValue()    

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

gscBsiGcUpdateValue()

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

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:

Copy
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:

Parameters Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] AID value of the applet (Generic Container on the card) in which the new data item is to be created. This parameter shall be ASCII hex encoded.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
ucTag [in] Tag identifying the value of the new data item to create.
uszValue [in] New value to create. This parameter shall be ASCII hex encoded.
unValueLen [in] Length of the encoded value string that includes the NULL terminator.

Returns:

Copy
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:

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

Parameters:

Method Description
hCard [in] Card connection handle returned by a successful call to the gscBsiUtilConnect() function.
uszAID [in] AID value of the applet (Generic Container on the card) in which the data item should be deleted. This parameter shall be ASCII hex encoded.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
ucTag [in] Tag identifying the value of the data item to delete.

Returns:

Copy
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:

Copy
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:

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 (Generic Container on the card) whose properties should be retrieved.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
strctGCacr [out] Pointer to a structure to be set by the function with the Access Control Rules defined for the services provided by this Generic Container applet. Caller must allocate this structure before passing it to this function. The structure is not populated if the input pointer is NULL.
strctContainerSizes [out] Structure indicating the sizes of the two storage areas of the container. The caller must allocate this structure. This parameter is not returned if the pointer is set to NULL.
containerVersion

[out] Container version in ASCII format. The calling application must pre-allocate this buffer.

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

Returns:

Copy
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:

Copy
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:

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 (Generic Container on the card) in which the tag list should be read.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
TagArray

[in, out] Buffer to be filled by the function with the list of tags stored in the Generic Container. Calling application must pre-allocate this buffer.

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

unNbTags [in, out] Pointer to a long integer to be set by the function with the returned tag count.

Returns:

Copy
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:

Copy
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:

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 (Generic Container on the card) in which the value should be read.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
ucTag [in] Tag identifying the value to be read.
uszValue

[in, out] Buffer to be filled by the function with the value identified by the tag provided in the ucTag parameter. Calling application must pre-allocate this buffer.

For further information, see Determining the Size of Buffer to Allocate. Value returned in this buffer is ASCII hex encoded.

punValueLen [in, out] Pointer to an unsigned long integer to be set by the function with the returned value length. This includes the NULL terminator.

Returns:

Copy
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:

Copy
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:

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 (Generic Container on the card) in which the value should be updated.
unAIDLen [in] Length of the Generic Container AID value including the NULL terminator.
ucTag [in] Tag identifying the value to be updated.
uszValue [in] ASCII hex encoded buffer containing the new value to associate with the tag provided in ucTag parameter.
unValueLen [in] Length of the new value including the NULL terminator.

Returns:

Copy
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