1 of 39

v3.2.x

Introduction

Trust1Connector v3 Release Documentation

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.

Prerequisites

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.

Trust1Connector JS SDK

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

You can also find the source code here

Changelog

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

Bug

Core

Concept

Running the Trust1Connector in a shared environment, such as Citrix, XenApp and Remote Desktop, requires additional installation steps. In this section we explain the concept and approach used.

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

Communication Stack

Quick-Migration Guide

Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.

Introduction

Migration from the v2 to the v3 of the Trust1Connector can be done in 2 ways;

Integration of the API
Integration via the deprecated Javascript SDK

Both are viable integrations but we strongly suggest to integrate via the API since the JS SDK does not include all features, only the ones which were available in the v2. When integrating via the API you have more control over the Javascript packages used.

The Javascript SDK has the following packages as dependencies;

Update a v2 application to v3

For updating your web application first of all you need to use the new Javascript SDK. After this there are some differences in using the SDK from the v2.

Configuration

The configuration from the v2 has changed, we simplified this.

The v2 had the following configuration options;

With the v3 this is significantly simplified to the following;

Some of the config options of the v3 are still in review and can be removed up until the final release of the v3, in the table below you will find more information

Initialisation

After you've created your configuration object you can do the initialisation of the Trust1Connector SDK. This has largely remained the same except for the error codes.

V2 example:

V3 example;

Consent

Introduction

The Trust1Connector supports user consent mechanism 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)

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.

The implementation of the consent flows only apply with the T1C JS SDK. Implementation with the API directly is different

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.

Currently, the need for a user interaction is a known limitation (aka. ). As this is the case, the W3C has a project ' ' to propose a solution for a new clipboard API in browsers. The use case for 'Remote clipboard synchronisation' as a use case included in this draft proposal. As this is a draft, and not yet supported by the browsers, we can not perform an automatic 'paste' ('copy' in terms of the browser) to the clipboard.

Sending an implicit consent request can be done as follows:

This call has 1 required and 2 optional parameters:

Code Word (required): a code word in string format that will be shown in the consent dialog.
Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted. If not provided, the default value is 365 days.
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.

Status codes / error handeling

Introduction

In the Trust1Connector V3 we've completely reworked the error system. The goal of this system is to have error codes which are easy to read, understand and integrate. Our first implementation was a very generic approach with as few error codes as possible.

After some iterations of the Trust1Connector we've discovered that this error system does not suffice the needs. So we've upgraded the system to be more consistent and extensive. This provides integrators the flexibility to have a very detailed error handeling system while keeping it easy to understand and read.

The new system provides information about the origin, type and detailed information of the error. We maintained the same type (integers) as our previous error codes, this makes it easier to differentiate them.

HTTP Status Codes

T1C uses the following HTTP response codes when handling a request.

In case of an error the response will contain a body with more detailed information about the error:

Error format

Error codes will be in the following number format XXXXXX for example 201010 is an error code that depicts an error occurred with the reader in the Transaction service.

The first digit depicts the Origin of that error, values can be the following;

The following 2 digits describe the type of error;

Finally we have 3 digits that give a more detailed error. These will give you more information about the specific error-case. Currently we have the following exceptions that can be thrown.

Codes to expect

The following list are codes that you can expect.

General / Controller

Aventry My Id 4

Oberthur 7.3

Idemia cosmo 8.2

BeID

Diplad

Luxtrust

Luxeid

EMV

Crelan

File exchange

Error codes coming from v2

Configuration

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:

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

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:

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:

Trust1Connector SDK integration

Token

Payment

Payment typing models

Introduction

This page describes all generic payment models used.

Models

FIle

HSM

PKCS11

Consent

Introduction

The Trust1Connector supports user consent mechanism for applications:

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.

The implementation of the consent flows only apply with the T1C JS SDK. Implementation with the API directly is different

User clipboard remark

Sending an implicit consent request can be done as follows:

This call has 1 required and 2 optional parameters:

Code Word (required): a code word in string format that will be shown in the consent dialog.
Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted. If not provided, the default value is 365 days.
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).

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

Concept

Running the Trust1Connector in a shared environment, such as Citrix, XenApp and Remote Desktop, requires additional installation steps. In this section we explain the concept and approach used.

Architecture Overview

Components

Web Environment

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

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

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.

Central Back-Office

Security

Communication Stack

Generic token

Introduction

The Generic token interface is an interface used to integrate all supported tokens. This interface relies on the fact that you will need to provide a valid module. The module suggested from the reader response can be used here.

Interface

Models

All model information can be found in the

Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

Obtain the Reader information

In order to get all connected card-readers, with available cards:

This function call returns:

As you can see in the response we get a property suggestedModule which is returned based on the card, reader and AID information. This suggested module can be used in the generic interface.

Using the generic interface can be done as follows;

The pin and pinType are optional and are used for unlocking the pace layer (if the card is protected with a pace layer).

At this point for each use-case you will need to provide the module. This can be manually defined or be retrieved from the suggestedModule property in the reader-response. In the examples below we provide the module as a variable module

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

Data can be signed using the Belgian eID smart card. To do so, the T1C-GCL 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'.

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.

When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.

Bulk PIN Reset

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

Response will look like:

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:

Authentication

The T1C-GCL 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:

Response:

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.

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)

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

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)

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

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.

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

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

Response:

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.

Core interface

{
 "picture": {
  "picture": "/9j/4AAQSkZJRgABAgEBLAEsAAD/...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"
 },
 "biometric": {
  "birthDate": "15 JUL  1993",
  "birthLocation": "Roeselare",
  "cardDeliveryMunicipality": "Avelgem",
  "cardNumber": "592124058233",
  "cardValidityDateBegin": "27.05.2015",
  "cardValidityDateEnd": "27.05.2025",
  "chipNumber": "...==",
  "documentType": "01",
  "firstNames": "Gilles Frans",
  "name": "Platteeuw",
  "nationalNumber": "...",
  "nationality": "Belg",
  "nobleCondition": "",
  "pictureHash": "...=",
  "rawData": "...+axEIuyskBgFySsp/",
  "sex": "M",
  "signature": ".../OlA44h4YCM/h+J14xUCg/98Y9/.../C/RB2dtVbHwFvDuafmr4ZEshTlZTLidHKlISFvFWOtsLAEPCbl5LjfQwcOKe0pDADtHb4IStBnr+aaE8oHsTaKq66Y+zt+AbwdmWOrMA5URKKf7dZkY7jt3h8KZDw36VjcytUgjxVIdqwHsDkmIjK6mJtakIwybS5wn3RiQj33/vgG7JTRZJoKgDXLLTvLZO4qlfA==",
  "specialStatus": "0",
  "thirdName": "J",
  "version": "0"
 },
 "address": {
  "municipality": "Hoeselt",
  "rawData": "...==",
  "signature": "...+Evety1PnTE4pqXaHgBxIpk+P8kRL5W3zDV+../../..+YoHBC9KqTmSpl5KULxdnKiyCt+2RyJdzE2wyoymjRmysIhJy1wW9PRnx99S1TFqQLuc0tyBmkBPR4aFqmOq4a7zqd0q2Q1g+BbnwJ4d3oa10ia5+0kBXf0THoXv3HYIHlnwhBMfAtWzPnFrYBuAKTwyl7yBF5IFfXFpGWuVZUTJElgNcmNvsHMnAhVwDw==",
  "streetAndNumber": "Kerkstraat X",
  "version": "0",
  "zipcode": "3730"
 }
}

Oberthur Cosmo One v7.3

Introduction

The ID-One Cosmo V7-n is part of the Oberthur family of cryptographic modules called ID-One Cosmo V7. Modules within

this family share the same functionalities and the description of the ID-One Cosmo V7 applies to all versions including the “-n” subject to this validation.

This document describes the functionality provided by the Oberthur ID-One smartcard - which is a PKI container:

ID-One Cosmo V7-n; FIPS 140-2 Security Policy

Interface

Models

All model information can be found in the

Examples

Create the Oberthur module

When initialisation is finished you can continue using the aventra object to execute the functions below.

All certificate filters

The expected response for this call should be;

all Key references

The expected response for this call should be;

all Certificates

Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:

Root certificate
Signing certificate
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.

The expected response for this call should be;

Token data

This will return information of the Aventra card.

The expected response for this call should be;

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.

Root certificate

Contains the 'root certificate' stored on the smart card. The service can be called:

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, authentication and singing. The service can be called:

Non repudiation certificate

Issuer certificate

Encryption certificate

The expected response for these calls should be in the following format;

Verify pin

The expected response for these calls should be in the following format;

Sign

Data can be signed using the smartcard. To do so, the SDK facilitates in:

Retrieving the certificate chain (root, intermediate and non-repudiation certificate)
Perform a sign operation (private key stays on the smart card)
Return the signed has

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 expected response for this call should be;

Bulk PIN Reset

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

Response will look like:

Authenticate

The SDK 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.

The expected response for this call should be;

Retrieve supported algorithms

The expected response for this call should be;

Chambersign

Chambersign is only usable when the Middleware software has been installed. As integrator you can check this with the . Example will be described below

Chambersign introduction

The Chambersign token is a token that requires for the middleware of Chambersign to be installed prior to using it on the Trust1Connector.

Detect if Middleware has been installed.

Windows

The chambersign software for windows requires administration rights to be installed. After installation the location will be:

x64 & x86 ; C:\Program Files\ChamberSign

To check if this has been installed we can use the File-exchange create type function and then check the contents of the (sub)-folders.

To check if the middleware is installed the sample code below is a good start to use the File-Exchange to check if the middleware has been installed and its safe to continue to use the ChamberSign middleware and the Trust1Connector.

This is an example of how this could be integrated. You are free to implement this however you like. Information for the file-exchange module can be found

Interface

Be aware that for chambersign only the following functions are supported at this time:

authenticate
sign

Models

All model information can be found in the

Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

Obtain the Reader information

In order to get all connected card-readers, with available cards:

This function call returns:

Using the generic interface can be done as follows;

Because we're using the generic interface we can define the module variable upfront since we know we want to use the chambersign integration.

Certificates

Exposes all the certificates publicly available on the smart card.

Authentication Certificate

Response:

Non-repudiation Certificate

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

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

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

Bulk PIN Reset

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

Response will look like:

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:

Authentication

The T1C-GCL 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:

Response:

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.

Get valid algorithms to use for Sign or Authenticate

Via the Trust1Connector generic 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)

Airbus

Introduction

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

Interface

Models

All model information can be found in the

Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

Obtain the Reader information

In order to get all connected card-readers, with available cards:

This function call returns:

Using the generic interface can be done as follows;

Because we're using the generic interface we can define the module variable upfront since we know we want to use the jcop3 integration.

Certificates

Exposes all the certificates publicly available on the smart card.

Authentication Certificate

Response:

Non-repudiation Certificate

Response:

Encryption Certificate

Response:

Root Certificate/Issuer Certificate

Contains the 'root certificate' or 'Issuer certificate stored on the smart card. The service can be called:

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

Data can be signed using the Jcop3 smart card. To do so, the T1C-GCL facilitates in:

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

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

Bulk PIN Reset

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

Response will look like:

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:

Authentication

The T1C-GCL 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:

Response:

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.

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)

Aventra MyEID PKI

Introduction

Aventra MyEID PKI Card is a cryptographic smart card conforming to common Public Key Infrastructure standards like ISO/IEC-7816 and PKCS#15v1.0 specification. It can be used for various tasks requiring strong cryptography, e. g. logging securely to Windows, encrypting e-mail, authentication, and electronic signatures. The card is also available as a Dual Interface version, compatible with T=CL protocol and also emulating Mifare™. The card is a JavaCard with Aventra MyEID applet that implements the functionality.

The applet implements the FINEID S1 v1.12 specification and it can be configured to include all or any subset of the features specified in FINEID S4-1 or S4-2 specifications. Starting from version 2.2.0 the applet supports both 1024 and 2048 bit RSA keys. From version 3.0.0 (MyEID3) the applet supports keys from 512 bit up to 2048 bit in increments of 64 bits. The applet is fully compatible with JavaCard 2.1.1 and GlobalPlatform 2.0.1 specifications. The new MyEID version 3 (MyEID3) is now released and it uses the new JavaCard 2.2.1 and GlobalPlatform 2.1.1 platform. The new MyEID3 now supports RSA keys from 512 up to 2048 bits in 64 bit increments. MyEID3 supports file sizes up to 32767 bytes and 14 different PIN-codes can be created and used. The number of RSA keys is only limited by the available memory and maximum numbers of files (see PUT DATA: INITIALISE APPLET).

References

The most relevant specifications and standards are:

ISO/IEC 7816-4
ISO/IEC 7816-8
ISO/IEC 7816-9

This document describes the functionality provided by the Aventra smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:

MyEID - reference manual v1.7.36

Interface

Models

All model information can be found in the

Examples

Create the Aventra module

When initialisation is finished you can continue using the aventra object to execute the functions below.

All certificate filters

The expected response for this call should be;

all Key references

The expected response for this call should be;

all Certificates

Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:

Root certificate
Signing certificate
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.

The expected response for this call should be;

Token data

This will return information of the Aventra card.

The expected response for this call should be;

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.

Root certificate

Contains the 'root certificate' stored on the smart card.

Authentication certificate

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.

Issuer certificate

Encryption certificate

The expected response for these calls should be in the following format;

Verify pin

The expected response for these calls should be in the following format;

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.

The expected response for this call should be;

Bulk PIN Reset

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

Response will look like:

Authenticate

The expected response for this call should be;

Reset pin

The expected response for this call should be;

Retrieve supported algorithms

The expected response for this call should be;

Certigna

Introduction

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

Interface

Be aware that for certigna only the following functions are supported at this time:

authenticate
sign

Models

All model information can be found in the

Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

Obtain the Reader information

In order to get all connected card-readers, with available cards:

This function call returns:

Using the generic interface can be done as follows;

Because we're using the generic interface we can define the module variable upfront since we know we want to use the certigna integration.

Certificates

Exposes all the certificates publicly available on the smart card.

Authentication Certificate

Response:

Non-repudiation Certificate

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

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

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

Bulk PIN Reset

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

Response will look like:

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:

Authentication

The T1C-GCL 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:

Response:

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.

Get valid algorithms to use for Sign or Authenticate

Via the Trust1Connector generic 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)

Jcop3

Introduction

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

Interface

Models

All model information can be found in the

Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

Obtain the Reader information

In order to get all connected card-readers, with available cards:

This function call returns:

Using the generic interface can be done as follows;

Because we're using the generic interface we can define the module variable upfront since we know we want to use the jcop3 integration.

Certificates

Exposes all the certificates publicly available on the smart card.

Authentication Certificate

Response:

Non-repudiation Certificate

Response:

Encryption Certificate

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

Data can be signed using the Jcop3 smart card. To do so, the T1C-GCL facilitates in:

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

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

Check the before signing with a defined algorithm

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

Bulk PIN Reset

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

Response will look like:

Verify PIN

Verify pin only check the global sign pin at this moment

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:

Authentication

The T1C-GCL 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:

Response:

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.

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)

{
 "picture": {
  "picture": "/9j/4AAQSkZJRgABAgEBLAEsAAD/...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"
 },
 "biometric": {
  "birthDate": "15 JUL  1993",
  "birthLocation": "Roeselare",
  "cardDeliveryMunicipality": "Avelgem",
  "cardNumber": "592124058233",
  "cardValidityDateBegin": "27.05.2015",
  "cardValidityDateEnd": "27.05.2025",
  "chipNumber": "...==",
  "documentType": "01",
  "firstNames": "Gilles Frans",
  "name": "Platteeuw",
  "nationalNumber": "...",
  "nationality": "Belg",
  "nobleCondition": "",
  "pictureHash": "...=",
  "rawData": "...+axEIuyskBgFySsp/",
  "sex": "M",
  "signature": ".../OlA44h4YCM/h+J14xUCg/98Y9/.../C/RB2dtVbHwFvDuafmr4ZEshTlZTLidHKlISFvFWOtsLAEPCbl5LjfQwcOKe0pDADtHb4IStBnr+aaE8oHsTaKq66Y+zt+AbwdmWOrMA5URKKf7dZkY7jt3h8KZDw36VjcytUgjxVIdqwHsDkmIjK6mJtakIwybS5wn3RiQj33/vgG7JTRZJoKgDXLLTvLZO4qlfA==",
  "specialStatus": "0",
  "thirdName": "J",
  "version": "0"
 },
 "address": {
  "municipality": "Hoeselt",
  "rawData": "...==",
  "signature": "...+Evety1PnTE4pqXaHgBxIpk+P8kRL5W3zDV+../../..+YoHBC9KqTmSpl5KULxdnKiyCt+2RyJdzE2wyoymjRmysIhJy1wW9PRnx99S1TFqQLuc0tyBmkBPR4aFqmOq4a7zqd0q2Q1g+BbnwJ4d3oa10ia5+0kBXf0THoXv3HYIHlnwhBMfAtWzPnFrYBuAKTwyl7yBF5IFfXFpGWuVZUTJElgNcmNvsHMnAhVwDw==",
  "streetAndNumber": "Kerkstraat X",
  "version": "0",
  "zipcode": "3730"
 }
}

v3.2.x

Introduction

hashtagA Word of Introduction

Prerequisites

hashtagTrust1Connector API DNS

Trust1Connector JS SDK

Changelog

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

hashtagBug

Core

Concept

hashtagArchitecture Overview

hashtagComponents

hashtagWeb Environment

hashtagShared Environment Host

hashtagShared Environment Client

hashtagCentral Back-Office

hashtagSecurity

hashtagShare Environment Flows

hashtagCommunication Stack

Quick-Migration Guide

hashtagIntroduction

hashtagUpdate a v2 application to v3

hashtagConfiguration

hashtagInitialisation

Consent

hashtagIntroduction

hashtagConsent dialog for implicit consent

hashtagUser clipboard remark

Status codes / error handeling

hashtagIntroduction

hashtagHTTP Status Codes

hashtagError format

hashtagCodes to expect

hashtagGeneral / Controller

hashtagAventry My Id 4

hashtagOberthur 7.3

hashtagIdemia cosmo 8.2

hashtagBeID

hashtagDiplad

hashtagLuxtrust

hashtagLuxeid

hashtagEMV

hashtagCrelan

hashtagFile exchange

hashtagError codes coming from v2

hashtag

Configuration

hashtagIntroduction

hashtagInitialise the client library

Trust1Connector SDK integration

Token

Payment

Payment typing models

hashtagIntroduction

hashtagModels

FIle

HSM

PKCS11

Payment typing models

hashtagIntroduction

hashtagModels

Quick-Migration Guide

hashtagIntroduction

hashtagUpdate a v2 application to v3

hashtagConfiguration

hashtagInitialisation

Trust1Connector JS SDK

Changelog

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

hashtagBug

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

hashtagBug

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

hashtagBug

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

hashtagBug

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

hashtagBug

hashtagStory

A Word of Introduction

Trust1Connector API DNS

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

Bug

Architecture Overview

Components

Web Environment

Shared Environment Host

Shared Environment Client

Central Back-Office

Security

Share Environment Flows

Communication Stack

Introduction

Update a v2 application to v3

Configuration

Initialisation

Introduction

Consent dialog for implicit consent

User clipboard remark

Introduction

HTTP Status Codes

Error format

Codes to expect

General / Controller

Aventry My Id 4

Oberthur 7.3

Idemia cosmo 8.2

BeID

Diplad

Luxtrust

Luxeid

EMV

Crelan

File exchange

Error codes coming from v2

Introduction

Initialise the client library

Introduction

Models

Introduction

Models

Introduction

Update a v2 application to v3

Configuration

Initialisation

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

Bug

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

Bug

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

Bug

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

Bug

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

Bug

Story

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

Bug

Story

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

Bug

Story

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

Bug

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

Improvement

Introduction

Consent dialog for implicit consent

User clipboard remark

Trust1Connector API DNS

Distribution Service

Disk Space

API Key

Operating System

Windows 8.1 or higher

Registry keys

Cookies

A Word of Introduction

Architecture Overview