A Word of Introduction

The Trust1Connector is a technical product that aims to make all hardware tokens, used for authentication and digital signing, interoperable in a web environment. No operating system dependencies to take into account, no browser dependencies, and compatible with smart-card readers, contactless readers and pin-pad readers/terminals.

Our mission is straight forward our focus is to enable secured communication, from a web application, to a desktop device, in the world of person identity, mainly for the following use cases:

• Read token information (personal info, ICAO, ...)

• Read certificates, certificate chains or certificate information

• Verify a known password (PIN, PUK, CAN, ...)

• Authenticate using a hash

• Digitally sign a hash

Our mission is to add all token profiles we find in B2C and B2B, government, banking, insurance, health, ...

This library is an SDK meant for fast integration in a web application. We promote although the use of the REST API. After installation of the middleware, from an application perspective, you can consume the functionalities as you do with other microservices. The application will need any REST client, in any language to enable all card communication functionalities.

As the connector exists for more than 5 years, Trust1Team decided to enhance the design, security, functionalities, ... and to incorporate all feedback of existing partners into the Trust1Connector v3.

The library has evolved as a technology product for smart card communication to a framework of secured communication from a browser to any hardware device. In our eco-system we have implemented communication to various printers, signature tablets, biometric devices etc.

During the years, the Trust1Connector has evolved from a product to be installed on standalone dekstops to a product which can be used on shared environments such as Citrix, XenApp, ...

In order to guarantee secured communication, former versions needed a user to have administrator rights during the installation. From this release on, the solution runs completely in user space, sandboxed and hardened. No user data is compromised and thus the solution is GDPR compliant.

Characteristics of Trust1Connector

The following list describes the characteristics of the Trust1Connector:

• Browser independent (no impact upon browser update)

• No need for browser plugin

• Based on official communication standards, security standards and regulations

• No additional software needed, the middleware includes it's own dependencies

• Recoverability build-in, preventive checks and tamper-proof

• Coops with multiple card readers/terminals (contact and contactless)

• Coops with multiple card types (we call it card application profiles)

• Extendable and secured framework, we are open to add any card the business needs on our platform

• Installers for all supported versions of Mac, Windows and Linux

• Installers for Citrix, XenApp or other shared environments

v3.1.4

Bug

• File digests config doesn't take the path differences between Mac OS and Windows into account

• PKCS11 configuration cookie cannot be created on Windows devices

• PKCS11 returns null pointer exception when no pin is provided

• Unresolved address exception when the Trust1Connector is installed or started without internet connection

Story

• As an end user I can use RMC with the new T1C v3 for the belgian eID and the file exchange

• Windows installers are signed with the Trust1Team certificate

• Windows installer includes the firewall settings upfront

• All endpoints communicating with smartcards/tokens/... need to be protected by means of JWT

• Support for silent install on Win Platforms

• Remove sensitive system info from API & Proxy exposed on /info endpoint

• Remove from API & Proxy the temp folder path on the /info

• Provide the possibility to use PKCS11 objects instead of keystores

• Integrate PKCS11 container in the sandbox-service

• Maintain a transaction log with labels

• Ability to do bulk signing with the generic token interface

v3.1.3

Bug

• PKCS11 SlotId in config issue

• Fileexchange when canceling file or directory dialogs, no error is thrown but an empty path is returned

• Catch errors with regards to the GRPC service nog being running

• File IO needs to check if access rights for file are fulfilled otherwise return 803

• Fileexchange v2 recovery failed due to wrong encoding

• T1C JS SDK fix typo for responseObject info endpoint

• Typescript typings are conflicting with eachother (generics)

• T1C SDK pkcs11generic slots should be numbers instead of strings

Story

• Cookie implementation for the Trust1Connector JS SDK in shared environments

v3.1.2

Bug

• check fileexchange file/directory access rights before executing the command

• After reinstallation the v3.0.1 of the t1c api config defines its running in a shared environment but there are no other instances running on the machine

• When no connector is installed no valid error code is returned in JS

• Play.pid blocking reinstallation of Trust1Connector API

Task

• Move file location of the T1C v3 file-exchange config to the new folder structure instead of using the old folder structure

Story

• Audit logging for tampering checks in the Trust1Connector

• Configure logging for T1C-API

• Keep audit record for lifecycle changes T1C-API (restart sandbox, ...)

• As an integrator I want to have the RemoteLoading functionality in REST available

• Keep DS logs for 1 year

• As the Trust1Connector I want the Sandbox to have an automatic recovery when an unexpected shutdown happens

• Add parameter validation to each endpoint which requires it

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

• Management of an in-memory list of active Agents

• Management of user consents in a shared environment by means of browser cookies with an optional configurable TTL (time to live)

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

• T1C-gRPC Port: This is the port exposing the gRPC interface locally towards the T1C-API component. The T1C-gRPC runs in a sandboxed and hardened environment, it contains the implementation modules needed for hardware communication with local or remote peripherals.

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.

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

Share Environment Flows

Communication Stack

Introduction

The Trust1Connector supports 2 different user consent mechanisms for applications:

• implicit user consent: the user will be provided with a consent token which can be pasted into his clipboard. The T1C-GCL will implicitly retrieve the consent token form the clipboard and perform a verification (the token pasted in the clipboard - form the application context - should match with the token available on the clipboard for the T1C-GCL)

For an implicit consent, the T1C is performing the verification of the shared code word.

The consent can be configured to have an expiration date, when this expiration date has been exceeded, a new consent will be asked towards the user.

Consent dialog for implicit consent

If the consent has been enabled upon installation of the Trust1Connector, a user will not be able to retrieve any data from the connector without first giving its consent, agreeing to give access to his/her card reader of filestorage. Without this consent, all requests will return a 401 Unauthorized response with error code 500 No valid consent found or at initialisation of the Trust1Connector SDK an error code 500 No valid consent found. The application should detect these error codes and use it to trigger the consent dialog.

The application shows this code word on screen and provide a button for 'copy-to-clipboard'. When the user has copied the code word to the clipboard (on user click button event), an implicit consent request can be executed towards the T1C. The T1C will grab the pasted code word from the user system clipboard and if both match, an implicit user consent has been granted for the calling application. The relation between the application and the local T1C instance is 'approved'. At this point the Trust1Connector returns a cookie that should be stored in the browser. This cookie will be re-used the next time the user wants to use the Trust1Connector until the cookie expires.

User clipboard remark

Initially the concept was based on copying programmatically the code word, from the application context, to the user system clipboard. Although, through CAB forum, this not allowed; A user interaction is mandatory. The application should provide a 'copy-to-clipboard' button or alike in order to 'trigger' a user action. Once this action has been done, the T1C executes the flow automatically, this is retrieval and verification of the code word.

Sending an implicit consent request can be done as follows:

This call has 1 required and 2 optional parameters:

1. Code Word (required): a code word in string format that will be shown in the consent dialog.

2. Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted

3. Callback function (optional): function to be called with the result of the consent request.

The response of the consent will be an updated T1C Client which you after this point can use to continue your use-case(s).

The response can also be a 400 Bad Request with status code 115 "No agents registered to the proxy service" which means that the request has been sent with the unique code but the Proxy cannot not find the user associated with it by checking the clipboards of all connected users.

This could mean that there is no T1C API client present or it is not running correctly.

Introduction

In order to use the JS-SDK, the library must be initialised with an api-key. The api-key is a key received upon subscription. The JS-SDK is a client library for web based consumers. As a reminder, the T1C can be used from a native applications context using a native client, or addressing directly the T1C interface. In order to work with an api-key in a browser context, 2 type of consumers can be distinguished:

• SPA (Single Page Application) integration: this is a web application without any back-end

• Web Application integration: this is a web application with a back-end implementation

For an SPA, an api-key (thus the access token to the Distribution Service) is considered unsafe in a browser context. For SPA's, Trust1Team configures extra security measures on infrastructure level. A mutual authentication is required and additional policies are applied (IP restriction policy, ...).

The api-key must be translated into an JWT token in order to enable communication with the T1C.

Initialise the client library

To initialise the JavaScript client library, the library must be loaded into your HTML page:

<script src="../T1CSdk.js" charset="utf-8"></script>

Once loaded, the script will expose a GCLLib global. This global will allow you to create a GCLConfig:

var config = new T1CSdk.T1CConfig(configOptions);

The GCLConfigOptions object will allow you to specify and/or override the configuration to be used. Configuration options can be found in the Configuration Options below. You can create a GCLConfigOptions as follows:

var configOptions = new T1CSdk.T1CConfigOptions(
        environment.t1cApiUrl,
        environment.t1cApiPort,
        environment.t1cProxyUrl,
        environment.t1cProxyPort,
        environment.t1cDSUrl,
        environment.jwt,
  );

Now that we have a configuration, we can initialise the client library. The following example creates a Promise that will resolve with an instance of a T1CClient:

T1CSdk.T1CClient.initialize(config).then(res => {
        client = res;
        console.log("Client config: ", client.localConfig)
        core = client.core();
    }, err => {});

Introduction

This page describes all generic token models used.

Models

export class ModuleDescriptionResponse extends DataObjectResponse {
  constructor(public data: TokenModuleDescription, public success: boolean) {
    super(data, success);
  }
}

export class TokenAddressResponse extends DataObjectResponse {
  constructor(public data: TokenAddressData, public success: boolean) {
    super(data, success);
  }
}

export class TokenPictureResponse extends DataObjectResponse {
  constructor(public data: TokenPictureData, public success: boolean) {
    super(data, success);
  }
}

export class TokenVerifyPinResponse extends DataObjectResponse {
  constructor(public data: TokenVerifyPinResponseData, public success: boolean) {
    super(data, success);
  }
}

export class TokenVerifyPinResponseData {
  constructor(
      public verified: boolean
  ) {}
}

export class TokenSignResponse extends DataObjectResponse {
  constructor(public data: TokenSignResponseData, public success: boolean) {
    super(data, success);
  }
}

export class TokenSignResponseData {
  constructor(
      public data?: string
  ) {}
}

export class TokenAuthenticateResponse extends DataObjectResponse {
  constructor(public data: TokenAuthenticateResponseData, public success: boolean) {
    super(data, success);
  }
}

export class TokenAuthenticateResponseData {
  constructor(
      public data?: string
  ) {}
}

export class TokenModuleDescription {
  constructor(
      public desc: string
  ) {}
}

export class TokenAddressData {
  constructor(
    public municipality?: string,
    public rawData?: string,
    public signature?: string,
    public streetAndNumber?: string,
    public version?: number,
    public zipcode?: string
  ) {}
}



export class TokenAllDataResponse extends DataObjectResponse {
  constructor(public data: TokenAllData, public success: boolean) {
    super(data, success);
  }
}


export class TokenAllData {
  constructor(
    public picture?: TokenPictureData,
    public biometric?: TokenBiometricData,
    public address?: TokenAddressData,
  ) {}
}

export class TokenPictureData {
  constructor(
      public picture?: string,
      public signature?: string,
      public width?: number,
      public height?: number,
  ) {}
}

export class TokenData {
  constructor(
      public rawData?: string,
      public version?: string,
      public serialNumber?: string,
      public label?: string,
      public prnGeneration?: string,
      public eidCompliant?: string,
      public graphicalPersoVersion?: string,
      public versionRfu?: string,
      public electricalPersoVersion?: string,
      public electricalPersoInterfaceVersion?: string,
      public changeCounter?: number,
      public activated?: string,
  ) {}
}

export class TokenDataResponse extends DataObjectResponse {
  constructor(public data: TokenData, public success: boolean) {
    super(data, success);
  }
}

export class TokenBiometricData {
  constructor(
    public birthDate?: string,
    public birthLocation?: string,
    public cardDeliveryMunicipality?: string,
    public cardNumber?: string,
    public cardValidityDateBegin?: string,
    public cardValidityDateEnd?: string,
    public chipNumber?: string,
    public documentType?: string,
    public firstNames?: string,
    public name?: string,
    public nationalNumber?: string,
    public nationality?: string,
    public nobleCondition?: string,
    public pictureHash?: string,
    public rawData?: string,
    public sex?: string,
    public signature?: string,
    public specialStatus?: string,
    public thirdName?: string,
    public version?: number,
    public issuer?: string
  ) {}
}

export class TokenBiometricDataResponse extends DataObjectResponse {
  constructor(public data: TokenBiometricData, public success: boolean) {
    super(data, success);
  }
}

export class TokenAlgorithmReferencesResponse {
  constructor(public data: TokenAlgorithmReferences, public success: boolean) {
  }
}

export class TokenAlgorithmReferences {
  constructor(public ref: Array<string>) {
  }
}

export class TokenResetPinResponse {
  constructor(public data: TokenResetPin, public success: boolean) {
  }
}

export class TokenResetPin {
  constructor(public verified: boolean) {
  }
}


export class PinType {
  static PIN = 'Pin';
  static CAN = 'Can';
}