v3.8.x

Initialisation

Description of how to initialise the T1C via API

Introduction

The Trust1Connector is a program that has 3 components that function together to create a coherent experience to interact with hardware readers and cards.

  • API

  • Registry

  • Sandbox

API

The API component is the main communication channel. This is used to ask information from a specific hardware device or send specific commands.

Registry

The Registry component is one that is available for each system. This takes care of keeping multiple API components active and available on the system.

Users can communicate with the registry to retrieve the correct configuration which holds information such as the TCP port to be used to contact the correct API.

This components is crucial to support multi-user environments such as Citrix, terminal server, RDP, ...

Sandbox

The sanbox is a component that takes care of all the lower level communication with the hardware components. The sandbox is directly used and managed by the API.

initialisation flow

Initialising the Trust1Connector can be done by following the flow described in the picture below

Check local consents

The first step in the initialisation is to check if the browser/user already has a consent present.

Based on this information we know if we either have to call for a new consent or just validate if the existing consent is correct and usable.

Local consent present

If we already have a consent present in the user's local storage we can ask the registry to validate them before we actually use them.

To validate your consents you can give them with the Validate endpoint as described below

Validate existing consents

POST https://t1c.t1t.io:51983/v3/validate

Validate existing consents to check if they have not exceeded the validity and if they are targetting the correct config.

Headers

NameTypeDescription

X-CSRF-Token*

String

t1c-js

Content-Type*

String

application/json

Request Body

NameTypeDescription

consents*

Array

Array of already existing consents

{
    "success": true,
    "data": {
        "consents": [
            "eyJhZ2VudCI6eyJ1c2VybmFtZSI6Im1pY2hhbGxpc3Bhc2hpZGlzIiwiaG9zdG5hbWUiOiJNaWNoYWxsaXNzLU1hYy1Qcm8ubG9jYWwiLCJhcGlJcCI6InQxYy50MXQuaW8iLCJhcGlQb3J0IjoiNTUwMDAiLCJhcGlQaWQiOiIxMDM0NiIsInNhbmRib3hJcCI6ImxvY2FsaG9zdCIsInNhbmRib3hQb3J0IjoiNTYwMDAiLCJzYW5kYm94UGlkIjoiMTA5NTciLCJhcGlMYXN0VXNlZCI6IjIwMjEtMTEtMDQgMDI6MDM6MTguMjAwNzUwIFVUQyIsImNsaWVudExhc3RVc2VkIjoiMjAyMS0xMS0wNCAwMjowMzoxOC4yNTEzNTYgVVRDIiwidmFsaWRpdHlJbkRheXMiOiIzNjUiLCJjb25uZWN0aW9uU3RhdGUiOiJDT05TRU5UIn0sInNpZ25lZEhhc2giOiIwK2krUlJsVHEwTlNGWEdyNVZLVXZWZ1lDQTA0SFNvNkh4OG5GRmN4SWUwPSJ9"
        ],
        "consentState": "REQUIRED"
    }
}

This endpoint will either return with consentState APPROVED or REQUIRED. Keep in mind it will always return the active list of consents you need to keep in your local list of consents.

Local consent not present or consent is required

If you do not have any consents locally or the Validate returned with REQUIRED you will have to provide a new consent.

To provide a consent you will need to create a randomised string value and let the user put this on his/her clipboard. You can do this via a JavaScript call that is triggered behind a button in the user interface.

After this is done you can now execute the consent endpoint providing the randomised string that is put on the user's clipboard as body data.

Ask for a new consent

POST https://t1c.t1t.io:51983/v3/consent

Based upon a random string on the user's clipboard we want to receive a new, valid consent.

Headers

NameTypeDescription

X-CSRF-Token*

String

t1c-js

Content-Type*

String

application/json

Request Body

NameTypeDescription

codeWord*

Strig

Codeword that was placed on the user's clipboard

If a users gets the consent required message after trying more then 2 times this means that the registry could not find that specific instance of the user.

This could indicate that this user does not have the Trust1Connector running or the value was not placed on his clipboard.

When the consent was successfull we store the list of consents in the local storage (for next time) and use the consent value to retrieve our configuration.

Parse the active consent

When either the validate or consent methods return succesfully we can use the consent property, which is the active consent to retrieve our configuration properties.

This includes the agent username, hostname, pid, sandbox information,...

but most importantly this holds the apiPort property which is the actively running port of the user's Trust1Connector API.

To retrieve this information we need to parse the active consent which is a base64 encoded JSON object.

The original value looks like this;

eyJhZ2VudCI6eyJ1c2VybmFtZSI6ImdpbGxlcyIsImhvc3RuYW1lIjoiR2lsbGVzcy1pTWFjLVByby5sb2NhbCIsImFwaUlwIjoibG9jYWxob3N0IiwiYXBpUG9ydCI6IjU1MDAxIiwiYXBpUGlkIjoiOTQxNjAiLCJzYW5kYm94SXAiOiJsb2NhbGhvc3QiLCJzYW5kYm94UG9ydCI6IjU2MDAxIiwic2FuZGJveFBpZCI6Ijk0MTY1IiwiYXBpTGFzdFVzZWQiOiIyMDIxLTExLTIyIDE3OjIyOjAzLjUwMTk3MCBVVEMiLCJjbGllbnRMYXN0VXNlZCI6IjIwMjEtMTEtMjIgMTc6MjI6MTUuOTYzNzgzIFVUQyIsInZhbGlkaXR5SW5EYXlzIjoiMzY1IiwiY29ubmVjdGlvblN0YXRlIjoiT05MSU5FIn0sInNpZ25lZEhhc2giOiJIWXNyK04zZXpLYnc0MnVSbXg5TEV5Smwza0RCajU4UWVXRndLWFd0VHRrPSJ9

After base64 decoding you will receive a JSON object which looks like this;

{
  "agent": {
    "username": "gilles",
    "hostname": "Gilless-iMac-Pro.local",
    "apiIp": "localhost",
    "apiPort": "55001",
    "apiPid": "94160",
    "sandboxIp": "localhost",
    "sandboxPort": "56001",
    "sandboxPid": "94165",
    "apiLastUsed": "2021-11-22 17:22:03.501970 UTC",
    "clientLastUsed": "2021-11-22 17:22:15.963783 UTC",
    "validityInDays": "365",
    "connectionState": "ONLINE"
  },
  "signedHash": "HYsr+N3ezKbw42uRmx9LEyJl3kDBj58QeWFwKXWtTtk="
}

With this information we can now use the apiPort contact the API directly and the initialisation of the Trust1Connector is finished.

The endpoint below is contacting the Trust1Connector API with the correct apiPort

Get the information of the Device

GET https://t1c.t1t.io:55001/info

Retrieve the Trust1Connector API info

{
    "t1CInfoOS": {
        "architecture": "x86_64",
        "platform": "Mac OS",
        "family": "unix",
        "os": "macos",
        "version": "macOS 12.0.1"
    },
    "t1CInfoRuntime": {
        "runtime": "rust",
        "desktop": "Aqua",
        "version": "1.56.1",
        "dateTime": "2021-11-30 10:37:28.706574 UTC"
    },
    "t1CInfoUser": {
        "name": "Gilles Platteeuw",
        "username": "gilles",
        "timezone": "UTC",
        "home": "/Users/gilles",
        "tempdir": "/var/folders/8d/hj_msvfj0153fspzywcsjwhm0000gn/T/",
        "installedDir": "/Users/gilles/_git/t1c-rust-api"
    },
    "t1CInfoAPI": {
        "service": {
            "deviceType": "DEVICE"
        },
        "activated": true,
        "status": "ACTIVATED",
        "environment": "prod",
        "uid": "7f69259cea22435b4b793a4e9918d3016321c9e44e37f61a839cd5ed1c2844ae",
        "modules": [
            "readers",
            "airbus",
            "crelan",
            "certigna",
            "eherkenning",
            "dialogs",
            "beid",
            "remoteloading",
            "luxtrust",
            "jcop3",
            "wacom",
            "print",
            "safenet",
            "pkcs11",
            "emv",
            "chambersign",
            "luxid",
            "certinomis",
            "fileexchange"
        ],
        "cors": [
            "localhost",
            "*.t1t.io"
        ],
        "version": "3.5.12",
        "logLevel": "INFO"
    }
}
PreviousFile Exchange APINextRegistry as a service (example)