Introduction

For initialisation of the T1C you need to prepare your application first by adding the SDK JS files to your project and importing them in such a way that you can call for the Javascript functions when you need them. When you've succesfully downloaded and installed the Trust1Connector you can initialize and use the Trust1Connector

Creating the configuration object

We will prepare the SDK's configuration Object, this object is used to pass information about which default port the Trust1Connector is running on, JWT key, API url, ... which is needed to properly contact and use the Trust1Connector.

When the Trust1Connector is configured with a Distribution Service in mind you can provide a valid JWT token in the configuration object. .

Now we can create a complete Configuration Options object to be passed to the Trust1Connector.

T1CConfigOptions

The T1C config options is a class that can be used to create a valid configuration object to initialize the Trust1Connector. Below you can find a class definition.

Parameters

t1cApiUrl: string Optional The URL that connects to the local Trust1Connector instances. This can be either localhost or a domain that directs towards localhost. By default this will be https://t1c.t1t.io

t1cApiPort: string Optional The port defined to be used for the Trust1Connector. By default this is 51983

t1cProxyUrl: string Optional - Deprecated The URL that connects to the local Trust1Connector Proxy instances. This can be either localhost or a domain that directs towards localhost. By default this will be https://t1c.t1t.io

t1cProxyPort: string Optional - Deprecated The port defined to be used for the Trust1Connector Proxy. By default this is 51983

jwt: string Optional The JWT token that is used to authenticate towards the Trust1Connector. This should be retrieved from the DS and is only needed when the Trust1Connector is configured to work with a DS and requires JWT validation

applicationDomain: string Optional The domain of the application that is using the Trust1Connector. This is used to make sure the consent is only available for a specific web-application. This prevents various clients to interfere with eachother. This domain also tags the Distribution service transactions being sent to the Distribution service. This makes it easy to distinguish between applications/tags for the transactions

When a remote DS is used you can set the following field with the correct DS url, this will in turn use the DS's capabilities of acting as a Trust1Connector proxy for enchanced security.

Now we can continue to use the config variable to and retrieve a T1CClient

Authenticated client

If you need to set up the Trust1Connector with a valid JWT token you can follow the documentation on the to from the DS.

When you have a valid token you can provide this in the Configuration. This will make sure the Trust1Connector is usable until the token becomes unvalid. At which point you can your token to continue to use the Trust1Connector. More information on how to retrieve,use and refresh a token can be found on the .

Initializing the Trust1Connector SDK

Initialization of the Trust1Connector in many cases requires a user consent, the exception being when no registry is configured (either local or central). More information can be found . The registry allowed us to create a Trust1Connector that works in any environment, without the need for Administrative rights from the users, wether it be Standalone, Multi session, RDP, Citrix, ...

To Initialize the Trust1Connector a is required(when a central or local registry is present). When no consent can be found the error codes 814500 or 814501 will be thrown. This means that either the previous consent is not valid anymore or no consent was given yet. More information regarding the consent can be found on the which explains it in more detail

When either no consent is present or its invalid you will receive a invalid client object (line 8 in example above) that can be used to trigger the getImplicitConsent function in the Core serivce.

The Consent requires a user action to . This data is used by the T1C registry to make sure you're targetting the correct instance of the Trust1Connector. More information about this can be found here.

The signature of the getImplicitConsent function is as follows;

This function expects:

codeword: string The string value that is saved to the user's clipboard needs to be sent to the Consent function.

durationInDays: number Optional Amount of days that the consent is valid.

callback: (error?: T1CLibException, data?: T1CClient) Optional Callback when you're not using ES

Below is a small javascript example of how you can trigger the getImplicitConsent function

After this you will have a client that can be used to execute the rest of the functionality that the Trust1Connector has to offer.

Full example

Clipboard

To provide a consent, we suggest you use the clipboard functionality available in browsers. The most supported way is via document.exeCommand and below you can find an example of this.

There is also a but this is not fully supported yet

Retrieve JWT token

GET https://ds.t1t.io/v3/tokens/application

This endpoint will return a valid JWT token to use for a certain period based on the API-key you provide in the `apikey` header

Headers

Introduction

The Belgian eID container facilitates communication with card readers with inserted Belgian eID smart card. The T1C-JS client library provides function to communicate with the smart card and facilitates integration into a web or native application. This document describes the functionality provided by the Belgian eID container on the T1C

Interface

Models

All model information can be found in the

Get Belgian eID container object

Initialise a Trust1Connector client:

Get the Belgian eID container service:

Call a function for the Belgian eID container:

Obtain the Reader-ID

The constructor for the Belgian eID expect as the parameter to be a valid reader-ID. A reader-ID can be obtained from the exposed core functionality, for more information see Core services responds with available card-readers, available card in a card-reader, etc. For example: In order to get all connected card-readers, with available cards:

This function call returns:

We notice that a card object is available in the response in the context of a detected reader. The reader in the example above is Bit4id miniLector, has no pin-pad capabilities, and there is a card detected with given ATR and description "Belgian eID Card". An ATR (Answer To Reset) identifies the type of a smart-card. The reader, has a unique ID, reader_id; this reader_id must be used in order to request functionalities for the Belgian eID card. This must be done upon instantiation of the Belgian eID container:

All methods for beid will use the selected reader - identified by the reader_id.

Cardholder Information

The card holder is the person identified using the Belgian eID card. It's important to note that all data must be validated in your backend. Data validation can be done using the appropriate certificate (public key).

Biometric data

Contains all card holder related data, excluding the card holder address and photo. The service can be called:

An example callback:

Response:

Address

Contains the card holder's address. The service can be called:

Response:

Picture

Contains the card holder's picture stored on the smart card. The service can be called:

Response:

Token info

The token info contains generic information about the card and it's capabilities. This information includes the serial number, file types for object directory files, algorithms implemented on the card, etc.

Response

Certificates

Exposes all the certificates publicly available on the smart card.

Root Certificate

Contains the 'root certificate' stored on the smart card. The root certificate is used to sign the 'citizen CA certificate'. When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not. The service can be called:

Response:

Authentication Certificate

Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding to the private RSA authentication key. The 'authentication certificate' is needed for pin validation and authentication. When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not The service can be called:

Response:

Intermediate Certificate (citizen)

Contains the citizen certificate stored on the smart card. The 'citizen certificate' is used to sign the 'authentication certificate' and the 'non-repudiation certificate'. When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not The service can be called:

Response:

Non-repudiation Certificate

Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key. When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not The service can be called:

Response:

Encryption Certificate (RRN)

Contains the 'encryption certificate' stored on the smart card. The 'encryption certificate' corresponds to the private key used to sign the 'biometric' and 'Address' data. When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not The service can be called:

Response:

Data Filter

Filter Card Holder Data

All data on the smart card can be dumped at once, or using a filter. In order to read all data at once:

Response:

The filter can be used to ask a list of custom data containers. For example, we want to read only the biometric data

Response:

Filter Certificates

All certificates on the smart card can be dumped at once, or using a filter. In order to read all certificates at once:

Response:

The filter can be used to ask a list of custom data containers. For example, we want to read only the rootCertificate

Response:

Sign Data

Algorithm

As the Beid module incorperates Beid 1.7 and 1.8 there is a difference in the algorithms being used. In 1.7 we have the following;

• md5

• sha1

• sha256

For beid 1.8 we have;

• sha2_256

• sha2_384

• sha2_512

As we've noticed most integrators use sha256 and to make sure current integrations do not break we have made the Trust1Connector to map sha256 to sha3_256 for beid 1.8. Ofcourse if you want to use a specifc supported algorithm you can still select them.

By default the 1.7 will fall back to sha256 and 1.8 to sha3_256 if an incompatible algorithm is passed to the function.

The tables below explain which algorithm will be used when providing a certain algorithm value in the function;

Belgian EID 1.7

Belgian EID 1.8

Signing

Data can be signed using the Belgian eID smart card. To do so, the T1C facilitates in:

• Retrieving the certificate chain (citizen-certificate, root-certificate and non-repudiation certificate)

• Perform a sign operation (private key stays on the smart card)

• Return the signed hash

To get the certificates necessary for signature validation in your back-end:

Response:

Depending on the connected smart card reader. A sign can be executed in 2 modes:

• Using a connected card reader with 'pin-pad' capabilities (keypad and display available)

• Using a connected card reader without 'pin-pad' capabilities (no keypad nor display available)

Security consideration: In order to sign a hash, security considerations prefer using a 'pin-pad'.

Signing with a Crelan card reader

When signing with a crelan card reader, it is additionally possible to optionally specify a transaction ID and the language. If the card reader is not a Crelan reader, these values will be ignored. This applies to all signing methods described below.

Sign Hash without pin-pad

When the web or native application is responsible for showing the password input, the following request is used to sign a given hash:

Response is a base64 encoded signed hash:

The 'authenticationreference' property can contain the following values: sha1, sha256, sha512, md5.

Sign Hash with pin-pad

When the pin entry is done on the pin-pad, the following request is used to sign a given hash:

Response is a base64 encoded signed hash:

The 'algorithm_reference' property can contain the following values: sha1, sha256, sha512, md5.

The core services lists connected readers, and if they have pin-pad capability. You can find more information in the Core Service documentation on how to verify card reader capabilities.

Bulk Signing

It is possible to bulk sign data without having to re-enter the PIN by adding an optional bulk parameter set to true to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with bulk being set to false is sent, or the method is called.

Bulk PIN Reset

The PIN set for bulk signing can be reset by calling this method.

Response will look like:

Calculate Hash

In order to calculate a hash from the data to sign, you need to know the algorithm you will use in order to sign.

You can use the following online tool to calculate the SHA256:

Hexadecimal result:

Notice that the length of the SHA256 is always the same. Now we need to convert the hexadecimal string to a base64-encoded string, another online tool can be used for this example:

Base64-encoded result:

Now we can sign the data:

Result:

Note: If you want to convert a binary signed hash to HEX (for development) you can use for example an online hexdump tool:

Verify PIN

Verify PIN without pin-pad

When the web or native application is responsible for showing the password input, the following request is used to verify a card holder PIN:

Response:

Verify PIN with pin-pad

When the pin entry is done on the pin-pad, the following request is used to verify a given PIN:

Response:

Verify PIN - retries left

In order to inform a user upon the PIN retries left, the Belgian eID doesn't provide a request to retrieve this information. After an unsuccessful PIN verification, the error code indicates the number of retries left. For example, when executing:

Note that, when the user has at least one retry left, entering a correct PIN resets the PIN retry status.

For more information about the error codes you can check the

Authentication

Algorithm

As the Beid module incorperates Beid 1.7 and 1.8 there is a difference in the algorithms being used. In 1.7 we have the following;

• md5

• sha1

• sha256

For beid 1.8 we have;

• sha2_256

• sha2_384

• sha2_512

As we've noticed most integrators use sha256 and to make sure current integrations do not break we have made the Trust1Connector to map sha256 to sha3_256 for beid 1.8. Ofcourse if you want to use a specifc supported algorithm you can still select them.

By default the 1.7 will fall back to sha256 and 1.8 to sha3_256 if an incompatible algorithm is passed to the function.

The tables below explain which algorithm will be used when providing a certain algorithm value in the function;

Belgian EID 1.7

Belgian EID 1.8

The T1C is able to authenticate a card holder based on a challenge. The challenge can be:

• provided by an external service

• provided by the smart card An authentication can be interpreted as a signature use case, the challenge is signed data, that can be validated in a back-end process.

  External Challenge

  An external challenge is provided in the data property of the following example:

Get valid algorithms to use for Sign or Authenticate

Via the Trust1Connector modules you are able to retrieve available algorithms to use for Signing or Authenticate

The response you can expect is a list of algorithms, an example can be found below (the values below are purely examplatory)

Introduction

Each lawyer in Belgium registered at the balie is obliged since 1/1/2018 to have an electronic lawyer card. This is declared in atr. 193bis of the :

“De advocaat moet voor zijn identificatie en voor de authenticatie beschikken over de elektronische CCBE-advocatenkaart.”

More info at .

Interface

Module

Models

All model information can be found in the

Examples

Initializing Diplad Module

All Data

Response will look like:

Biometric Data

Response will look like:

Picture

Response will look like:

All Certificates

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

Response will look like:

Root Certificate

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

Response will look like:

Authentication Certificate

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

Response will look like:

Non-Repudiation Certificate

When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

Response will look like:

Verify PIN

• If the card reader has a PIN pad, the PIN must always be entered via the card-reader PIN pad.

• If the card reader has no PIN pad:

  • If the osDialog property is set to true

Response will look like:

Sign

To sign data, an algorithm must be specified in the algorithm property (see ), and a Base64-encoded string representation of the digest bytes of the same algorithm in the data property.

Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional bulk parameter set to true to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with bulk being set to false is sent, or the method is called.

The PIN can provided/entered in the same way as

Response will look like:

Authenticate

To sign data, an algorithm must be specified in the algorithm property (see Supported Algorithms), and a Base64-encoded string representation of the digest bytes of the same algorithm in the data property.

The PIN can provided/entered in the same way as

Response will look like:

Get Supported Algorithms

Response will look like:

Bulk PIN Reset

The PIN set for bulk signing can be reset by calling this method.

Response will look like:

Introduction

The following page describes how you can integrate the Eherkenning module exposed on the Trust1Connector onto your web application.

Introduction

This page describes all generic payment models used.

Models

Introduction

This container supports functionality for EMV "chip and PIN" bank cards, including:

• VISA, MasterCard, Amex, CB and UK Post Office Account contact cards

• PayWave (VISA) and PayPass (MasterCard) contactless cards

Get EMV container object

Initialise a Trust1Connector:

Get the EMV service:

Call a function for the EMV container:

Obtain the Reader-ID

The constructor for the EMV expect as the parameter to be a valid reader-ID. A reader-ID can be obtained from the exposed core functionality, for more information see . Core services responds with available card-readers, available card in a card-reader, etc. For example: In order to get all connected card-readers, with available cards:

This function call returns:

We notice that a card object is available in the response in the context of a detected reader. The reader in the example above is VASCO DIGIPASS 870, has pin-pad capabilities, and there is a card detected with given ATR and some descriptions. An ATR (Answer To Reset) identifies the type of a smart-card. The reader, has a unique ID, reader_id; this reader_id must be used in order to request functionalities for the EMV card. This must be done upon instantiation of the EMV container:

All methods for emv will use the selected reader - identified by the reader_id.

Reading data

Applications

List the supported applications on the EMV card

An example callback:

Response:

Application data

The application data contains information of the holder of the card, the validity, the primary account number, ...

An example callback:

Response:

Issuer Public Key Certificate

On some applications there is an issuer public key certificate present. The aid parameter indicates which application you want to use, this can be fetched using the applications endpoint.

An example callback:

Response:

ICC Public Key Certificate

On some applications there is an icc public key certificate present. The aid parameter indicates which application you want to use, this can be fetched using the applications endpoint.

An example callback:

Response:

Verify PIN

Verify PIN without pin-pad

When the web or native application is responsible for showing the password input, the following request is used to verify a card holder PIN:

Response:

Verify PIN with pin-pad

When the pin entry is done on the pin-pad, the following request is used to verify a given PIN:

Response:

Verify PIN - retries left

After an unsuccessful PIN verification, the error code indicates the number of retries left. For example, when executing:

The following error message will be returned when PIN is wrong:

After a second wrong PIN verification:

Note that, when the user has at least one retry left, entering a correct PIN resets the PIN retry status.

Error Handling

Error Object

The functions specified are asynchronous and always need a callback function. The callback function will reply with a data object in case of success, or with an error object in case of an error. An example callback:

The error object returned:

For the error codes and description, see .

Introduction

The ReLo (Remote Loading) container is provided through the T1C (Trust1Connector) in order to provide a secured communication channel to executed APDU commands that are generated from a back-end service (which can be optionally signed by a HSM).

The ReLo provides smart card operations, like for example:

• open/close session

• execute APDUs (single or in bulk)

• retrieve card/card reader features

Communication Flow

The ReLo-API is an example back-end service implementing different smart card or token profiles (there is no limitation to smart cards). The T1V (Trust1Vault) is a Trust1Team product operating as a secured vault, and integrating with a HSM.

Available functions

The following functions are available in the library:

ReaderId

The readerId is passed to theremoteloading handler object on initialization. For example, opening a session on reader with idf56c0ffe15a07d09

Callback/Promise

All function return Promises by default.

If you prefer callbacks, each function also has an optional parameter to pass in a callback function. If a callback function is provided, the function will still return a promise, but the callback function will be called when the promise resolves/gets rejected.

SessionID is optional

For any function that accepts a sessionIdparameter, the parameter is optional. If a sessionId is provided, the corresponding session will be used for the request and then will be _kept open_once the request completes. This means that if this was the last request that needed to be made, the session needs to be explicitly closed with a call tocloseSession.

If no sessionId is provided, the request will still complete, but the GCL will set up a new session, perform the required action and then close the session. This means that there is _no open session_once the request completes.

When a wrong sessionID is sent in a request, an error message will be returned. The status code will be 'invalid sessionID' or 'no active session'

Interface

Objects

Detailed Function Overview

openSession

Opens a new session. Returns the sessionId, which will need to be stored by the client application for later use.

Interface

Parameters

• timeout (optional): session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.

Output

command

Sends a command to the reader for execution.

Interface

command(tx: string, sessionId?: string, callback: (error, data))

Parameters

• tx: command-string to be executed

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

ccid

Activates a specific CCID feature if it is available on the reader

Interface

ccid(feature: string, command: string, sessionId?: string, callback?: (error, data))

Parameters

• feature: feature to check

• command: command to send to the ccid reader (hex format)

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

closeSession

Closes currently open session.

Interface

closeSession(callback?: (error, data))

Parameters

• none

Output

isPresent

Checks if the card for this session is still present.

If no sessionId is provided, checks if a card is present in the reader.

Interface

isPresent(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

atr

Retrieves the ATR for the card currently in the reader.

Interface

atr(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

ccidFeatures

Returns a list of available CCID features for the current reader.

Interface

ccidFeatures(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

apdu

Executes an APDU call on the current reader. The difference with the commandfunction is that theapdu function takes an APDU object, whereas commandtakes a string.

Interface

apdu(apdu: ApduObject, sessionId?: string, callback?: (error, data))

Parameters

• apdu: object containing the APDU to be executed

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

APDU Object interface:

Output

Bulk Actions

For the apduand commandfunctions, it is possible to send an array of apdu's/commands.

apdus (bulk)

Executes an array of APDU calls on the current reader.

Interface

apdus(apdu: ApduObject[], sessionId?: string, callback?: (error, data))

Parameters

• apdu: array containing the APDU objects to be executed

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

APDU Object interface:

Output

commands (bulk)

Executes an array of commands on the current reader.

Interface

commands(tx: string[], sessionId?: string, callback?: (error, data))

Parameters

• tx

  : array containing the command strings to be executed

• sessionId

  (optional)

  : sessionId to use. Required if the session needs to be kept open after the request completes.

Output

A Word of Introduction

The Trust1Connector Javascript SDK is a library that purely functions as a proxy towards the Trust1Connector API. This Library does not contain any business logic.

Architecture Overview

The following schematic seems rather complicated as it explains the inner workings of the Trust1Connector components, the concept is elaborate further on this page. If you are only interested in what the integration impact is for your Web Application in a Shared Environment, you can skip directly to the section: Integration in Web Applications

Components

Web Environment

The Web Application can use the T1C-SDK-JS or a custom REST API client for integration purpose. As the Web Application operates in a browser context, resolving an agent, by means of a consent, will result in a browser cookie being provided.

The T1C-SDK-JS implements the detection of a Shared Environment during the initialisation of the library. When initialisation succeeds without a controlled exception, the setup is a standalone; when the initialisation throws an 401 Error, the T1C-SDK-JS can be used to request the user for a Consent.

When using the REST API directly form your web application, reading the browser cookie and performing the initialisation must be done by the integrating Web Application itself.

Shared Environment Host

Compared to Trust1Connector v2, the v3 release has a separate component to be be installed on a shared host. This component is called the T1C-Proxy and only exposes the following use cases:

• Verify random available ports [in a predefined range] which can be used by an Agent (Session of T1C-API running in user space)

• Port reservation upon installation of a new T1C-API in an active user session

• Port registration upon initialisation of a T1C-API in an active user session

The T1C-Proxy operates by Default on the API port defined in the T1C-DS (Distribution Server). From a Web Application perspective, this is the only information known. When a Web Application requests the information of the device, the PROXY device type will inform the Web Application that the targeted underlying API is a PROXY, which means that the Web Application must ask for the Agent specific API port to configure an URI which can be used to execute the use cases.

When using the T1C-SDK-JS this is done implicitly during initialisation.

Shared Environment Client

A T1C-API installed for a specific users runs in [User Space]. To avoid possible attack vectors, the Trust1Connector v3 will always run in [User Space].

Upon installation of the T1C-API, during the post install phase, the T1C-API will try to verify automatically if it is running in a shared environment. If this is the case, the T1C-API will ask the T1C-Proxy for available ports and will reserve those post, prior to initialisation and startup.

The ports which are reserved by the T1C-Proxy are the following:

• T1C-API Port: This is the port exposing the OpenAPI interface towards Web Applications and used by the T1C-SDK-JS

When receiving ports during post-install, an user agent device is temporary RESERVED in the Agent Registry of the T1C-Proxy. Upon T1C-API initialisation, the port configurations will be confirmed and the Agent Registry will set the device state on REGISTERED. From this moment on, a T1C-API instance, running in an active user session, will be available for the Web Application via the .

The T1C-gRPC instance is inherently a component from the T1C-API, and thus is managed by the T1C-API. As each user must have it's own hardened runtime for communication purpose, the port assigned for T1C-gRPC will be registered and configured by the T1C-API (and restarted when needed).

Central Back-Office

Starting from this release (v3) of the Trust1Connector, each device must have a link with an active and running T1C-DS (Trust1Connector Distribution Server). This is to guarantee security, updates, and avoid potential risk in production.

The T1C-DS is proceeded by an API Gateway who is managing the security offloading in the application layer. For a Web Application to communicate with a T1C-Proxy or T1C-API, a JWT (Json Web Token) is needed and obliged. The T1C-DS is responsible for the key management, the certificate management and other use cases which are described in a separate wiki.

In order to retrieve a valid JWT, the T1C-DS can be requested from your application back-end with a valid api-key. The JWT is valid for a given amount of time, and sets the context used when requesting the T1C-API on a device.

Security

Pin Handling

The PIN handling logic is implemented in the Trust1Connector API. More information on the basic and/or advanced rules can be found on the following link:

Share Environment Flows

Communication Stack

Include Trust1Connector JS SDK

Include the Trust1Connector JavaScript SDK on your web application. This will provide you with access to the SDK's functions which are used to execute the Trust1Connector's functionality.

From now on we will refer to the Trust1Connector JS SDK to the following variances;

• T1C-js/t1cjs

• T1C SDK

Using Trust1Connector in as a library

The Trust1Connector is a Javascript Library with TypeScript typings. This can be easily used in any web-application by loading the javacript files on the web-page.

Loading the T1C SDK onto a web-page can be done as shown in the code example below of a html page

In the example you can see that we load the Javascript SDK on line 8

The defer attribute means that the script will be downloaded in parallel with the rest of the web-page but will be executed when the page has finished loading in.

This is mostly used to make sure that when the Javascript wants to target a specific element on the page, for example a div, that this element has already been loaded and is accessable.

Using Trust1Connector as a module

We also provide an npm package that makes it easier to load and use the Trust1Connector Javascript SDK as a module.

You can find the trust1connector JS SDK for the Trust1Connector v3 via NPM

You can also find the source code here

Release notes - Trust1Connector - Version T1C-sdk-js-3.5.5

Story

• As an integrator I want to retrieve a consent value from the Javascript SDK

• As a Integrator I would like to use a central registry hosted on the DS

Release notes - Trust1Connector - Version T1C-sdk-js-3.5.4

Bug

• Trust1Connector JavaScript SDK removes the consent when the validate returns a response where an extra consent is required.

Story

• Trust1Connector should be able to provide organization context when not requiring application tokens

Release notes - Trust1Connector - Version T1C-JS-v3.5.3

Story

• Support Citrix multi-host session management for consent flow

Release notes - Trust1Connector - Version T1C-JS-v3.5.1

Bug

• Issue with pinEncryption when version is not found, stops the flow

• JS SDK for T1C v3.5 attempts to reset bulk PIN by POST request instead of GET

Release notes - Trust1Connector - Version T1C-JS-v3.5.0

Bug

• File exchange relative path for download does not handle all cases

• Download does not correctly build the relative path

Story

• As an Integrator I want to provide a timeout for the dialogs

• Migrate to Rust Jcop

• Safenet rustification

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC7

Story

• Remote registry implementation

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC6

Bug

• File exchange relative path for download does not handle all cases

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC5

Story

• As an Integrator I want to provide a timeout for the dialogs

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC4

Bug

• Download does not correctly build the relative path

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC3

Bug

• Javascript semver check doesn't handle beta and RC versions

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC2

Story

• Migrate to Rust Jcop

• Safenet rustification

• eHerkenning rustification

Release notes - Trust1Connector - Version T1C-JS-v3.5.0-RC1

Story

• Implement new architecture for shared environment, multi session host, single installation, ...

Release notes - Trust1Connector - Version T1C-JS-v3.4.2

Bug

• Check correct versions for backwards compatibility

Release notes - Trust1Connector - Version T1C-JS-v3.4.1

Story

• Pin Obfuscation not working for all modules

• base64 encode the PIN before sending it to the API

Release notes - Trust1Connector - Version T1C-JS-v3.4.1-RC3

Story

• Pin Obfuscation not working for all modules

Release notes - Trust1Connector - Version T1C-JS-v3.4.1-RC2

Story

• base64 encode the PIN before sending it to the API

Release notes - Trust1Connector - Version T1C-JS-v3.4.0

Story

• I want to enable module for Certinomis

• Migrate certigna integration with the latest token

Release notes - Trust1Connector - Version T1C-JS-v3.3.0

Bug

• Return interface to previous state to prevent breaking applications

Release notes - Trust1Connector - Version T1C-JS-v3.2.13

Bug

• Pkcs11 module and os dialog return decryption error

• Update certificate model to correctly handle multiple certificates

Release notes - Trust1Connector - Version T1C-JS-v3.2.12

Bug

• Device-key endpoint gets called in error handler instead of successhandler

Release notes - Trust1Connector - Version T1C-JS-v3.2.11

Bug

• File-exchange ArrayBuffer should be Blob

Release notes - Trust1Connector - Version T1C-JS-v3.2.10

Bug

• Initialising with invalid JWT does not throw an error

Release notes - Trust1Connector - Version T1C-JS-v3.2.9

Bug

• Entity and type response object inconsistency

• Remoteloading split TX, RX and SW value based on APDU response

Story

• Use Device certificate to encrypt the pin value sent in clear text

• I want to enable the module for eHerkenning

• I want to enable module for Print Writer

Release notes - Trust1Connector - Version T1C-JS-v3.2.8

Bug

• Aventra, Idemia, Oberthur callback functions not being triggered

• FileExchange typing inconsistency

Story

• Add LuxeID to the token generic interface in JS SDK

Release notes - Trust1Connector - Version T1C-JS-v3.2.7

Bug

• Fix imports for Pkijs

Story

• Disbable implicit any typing

Release notes - Trust1Connector - Version T1C-JS-v3.2.6

Bug

• Fix for bulk sign reset in JS SDK causes the reader ID not to be included in certificate retrieval

Release notes - Trust1Connector - Version T1C-JS-v3.2.5

Improvement

• Provide separate implementation for Belgian eID with Crelan reader

Trust1Connector API DNS

The Trust1Connector API v3 exposes a secure REST API on the client device. Trust1Team has created a t1c.t1t.io DNS entry (or customer-specific DNS entry) that points to 127.0.0.1 in order to facilitate SSL communication. This means that if the customer infrastructure uses a proxy for all network traffic, an exemption must be made for t1c.t1t.io to always point to the origin device's loopback address.

If no exemption is made and https://t1c.t1t.io is handled by a proxy, it will redirect to 127.0.0.1 IP of the proxy server instead of the local machine, and the Trust1Connector API will be unreachable.

The reserved domain from Trust1Team has been registered with DNSSEC on the aforementioned URI. When a PARTNER uses its own DNS, we strongly recommend applying DNSSEC on the domain used in production.

Applications using the Trust1Connector

Applications that want to make use of the Trust1Connector will be run from a specific domain. This means that the Trust1Connector needs to know that certain domains/applications want to make use of the Trust1Connector's functionality.

For these applications to gain access to the Trust1Connectors API we need to whitelist the domain in whats called the cors list. This list contains all the accepted domains that can make use of the Trust1Connector.

Distribution Service

In order to correctly function, the Trust1Connector API must be able to connect to its configured Distribution Service. You must allow REST traffic to the following URLs (if applicable):

• Acceptance: https://acc-ds.t1t.io

• Production: https://ds.t1t.io

A partner can opt for its own Distribution server, whereas the URIs mentioned above, will be defined by the hosting party.

The option of working without Distribution Service is also possible. You can find all the possibilities to run the Trust1Connector here

Disk Space

Windows

Trust1Connector installer is about 15-20Mb in size. The installed size comes to 35-45Mb.

This includes the Trust1Connector API, Registry and Sandbox.

MacOS

Trust1Connector installer is about 15-20Mb in size. The installed size comes to 40-50Mb.

This includes the Trust1Connector API, Registry and Sandbox.

The increased size over windows mainly comes to the way MacOS handles dialogs. These are distributed with the Trust1Connector as seperate binaries.

API Key

All endpoints of the Trust1Connector API are secured and require a JWT to access. To obtain a token, an .

This API key must be requested from TRUST1TEAM, or created by the customer if they are hosting their own Distribution Service. The API key must never be used in a front-end application (where the API key can be compromised). The API key is needed to exchange the token, using a Distribution Server, resulting in a short-lived Json Web Token.

A PARTNER can decide to distribute a version without the use of a JWT. In those cases, the liability of the security flow resides completely in the context of the web application, thus Trust1Team can not guarantee the security context where the Trust1Connector is integrated upon.

Operating System

Right now Trust1Connector support two operating systems;

• MacOS 10.13 or higher

  • X86 architecture

  • M1/ARM architecture

Trust1Team support Windows/Mac OSX OS families where lifecycle support is guaranteed from the Vendor of the Operating System. The moment the OS version has been marked as ‘end of life’, Trust1Team can not guarantee the functionality anymore.

When PARTNERS are in need to support an older version or keeping the support running on the level of Trust1Team, no guarantees can be made. Trust1Team can setup a custom project, on demand of the PARTNER. Those requirements, changes or other adaptations needed, are not covered in the Trust1Connector license fee.

Windows 8.1 or higher

To run in user-space on Windows 8.1 or higher some components have to be set on the operating system

Registry keys

Below you can find a list of all registry keys that will be created for the working of the Trust1Connector, All these keys are added to HKCU

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

HKEY_CURRENT_USER\SOFTWARE\Trust1Team\Trust1Connector

Cookies

Since 3.5.x no more cookies are used.

Browsers

The Trust1Connector is browser agnostic so it does not matter what browser is being used as long as it support HTTP communication (HTTP 1.1) (which should all of them).

Version wise we do recommend to use the latest versions of your browser for security reasons but the versions below is was we accept as a minimum

• Chrome >80

• Firefox >75

• Edge 88 or higher

Downloading Trust1Connector

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 analyse 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 macosarm.

2. /v3/downloads/installers/{{OS}}/versions/{{version}}

Differentiate between MacOS architectures

For MacOS there are currently 2 supported architectures:

• ARM64 (M1, ...)

• Intel x86_64

Currently, browsers etc do not display which architecture you're running. So in order to provide download links to the users you need to provide them with the option to download any of the 2 architectures. The user needs to decide which platform he is running.

From the DS you can get both links with the following URL's (Production DS is used in the example);

After this, you can provide the user with the choice of which one they want to download. Below you can see an example of how Google does this with their Browser, Google Chrome.

Here you can clearly see they provide two versions, with a recommendation on Intel because the majority of the users still run Intel Apple devices

Distribution services

Below you can find a list of Distribuction services available from Trust1Team. If you are integrating with a 3rd party that uses the Trust1Connector you can contact them for information regarding the Distribution services.

Introduction

The Trust1Connector after correct initialization has the ability to retrieve the available card readers detected on the system. With these card readers you can continue and execute functionality such as retrieving biometric information, signing data, authentication, ...

Below you can find more information on how to retrieve the available readers. All these functions are available in the Core Service

List card readers

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

The response will contains a list of card readers:

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.

In the response below you notice that this specific card also includes a module and description property. Both of these are arrays and are also optional. This means that the Trust1Connector recognizes this specific token and knows which module can be used for this token. The Trust1Connector has the possibility to detect that a card can be used by more than 1 module, in that case the module array will display multiple values depicting which modules can be used. The description is purely metadata.

Pin-Pad Capabilities

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

List Card-Readers - Explained Example

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

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

Get card readers 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.

Response: