Core Service

Introduction

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

• interface for web/native applications using JavaScrip/Typescript

• REST API as a new approach and to incorporate the Trust1Connector as a microservice in the application architecture

In this guide, we target only the use of Trust1Connector's core interface for web/native applications. The T1C-SDK-JS exposes protected resources for administration and consumer usage.

The JavaScript library must be initialized correctly in order to access the all resource.

Consumer resources

Consumer resources are typically used from an application perspective:

• Get pub-key certificate

• Get version

• Get Information (operating system, runtime, user context, variable configuration)

• List card-readers (with active card)

• Get card-reader

• List card-readers (with active cards)

• List card-readers (with or without active card)

• Trigger a push of the log files towards the DS

Executing these functionality is explained further.

Core Functionalities

The Trust1Connector functionalities are about secured communication with device hardware. The document highlights communication with smart card readers - contact and contact-less. Other hardware devices can be enabled or integrated as well in the solution. Some of the already are, for example printer drivers, signature tablet drivers, ...

After you've initialized the Trust1Connector you can execute the rest of the Trust1Connector's functionality, for example listing the readers and fetching information from a specific smart card.

List card readers

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

T1CSdk.T1CClient.initialize(config).then(res => {
    var coreService = res.core();
    core.readers(callback);
}, err => {
    console.error(err);
});)

The response will contains a list of card readers:

{
  "success": true,
  "data": [
    {
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false,
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card (eID)"
        ],
        "module": "beid"
      }
    }
  ]
}

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

{
  "data": [
    {
      "id": "ec3109c84ee9eeb5",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
      "pinpad": false
    },
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    },
    {
      "id": "c8d31f8fed44d952",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
      "pinpad": false
    }
  ],
  "success": true
}

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.

{
  "data": [
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    }
  ],
  "success": true
}

Excluded by name

Possibility to exclude certain readers based on their name

This exclude readers will search for the term in the reader names and exclude those that match with the term

core.readersExcludeByName("Bit4id", callback);

{
  "data": [
  ],
  "success": true
}

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

{
  "data": [
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    }
  ],
  "success": true
}

List Card-Readers - Explained Example

The following example is the response for List card-readers on a device with 4 different card-readers attached:

{
  "data": [
    {
      "id": "ec3109c84ee9eeb5",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
      "pinpad": false
    },
    {
      "card": {
        "atr": "3B67000000000000009000",
        "description": [
          "MisterCash & Proton card",
          "VISA Card (emitted by Bank Card Company - Belgium)"
        ]
      },
      "id": "e5863fcc71478871",
      "name": "Gemalto Ezio Shield Secure Channel",
      "pinpad": true
    },
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    },
    {
      "id": "c8d31f8fed44d952",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
      "pinpad": false
    }
  ],
  "success": true
}

In the above example you notice that 4 card-readers are connected. Each card-reader receives his temporary id which can be used for other functions where a card-reader id is needed. This method can be requested in order to list all available card-readers, and optional cards-inserted. Each card-reader has a vendor provided name, which is retrieved from the card-reader itself. An additional property pinpad, a boolean value, denotes if the card-reader has pin-pad capabilities. A pin-pad is a card-reader, most of the times with its own display and key-pad. From a security perspective, it's considered best practice to use as much as possible pin-pad capabilities of a pin-pad card-reader. When a reader has a smart-card inserted (contact interface) or detected (contactless interface), the card type will be resolved by the GCL in order to respond with a meaningful type. In the above examples you see that; one card-reader has a Belgian eID card; another card-reader has a MisterCash or VISA Card available for interaction.

The readers returned, are the card-readers with a card available. The card-readers where no card is presented, are ignored.

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 reader_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 JSON response.

T1CClient.initialize(config).then(client => {
    var coreService = client.core();
    core.readersCardAvailable(callback);
}, err => {
    console.error(err);
});

Response:

{
  "data": [
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": []
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    }
  ],
  "success": true
}

Get the Javascript SDK version

To retrieve the version of the Javascript SDK you can use the version function available in the CoreService

You can follow the example below to retrieve the version number

T1CSdk.T1CClient.initialize(config).then(client => {
    var coreService = client.core();
    core.version().then(version => {
        console.log(version)
    });
}, err => {
    console.error(err);
});

The ouput in the log of the code above should look like the following

3.5.3

Get device public key

via the getDevicePublicKey endpoint you're able to fetch the public key information of the device. This requires an authenticated client to be able to access this endpoint.

This endpoint is used in the library to encrypt pin, puk and pace information so that it is not exposed in the network logs of the browser.

Encryption of pin, puk and pace is only possible when the Trust1Connector is registered via a DS and has a valid device key-pair. The SDK will automatically switch to send the pin, puk or pace info in clear text if its not able to encrypt. The Trust1Connector API will also detect if it has no valid device key-pair it will not try to decrypt the incoming pin, puk or pace information.

Push log files

Via the pushLogs function you can trigger the Trust1Connector to send out the log files towards the Distribution service.

Core interface

export interface AbstractCore {
  getImplicitConsent(codeWord: string, durationInDays?: number, callback?: (error?: T1CLibException, data?: T1CClient) => void): Promise<T1CClient>;
  validateConsent(consent: string, callback?: (error?: T1CLibException, data?: T1CClient) => void): Promise<T1CClient>;
  updateJWT(jwt: string, callback?: (error: T1CLibException, data?: T1CClient) => void): Promise<T1CClient>
  info(callback?: (error: T1CLibException, data: InfoResponse) => void): void | Promise<InfoResponse>;
  reader(reader_id: string, callback?: (error: T1CLibException, data: SingleReaderResponse) => void): Promise<SingleReaderResponse>;
  readers(callback?: (error: T1CLibException, data: CardReadersResponse) => void): Promise<CardReadersResponse>;
  readersCardAvailable(callback?: (error: T1CLibException, data: CardReadersResponse) => void): Promise<CardReadersResponse>;
  readersExcludedByName(name: string, callback?: (error: T1CLibException, data: CardReadersResponse) => void): Promise<CardReadersResponse>;
  readersCardsUnavailable(callback?: (error: T1CLibException, data: CardReadersResponse) => void): Promise<CardReadersResponse>;
  getUrl(): string;
  getDevicePublicKey(): void;
  dsCorsSync(): Promise<boolean>;
  pushLogs(): Promise<boolean>;
  version(): Promise<string>;
}