Core Services

Introduction

The Trust1Connector core services address communication functionality with local, unmanaged devices. The Trust1Connector core exposes 2 main interfaces:

• interface for web/native/Java applications
• framework interface for private or community containers

In this guide, we target only the use of Trust1Connector's core interface for native or Java applications. The GCL exposes protected and unprotected resources.

Protected resources

Protected resources are administration resources. The Java library must be initialized with a correct token in order to access the resource.

• Get registration information
• Register device
• Synchronize device

Executing these functionality is explained further.

Un-protected resources

Un-protected resources can be used without the need of an additional security token.

• Get pub-key certificate (administration resource)
• Update pub-key certificate (administration resource)
• List card-readers
• List containers
• Get container
• Get card-reader
• Get card-readers with card inserted
• Get card-readers without card
• Detect card for card-reader (polling utility resource)
• Detect any card (polling utility resource)
• Detect card-readers (polling utility resource)
• OS Information (utility resource)

Executing these functionality is explained further.

Core Functionality

The core functionality is about communication with device hardware.
The document highlights communication with smart card readers - contact and contact-less. In the future, documentation will be updates with information for USB and Bluetooth connectivity.

Information

First we instantiate a new T1C client, as follows:

```java
LibConfig conf = new LibConfig();
conf.setEnvironment(Environment.DEV);
conf.setDsUri(DS_URI);
conf.setOcvUri(OCV_URI);
conf.setGclClientUri(URI_T1C_GCL);
conf.setApiKey(API_KEY);
conf.setHardwarePinPadForced(false);
conf.setDefaultPollingIntervalInSeconds(5);
conf.setDefaultPollingTimeoutInSeconds(10);
conf.setSessionTimeout(60);
T1cClient t1cClient = new T1cClient(conf);

In order to retrieve information about the installed device, the following function can be called:

GclStatus status = t1cClient.getCore().getInfo();

List card readers

Returns a list of available card readers. Multiple readers can be connected. Each reader is identified by a unique id.

List<GclReader> readers = t1cClient.getCore().getReaders();

The response will contains a list of card readers:

com.t1t.t1c.GclReader

com.t1t.t1c.GclCard

When multiple readers are attached to a device, the response will show all connected card readers

Important to notice:

• The response adds a card-element when a card is inserted into the card reader.
• The response contains card-reader pin-pad capabilities

Card Inserted

As mentioned in the List card-readers, when a smart-card is inserted/detected, the reader will contain the cart-type based on the ATR. The ATR (Anwser To Reset), is the response from any smart-card when powered, and defines the card type.
The Trust1Connector recognized more than 3k smart-card types.

Pin-Pad Capabilities

As mentioned in the List card-readers, when a card-reader has pin-pad capabilities, this will be mentioned in the response (notice the pinpadproperty):

Get Card-Reader

We can address a specific card-reader by using the card-reader reader object received from the previous call List card-readers:

List<GclReader> readers = t1cClient.getCore().getReaders();
GclReader reader = t1cClient.getCore().getReader(readers.get(0).getId());

The response will contain the information for the card-reader; including pin-pad capabilities or a card property when a smart-card is inserted or detected

Get card reader with card inserted

Returns a list of available card readers with a smart card inserted. Multiple readers can be connected with multiple smart cards inserted. Each reader is identified by a unique id and contains information about a connected smart card. A smart card is of a certain type. The Trust1Connector detects the type of the smart card and returns this information in the GclReader object response.

List<GclReader> readers = t1cClient.getCore().getReadersWithInsertedCard();

Get card reader without inserted card

Returns a list of available card readers without an inserted smart card.

List<GclReader> readers = t1cClient.getCore().getReadersWithoutInsertedCard();

List containers

Returns a list of available containers and container versions. Multiple versions of a container can run on the same Trust1Connector framework. In order to select the correct container, a id defines the unique id of a container.

List<GclContainer> containers = t1cClient.getCore().getContainers();

Response:

com.t1t.t1c.core.GclContainer

Get platform information

Returns platform information that is needed in order to download a GCL instance.

PlatformInfo info = t1cClient.getCore().getPlatformInfo();

Response:

com.t1t.t1c.model.PlatformInfo

com.t1t.t1c.model.OsInfo

com.t1t.t1c.model.PlatformInfo

Administration Services

The T1C-JLIB can be used to execute administration services.
In the Java library, administration services are called with an additional Bearer token in the request header:
The underlying GCL service will be requested, for example, with the following headers:

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer eyJhbGciOiJSUzI...kRIIXz6bxTHFnqFX28oXk' 'https://localhost:10443/v1/core/update'

Initialization

The initialization process performs 2 main tasks:

• one-time registration/activation of the GCL
• retrieve JWT and check for updates

The one-time registration is explained further in Register Device.
Upon initialization the T1C-JLIB will try to retrieve a valid JWT in order to check for updates.

More information for the configuration of the T1C-JLIB can be found in Client Configuration.
Depending of the initialization of the T1C-JLIB, we have the following possibilities:

In order to refresh JWT, the T1C-JLIB lib will request automatically a new JWT, by exchange of the existing JWT, as long as the token expiration time is still valid.

Utility Services

Utility services are function calls, available in the Java library, implementing flows using the aforementioned elementary core functionality. A flow is the execution of a logical sequence of one or more resources
Utility services are there to ease the integration, but can be implemented by the consumer itself.

Detect Card Readers

A utility function in order to detect a card reader. The goal of this function is to start a card reader detection-process for a fixed amount in time (web application controls the poll-time). When a card-reader has been found, the card-reader info is returned and the poll process stops looking for card-readers.

T1cClient t1cClient = new T1cClient(conf);
Integer pollIntervalInSeconds = 5;
Integer pollTimeoutInSeconds = 30;
List<GclReader> readers = t1cClient.getCore().pollReaders(pollIntervalInSeconds, pollTimeoutInSeconds);

The pollIntervalInSeconds expects an integer and denotes the interval between attempts to detect card-readers. A default value can be configured in the client configuration.

The pollTimeoutInSeconds expects an integer and denotes the total time during which the client should attempt to detect card-readers. A default value can be configured in the client configuration.

On success the function returns card-reader info (same response as in card-reader info).

Detect Readers with Card Inserted

A utility function in order to detect an inserted card. If a card is already inserted, the reader info, including card info will be send back as a response. The function verifies if there is a card-reader connected, and if so, return the list of readers with inserted cards. When a card-reader is connected and a card is detected, the info is send back as a response.

T1cClient t1cClient = new T1cClient(conf);
Integer pollIntervalInSeconds = 5;
Integer pollTimeoutInSeconds = 30;
List<GclReader> readers = t1cClient.getCore().pollReadersWithCards(pollIntervalInSeconds, pollTimeoutInSeconds);

The pollIntervalInSeconds expects an integer and denotes the interval between attempts to detect card-readers. A default value can be configured in the client configuration.

The pollTimeoutInSeconds expects an integer and denotes the total time during which the client should attempt to detect card-readers. A default value can be configured in the client configuration.

On success the function returns card-reader info (same response as in card-reader info).

Detect Reader with Inserted Card

A utility function in order to detect an inserted card. If a card is already inserted, the reader info, including card info will be send back as a response. The function verifies if there is a card-reader connected, and if so, return the first Reader object it finds with an inserted card. When a card-reader is connected and a card is detected, the info is send back as a response.

T1cClient t1cClient = new T1cClient(conf);
Integer pollIntervalInSeconds = 5;
Integer pollTimeoutInSeconds = 30;
GclReader reader = t1cClient.getCore().pollCardInserted(pollIntervalInSeconds, pollTimeoutInSeconds);

The pollIntervalInSeconds expects an integer and denotes the interval between attempts to detect card-readers. A default value can be configured in the client configuration.

The pollTimeoutInSeconds expects an integer and denotes the total time during which the client should attempt to detect card-readers. A default value can be configured in the client configuration.

On success the function returns card-reader info (same response as in card-reader info).

Certificate Management

In order to the GCL to operate on locale devices, a trust relation must be available between the requests/responses send to/from the distribution server. The T1C-JLIB is considered unsecured, and only serves as the application mediator between the GCL and the T1C-DS. Therefore JWT (JSON Web Tokens) are used to validate tokens in the context of a local device. The issued tokens are signed with the private key of the Distribution Service (T1C-DS).
During the initialization of a GCL instance, the T1C-JLIB will update the public key taking into consideration the targetted environment (development, acceptance, staging, production).
The api-key issued for a customer or application consumer is resovled with the necessary information.

Get GCL Public Key

In order to validate if a GCL instance has been successfully initialized, and contains a valid public key certificate. The following function can be called:

String base64PublicKey = t1cClient.getCore().getPubKey();

Update GCL Public Key

When the GCL is initially downloaded, it must be initialised with a valid public key. The GCL is distributed with a root CA and sub CA certificate. The public key must be issued by this root/sub authority in order to be valid.
The public key issues, is specific for the environment in which the GCL operates. When the apikey (used in order to initialize the T1C-JLIB lib) is issued for a development environment, a development public key will be requested in order to initialize the locale GCL instance.