# 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&#x20;

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 with a correct token in order to access the all resource. The security policy for `Trust1Connector` v3 secured ALL endpoints.

### Administration resources

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

* Download `Trust1Connector` installer
* Get Information of the device and user context
* Register T1C for device
* Update T1C on device (install new version)
* Update DS (distribution server) metadata
* Increment use case counter

Executing these functionality is explained further.

### 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
* List modules
* Get module
* Get card-reader
* Get card-reader with cards inserted
* Get card-readers without card
* Get consent (needed for shared environments)
* Detect card for card-reader (polling utility resource)
* Detect any card (polling utility resource)
* Detect card-readers (polling utility resource)
* Browser Information (utility resource)

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, ...

### Initialize the client library

The client can be initialized by passing a `T1CConfig` object in the constructor

```javascript
config = new T1CSdk.T1CConfig(configoptions);
T1CSdk.T1CClient.initialize(config).then(res => {
    client = res;
    console.log("Client config: ", client.localConfig)
    core = client.core();

}, err => {
    if (err.code == 500) {
        console.log(err)
        client = err.client
        $('#consentModal').modal('show', {
            keyboard: false
        });
        $('.consent-token').text(makeid(20));
    } else if (err.code == 115) {
        $('.consent-token').text(makeid(20));
    } else if (err.code == 199) {
        document.querySelector("#initAlert").classList.remove("d-none")
        document.querySelector("#initAlert").innerHTML = err.description;
    } else {
        console.error("T1C error:", err)
    }
});
```

### List card readers

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

```javascript
T1CClient.initialize(config).then(res => {
    var coreService = res.core();
    core.readers(callback);
})
```

The response will contains a list of card readers:

```javascript
{
  "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:

```javascript
{
  "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 (**A**nwser **T**o **R**eset), is the response from any smart-card when powered, and defines the card type.\
The `Trust1Connector` recognized more than 3k smart-card types.

```javascript
{
  "data": [
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    }
  ],
  "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 `pinpad`property):

```javascript
{
  "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:

```javascript
{
  "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.

```javascript
GCLClient.initialize(config, function(err, client) {
    var coreService = client.core();
    core.readersCardAvailable(callback);
});
```

Response:

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

### Download T1C Installer

The T1C JS SDK no longer has a method to download the T1C installer.

Instead, the T1C installer can be downloaded by navigating the client browser to the `/v3/downloads/installer` endpoint of the Distribution Service (e.g. `https://acc-ds.t1t.io/v3/downloads/installer`). The Distribution Service will analyze the `User-Agent` header and automatically initiate the download of an OS-appropriate installer of the latest configured version. The user agent string parsing is considered "best-effort"; as they can vary wildly depending OS and browser software.

Alternatively, you can also initiate the download of a T1C installer with the following endpoints:

1. `/v3/downloads/installers/{{OS}}`: This endpoint allows you to specify the OS for which you wish to obtain an installer. The possible values are `win32`, `win64`, `unix`, `macos`.&#x20;
2. `/v3/downloads/installers/{{OS}}/versions/{{version}}`: This endpoint allows you to download a specific version of a T1C installer for a specific OS.

### Get Information

