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

• Update T1C on device (install new version)

• Update DS (distribution server) metadata

• Increment use case counter

Executing these functionality is explained further.

Consumer resources

Consumer resources are typically used from an application perspective:

• Get pub-key certificate

• Get version

• Get Information (operating system, runtime, user context, variable configuration)

• List card-readers

• List modules

• Get module

• Get card-reader

• Get card-reader with cards inserted

• Get card-readers without card

• Get consent (needed for shared environments)

• Detect card for card-reader (polling utility resource)

• Detect any card (polling utility resource)

• Detect card-readers (polling utility resource)

• Browser Information (utility resource)

Executing these functionality is explained further.

Core Functionalities

The Trust1Connector functionalities are about secured communication with device hardware. The document highlights communication with smart card readers - contact and contact-less. Other hardware devices can be enabled or integrated as well in the solution. Some of the already are, for example printer drivers, signature tablet drivers, ...

Initialize the client library

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

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

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

List card readers

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

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

The response will contains a list of card readers:

{
  "success": true,
  "data": [
    {
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false,
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card (eID)"
        ],
        "module": "beid"
      }
    }
  ]
}

When multiple readers are attached to a device, the response will show all connected card readers:

{
  "data": [
    {
      "id": "ec3109c84ee9eeb5",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
      "pinpad": false
    },
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    },
    {
      "id": "c8d31f8fed44d952",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
      "pinpad": false
    }
  ],
  "success": true
}

Important to notice:

• The response adds a card-element when a card is inserted into the card reader.

• The response contains card-reader pin-pad capabilities

Card Inserted

As mentioned in the List card-readers, when a smart-card is inserted/detected, the reader will contain the cart-type based on the ATR. The ATR (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.

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

Pin-Pad Capabilities

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

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

List Card-Readers - Explained Example

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

{
  "data": [
    {
      "id": "ec3109c84ee9eeb5",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(2)",
      "pinpad": false
    },
    {
      "card": {
        "atr": "3B67000000000000009000",
        "description": [
          "MisterCash & Proton card",
          "VISA Card (emitted by Bank Card Company - Belgium)"
        ]
      },
      "id": "e5863fcc71478871",
      "name": "Gemalto Ezio Shield Secure Channel",
      "pinpad": true
    },
    {
      "card": {
        "atr": "3B9813400AA503010101AD1311",
        "description": [
          "Belgium Electronic ID card"
        ]
      },
      "id": "57a3e2e71c48cee9",
      "name": "Bit4id miniLector",
      "pinpad": false
    },
    {
      "id": "c8d31f8fed44d952",
      "name": "Identiv uTrust 4701 F Dual Interface Reader(1)",
      "pinpad": false
    }
  ],
  "success": true
}

In the above example you notice that 4 card-readers are connected. Each card-reader receives his temporary id which can be used for other functions where a card-reader id is needed. This method can be requested in order to list all available card-readers, and optional cards-inserted. Each card-reader has a vendor provided name, which is retrieved from the card-reader itself. An additional property pinpad, a boolean value, denotes if the card-reader has pin-pad capabilities. A pin-pad is a card-reader, most of the times with its own display and key-pad. From a security perspective, it's considered best practice to use as much as possible pin-pad capabilities of a pin-pad card-reader. When a reader has a smart-card inserted (contact interface) or detected (contactless interface), the card type will be resolved by the GCL in order to respond with a meaningful type. In the above examples you see that; one card-reader has a Belgian eID card; another card-reader has a MisterCash or VISA Card available for interaction.

The readers returned, are the card-readers with a card available. The card-readers where no card is presented, are ignored.

Get card reader with card inserted

Returns a list of available card readers with a smart card inserted. Multiple readers can be connected with multiple smart cards inserted. Each reader is identified by a unique reader_id and contains information about a connected smart card. A smart card is of a certain type. The Trust1Connector detects the type of the smart card and returns this information in the JSON response.

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

Response:

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

Download T1C Installer

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

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

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

1. /v3/downloads/installers/{{OS}}: This endpoint allows you to specify the OS for which you wish to obtain an installer. The possible values are win32, win64, unix, macos.

2. /v3/downloads/installers/{{OS}}/versions/{{version}}: This endpoint allows you to download a specific version of a T1C installer for a specific OS.

Get Information

Introduction

The PKCS #11 standard defines a platform-independent API to cryptographic tokens, such as hardware security modules (HSM), smart cards, and names the API itself "Cryptoki" (from "cryptographic token interface" and pronounced as "crypto-key" - but "PKCS #11" is often used to refer to the API as well as the standard that defines it). The API defines most commonly used cryptographic object types (RSAX.509 keys, DES/Triple DES Certificates/keys, etc.) and all the functions needed to use, create/generate, modify and delete those objects. This container relies on a PKCS#11 a library which handles the communication with the token/card. This can be a vendor specific library or an opensource one, please select the correct one depending on the type of token/card you are using.

Interface Summary

The Abstract PKCS #11 smartcard interface is summarised in the following snippet:

export interface AbstractPkcs11 {
    certificates(slotId: string, parseCerts?: boolean, callback?: (error: T1CLibException, data: Pkcs11ObjectCertificatesResponse) => void): Promise<Pkcs11ObjectCertificatesResponse>;
    signData(data: Pkcs11SignData, callback?: (error: T1CLibException, data: Pkcs11ObjectSignResponse) => void): Promise<Pkcs11ObjectSignResponse>;
    slots(callback?: (error: T1CLibException, data: Pkcs11ObjectSlotsResponse) => void): Promise<Pkcs11ObjectSlotsResponse>;
    slotsWithTokenPresent(callback?: (error: T1CLibException, data: Pkcs11ObjectSlotsResponse) => void): Promise<Pkcs11ObjectSlotsResponse>;
    token(slotId: string, callback?: (error: T1CLibException, data: Pkcs11ObjectTokenResponse) => void): Promise<Pkcs11ObjectTokenResponse>;
}

Pkcs11 object models

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

export class Pkcs11ObjectSign {
    constructor(public data: string) {
    }
}

export class Pkcs11ObjectSignResponse {
    constructor(public data: Pkcs11ObjectSign, public success: boolean) {
    }
}

export class Pkcs11ObjectSlots {
    constructor(public slots: Pkcs11Slot[]) {
    }
}

export class Pkcs11ObjectSlotsResponse {
    constructor(public data: Pkcs11ObjectSlots, public success: boolean) {
    }
}


export class Pkcs11ObjectCertificates {
    constructor(public certificates: Pkcs11ObjectCertificate[]) {}
}


export class Pkcs11ObjectCertificate {
    constructor(public id: string, public certificate: string, public parsed?: Certificate) {}
}

export class Pkcs11ObjectCertificatesResponse {
    constructor(public data: Pkcs11ObjectCertificates, public success: boolean) {
    }
}

export class Pkcs11SignData {
    constructor(public slotId: string,
                public certificateId: string,
                public algorithm: string,
                public data: string,
                public pin?: string,
                public osDialog?: boolean) {}
}

export class Pkcs11ObjectTokenResponse {
    constructor(public data: Pkcs11TokenInfo, public success: boolean) {
    }
}

export class Pkcs11SetConfigResponse {
    constructor(public data: string, public success: boolean) {
    }
}

export class Pkcs11Slots {
    constructor(public slots: Pkcs11Slot[]) {
    }
}

export class Pkcs11Slot {
    constructor(public slot: number,
                public description: string) {
    }
}

export class Pkcs11TokenInfo {
    constructor(public slot: string,
                public label: string,
                public manufacturerId: string,
                public model: string,
                public serialNumber: string,
                public flags: string,
                public ulMaxSessionCount: number,
                public ulSessionCount: number,
                public ulMaxRwSessionCount: number,
                public ulMaxPinLen: number,
                public ulMinPinLen: number,
                public ulTotalPublicMemory: number,
                public ulFreePublicMemory: number,
                public ulTotalPrivateMemory: number,
                public ulFreePrivateMemory: number,
                public hardwareVersion: string,
                public firmwareVersion: string) {
    }
}

Get the PKCS #11 container object

For more information on how to configure the JS client library see Configuration.

const winLocation = "C:\\Windows\\System32\\eTPKCS11.dll"
const macLocation = "/usr/local/lib/libeTPkcs11.dylib";

T1CSdk.T1CClient.initialize(config).then(res => {
  client = res;
  console.log("Client config: ", client.localConfig)
  core = client.core();
  
  // Depending on the OS select the appropriate location of the library
  const pkcs11 = client.pkcs11(winLocation);
  
}, err => {});

Call a function for the PKCS #11 container:

const slotId = 0;

pkcs11.certificates(slotId, true).then(res => {
    console.log(JSON.stringify(data, null, '  '));
}, err => {
    console.log("Error:",JSON.stringify(err, null, '  '));
});

Reading data

Slots

This methods returns the available slots on the system.

pkcs11.slots();

An example response:

{
    "data":
    [
        {
            "slot": 0,
            "description": "eToken 5100",
        },
        {
            "slot": 1,
            "description": "",
        }
    ]
    "success": true    
}

Slots with tokens present

This method is similar the the slots endpoint but only returns a list of slots where a token is present.

pkcs11.slotsWithTokenPresent(callback);

An example response:

{
    "data":
    [
        {
            "slot": 0,
            "description": "eToken 5100"
        }
    ]
    "success": true    
}

Token

This methods returns the token information for a slot.

pkcs11.token(slot_id, callback);

An example response:

{
    "data":
    {
        "slot": 1,
        "label": "Token Label",
        "manufacturerId": "Gemalto",
        "model": "Safenet Token e5100",
        "serialNumber": "1234567890",
        "flags": 7,
        "maxSessionCount": 10,
        "sessionCount": 1,
        "maxRwSessionCount": 5,
        "rwSessionCount": 1,
        "maxPinLength": 20,
        "minPinLength": 8,
        "totalPublicMemory": 10000,
        "freePublicMemory": 5000,
        "totalPrivateMemory": 1000,
        "freePrivateMemory": 50,
        "hardwareVersion": "1",
        "firmwareVersion": "1"
    },
    "success": true    
}

Certificates

This methods allows you to retrieve the certificates from the PKCS #11 token.

// retrieve certificates for token in slot_id 0
pkcs11.certificates(0, false);

Response:

{
  "data": [
    {
      "certificate": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "E8CE05618E79A79825722AE067EC0029851D860D"
    },
    {
      "certificate": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "id": "9F8F1CD68867526B1DF919832219B217282D2B0B"
    }
  ],
  "success": true
}

Signing data

To successfully sign data, we need the following parameters:

• Slot ID of the token to use

• Certificate ID of the signing certificate

• PIN code

• Hashed data to sign

• Hashing algorithm used

The slot id can be found using either a call to slots, slotsWithTokenPresent. Once the slot id is found, the certificates can be retrieved with a call to certificates. This then returns the certificate id. Now we can combine this with the PIN code and hashed data + hashing algorithm (SHA1, SHA256, SHA384, SHA512) to create the final signData call:

signData call

Returns signed data for provided input data.

var signDataPayload = {
    slotId: 1,
    certificateId: "9F8F1CD68867526B1DF919832219B217282D2B0B",
    pin: "thepincodeforthetoken",
    data: "hashed data"
    algorithm: "sha256"
}

pkcs11.signData(signDataPayload, callback);

An example response:

{
    "data": "L3BWs7lvoajPg5tC9GEmlSMdXMcDkNDUVVvt+KFqbJbXkJdI3DGoM3IOeXLaeTCxKmJ33/QQApL1nEAMuHY38V41czyswfSdpnqeex3EisXKkiYHeNzt9AXeoxDtsWbGkejKqru6X4xzAy/1SnccjZ2BQB/uUwyfyyweFjbZAGCLfTzWraCxG0ud2c8itsjmsBgXSuGjLqxKIJXbtuX22gd0nc4LeZLA91sxaoNFBCEVlOgJ/oJncFylf6T/Tz9R4VOA9kSf6NB1tAMsFEsihgjZafu/rzlrOfzZw4YY/T32LKY4Y2zNnDhJAucqflZjopGadDvkkSmTvxxEJuE+Bw==",
    "success": true    
}

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:

function callback(err,data) {
    if(err){
        console.log("Error:",JSON.stringify(err, null, '  '));
    }
    else {
        console.log(JSON.stringify(data, null, '  '));
    }
}

The error object returned:

{
  success: false,
  description: "some error description",
  code: "some error code"
}

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.

Currently, the need for a user interaction is a known limitation (aka. clipboard.js). As this is the case, the W3C has a project ' Clipboard APIs' 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:

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

}, err => {
    if (err.code == 500) {
        client = err.client
        $('#consentModal').modal('show', {
            keyboard: false
        });
        $('.consent-token').text(makeid(20));
    } else if (err.code == 115) {
        $('.consent-token').text(makeid(20));
    } else {
        console.error("T1C error:", err)
    }
});
    

$('#consentModal .btn-primary').on('click', (ev) => {
    const tokenNode = document.querySelector('.consent-token');
    var range = document.createRange();
    range.selectNode(tokenNode);
    window.getSelection().addRange(range);
    try {
        document.execCommand('copy');
    } catch (err) {
        console.log('Oops, unable to copy');
    }
    window.getSelection().removeRange(range);
    const clipboardData = tokenNode.textContent;
    
    client.core().getImplicitConsent(clipboardData).then(consentRes => {
        client = consentRes // replace the client and other set variables of the T1C
        core = client.core();
        core.version().then(versionResult => console.log("T1C running on core " + versionResult));
        $('#consentModal').modal('hide');
    }, err => {
        console.error(err)
    })
});

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

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

1. Integration of the API

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

"@types/lodash": "^4.14.150",
"Base64": "^1.1.0",
"axios": "^0.19.2",
"jsencrypt": "^3.0.0-rc.1",
"lodash": "^4.17.15",
"logger-bootstrap": "^2.0.0-alpha2",
"semver": "^7.3.2",
"sha256": "^0.2.0",
"store2": "^2.11.1",
"uuid": "^8.0.0"

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;

export class GCLConfigOptions {
    constructor(public gclUrl?: string,
                public gwOrProxyUrl?: string,
                public apiKey?: string,
                public gwJwt?: string,
                public tokenExchangeContextPath?: string,
                public ocvContextPath?: string,
                public dsContextPath?: string,
                public dsFileContextPath?: string,
                public pkcs11Config?: Pkcs11ModuleConfig,
                public agentPort?: number,
                public implicitDownload?: boolean,
                public forceHardwarePinpad?: boolean,
                public sessionTimeout?: number,
                public consentDuration?: number,
                public consentTimeout?: number,
                public syncManaged?: boolean,
                public osPinDialog?: boolean,
                public containerDownloadTimeout?: number,
                public localTestMode?: boolean,
                public lang?: string,
                public providedContainers?: T1CContainerid[]) {
    }
}

With the v3 this is significantly simplified to the following;

export class T1CConfigOptions {
  constructor(
    public t1cApiUrl?: string,
    public t1cApiPort?: string,
    public t1cRpcPort?: string,
    public t1cProxyUrl?: string,
    public t1cProxyPort?: string,
    public dsUrl?: string,
    public jwt?: string,
    public osPinDialog?: boolean
  ) {}
}

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:

config = new GCLLib.GCLConfig(configoptions);
    GCLLib.GCLClient.initialize(config).then(res => {
        client = res;
        core = client.core();
        console.log("GCLClient: ", res)
    }, err => {
        console.log("GCL error:", err)
        if (err.code == 301 || err.code == 302) {
            err.client.download("v2.1.0").then(res => {
                let download = "Download the GCL here";
                document.querySelector(".download").classList.remove("hidden")
                document.querySelector(".download").innerHTML = download.link(res.url);
            });
        }
    })

V3 example;

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

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

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:

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

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

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

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-GCL (Generic Connector Library).

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

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.

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 might have noticed the algorithm_reference property provided in the sign request. The algorithm_reference can be one of the values: md5, sha1, sha256, sha512. For example, we want the following text to be signed using sha256:

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:

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.

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. The 'algorithm_reference' property can contain the following values: sha1, sha256, sha512, md5.

  Generated Challenge

  A server generated challenge can be provided to the JavaScript library. In order to do so, an additional contract must be provided with the 'OCV API' (Open Certificate Validation API).

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

• JavaCard 2.1.1, MyEID3: 2.2.1

• GlobalPlatform 2.0.1 ' (Open Platform), MyEID3: GlobalPlatform 2.1.1

• FINEID S1 and S4 documentation

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

export interface AbstractAventra {
    allCertFilters(): string[];
    allKeyRefs(): string[];
    allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
    tokenData(callback?: (error: T1CLibException, data: TokenDataResponse) => void): Promise<TokenDataResponse>;
    rootCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    authenticationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    nonRepudiationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    encryptionCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    issuerCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>
    verifyPin(body: TokenVerifyPinData, callback?: (error: T1CLibException, data: TokenVerifyPinResponse) => void): Promise<TokenVerifyPinResponse>;
    authenticate(body: TokenAuthenticateOrSignData, callback?: (error: T1CLibException, data: TokenAuthenticateResponse) => void): Promise<TokenAuthenticateResponse>;
    sign(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
    resetPin(body: TokenResetPinData, callback?: (error: T1CLibException, data: TokenResetPinResponse) => void): Promise<TokenResetPinResponse>
    allAlgoRefs(callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
    resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}

Models

All model information can be found in the Token typings model page

Examples

Create the Aventra module

T1CSdk.T1CClient.initialize(config).then(res => {
    const aventra = res.client.createAventra(readerId);
}, err => {
    console.error(error)
});

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

All certificate filters

aventra.allCertFilters().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate', 'nonRepudiationCertificate', 'issuerCertificate']
}

all Key references

aventra.allKeyRefs().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: ['authenticate', 'sign', 'encrypt']
}

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

• Issuer certificate

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

const filter = ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate'];
aventra.allCerts(parseCertsBoolean, filter).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
       authenticationCertificate?: {
             certificate?: string,
             certificates?: Array<string>,
             certificateType?: string,
             id?: string,
             parsedCertificate?: Certificate,
             parsedCertificates?: Array<Certificate>
       },
       citizenCertificate?: {
             certificate?: string,
             certificates?: Array<string>,
             certificateType?: string,
             id?: string,
             parsedCertificate?: Certificate,
             parsedCertificates?: Array<Certificate>
       },
       nonRepudiationCertificate?: {
             certificate?: string,
             certificates?: Array<string>,
             certificateType?: string,
             id?: string,
             parsedCertificate?: Certificate,
             parsedCertificates?: Array<Certificate>
       },,
       rootCertificate?: {
             certificate?: string,
             certificates?: Array<string>,
             certificateType?: string,
             id?: string,
             parsedCertificate?: Certificate,
             parsedCertificates?: Array<Certificate>
       },,
       encryptionCertificate?: {
             certificate?: string,
             certificates?: Array<string>,
             certificateType?: string,
             id?: string,
             parsedCertificate?: Certificate,
             parsedCertificates?: Array<Certificate>
       },
    }
}

Token data

This will return information of the Aventra card.

aventra.tokenData().then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
       version?: string,
       serialNumber?: string,
       label?: string,
       changeCounter?: number,
    }
}

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.

aventra.rootCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

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

aventra.authenticationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

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.

aventra.nonRepudiationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Issuer certificate

aventra.issuerCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

Encryption certificate

aventra.encryptionCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})

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

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<Certificate>
    }    
}

Verify pin

const data = {
    pin: "1234", // optional
    osDialog: true // optional
}
aventra.verifyPin(data).then(res => {
}, err => {
    console.error(err)
})

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

{
    success: true,
    data: {
        certificate?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string
    }    
}

Sign

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.

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 Bulk PIN Reset method is called.

const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
const bulk = false;
aventra.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        data: string
    }
}

Bulk PIN Reset

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

aventra.resetBulkPin().then(res => {
}, err => {
    console.error(err)
})

Response will look like:

{
    "success": true,
    "data": true
}

Authenticate

const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
aventra.authenticate(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        data: string
    }
}

Reset pin

const data = {
    pin: "3214", //optional
    puk: "123123"
}
aventra.resetPin(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        verified: boolean
    }
}

Retrieve supported algorithms

aventra.allAlgoRefs(data).then(res => {
}, err => {
    console.error(err)
})

The expected response for this call should be;

{
    success: true,
    data: {
        ref: ['sha256', 'md5']
    }
}

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:

{
  description: "some error description",
  code: "some error code"
}

All possible values of the codes are described below in "Application Status Codes" The description field contains more information

Application Status Codes

General Trust1Connector errors

Transaction errors

Certificate errors

File (exchange) errors

Error codes coming from v2

Internal errors

Introduction

The Luxembourg ID container facilitates communication with card readers with inserted Luxembourg ID 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 Luxembourg ID container on the T1C-GCL (Generic Connector Library).

Interface Summary

The Abstract Lux eID interface is summarised in the following snippet:

Each interface will be covered on this wiki, accompanied with example code and response objects.

Models

All model information can be found in the

Get Luxembourg ID container object

Initialise a Trust1Connector client:

Get the Luxembourg ID container service:

Note that we pass both the reader_id and pin/can and specify the pin_type in this call. Unlike other cards, all communication with the Luxembourg ID card is protected with the PIN or CAN code.

Call a function for the Luxembourg ID container:

For demonstration purpose we will use the aforementioned callback, which only outputs the data and eventual error messages. During integration meaningful functionality should be provided.

The pin should be provided in order to instantiate the container. It's is possible to enforce user PIN entry for each function separately. Providing the PIN at instantiation of the container, means that the PIN will be in the browser session - but not persisted - for the lifetime of the container instance within the browser session.

Obtain the Reader-ID

The constructor for the Luxembourg ID 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 iDentiv CL, has no pin-pad capabilities, and there is a card detected with given ATR and description "Grand Duchy of Luxembourg...". 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 Luxembourg eID card. This must be done upon instantiation of the container:

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

Cardholder Information

The card holder is the person identified using the Luxembourg 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 Information

Contains all biometric related data, excluding the card holder address and picture. 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:

Signature Image

Contains an image of the card holder's signature stored on the smart card. The service can be called:

Response:

Certificates

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

• Root certificate

• Intermediate certificate

• Authentication certificate

• Non-repudiation certificate

T1C-JS will return the raw base64 certificate, optionally it can also return an object representing the certificate as parsed by . To enable parsing, parseCerts must be set to true.

The root and intermediate certificates are both stored as root certificates.

Certificate Chain

Root Certificate

Contains the 'root certificate' stored on the smart card. The root certificate is used to sign the 'intermediate certificate'. The service can be called:

Response:

There are 2 root certificates on the card, one is the issuer certificate of the intermediate

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:

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. The service can be called:

Response:

Data Filter

Filter Card Holder Information

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 'rn', 'picture' and 'rrn 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 'root-certificate' and the 'rrn-certificate':

Response:

Sign Data

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

• Retrieving the certificate chain (root, inetermediate 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

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 'authentication_reference' property can contain the following values: sha1, sha256, sha512, md5.

Avoid using SHA-1: is deprecated on the interface and will not be available in the future

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 might have noticed the algorithm_reference property provided in the sign request. The algorithm_reference can be one of the values: md5, sha1, sha256, sha512. For example, we want the following text to be signed using sha256:

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:

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

In order to inform a user upon the PIN retries left, the Luxembourg 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:

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.

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. The 'algorithm_reference' property can contain the following values: sha1, sha256, sha512, md5.

  Generated Challenge

  A server generated challenge can be provided to the JavaScript library. In order to do so, an additional contract must be provided with the 'OCV API' (Open Certificate Validation API).

Introduction

This page describes all generic token models used.

Models

Introduction

This page describes all generic payment models used.

Models

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

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


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

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

export class PaymentReadData {
  constructor(
      public applications: Array<PaymentApplication>,
  ) {}
}

export class PaymentApplication {
  constructor(
      public aid?: string,
      public name?: string,
      public priority?: number,
  ) {}
}


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

export class PaymentReadApplicationData {
  constructor(
      public country?: string,
      public countryCode?: string,
      public effectiveDate?: string,
      public expirationDate?: string,
      public language?: string,
      public name?: string,
      public pan?: string,
  ) {}
}

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

export class PaymentSignResponseData {
  constructor(public success: boolean, public data?: string, public cardSignature?: string, public readerSignature?: string) {
  }
}

export class PaymentSignResponse {
  constructor(public data: PaymentSignResponseData, public success: boolean) {}
}

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 .

Interface

Models

Initialising the SDK

Before you are able to use the SDK's methods you need to initialise the trust1connector javascript SDK. Below you can find an example of how to do this. You can also check the page.

In this example you can see when the connector is initialised we try to fetch the pkcs11 configuration already loaded in (if present), if this is not loaded you still need to upload the configuration. (line 30)

we store the client data for later use (line 27)

After initialising the configuration we can fetch all available slots to display on the screen. (line 31)

Configuration

Example

Example config contents

The most important config values are the name and the library (location of the PKCS11 dylib or DLL).

Base64 ecoding the config contents described in the codeblock above and sending them via the uploadConfig method of the JS sdk will enable you to upload and use that pkcs11 configuration.

Upload configuration

To be able to use the PKCS11 generic you need to upload a correct configuration file, which includes the name and library to be used. We use a html file chooser to fetch a file and use the FilereaderAPI to retrieve the contents of the selected file, then we convert it to a base64 string which we send to the uploadConfig method

Get configuration

Clear configuration

This method is used to clear a currently active configuration

Os information

Via the following endpoint your're able to retrieve OS information if required

Info

Retrieve the library information of the loaded configuration. When the loaded config is not present it will throw a configuration exception

Requirements: loaded configuration

slots

Retrieve all available slots

Requirements: loaded configuration

The same endpoint can be triggered but only showing the slots present;

Slot information

Retrieve relevant slot information

Requirements: loaded configuration, slotId

Token information

Retrieve information about the selected token

Requirements: loaded configuration, slotId

Retrieve aliasses

Retrieve all aliasses for a specific token.

Requirements: loaded configuration, slotId, verifyPin object

Retrieve the Private key type

Returns the name of the algorithm associated with this key

Requirements: loaded configuration, slotId, Alias, verifyPin object

Retrieve the certificates

Retrieve all certificates present for a specific token.

Requirements: loaded configuration, slotId, Alias, verifyPin object

Sign

Sign base64 data object.

Requirements: loaded configuration, slotId, Alias, signData object

Verify pin

Verify the pin of a specific token.

Requirements: loaded configuration, slotId, Alias, VerifyPin object

Status/error codes

TBD

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, a OS dialog window will be displayed for the user the enter their PIN

  • If the pin property is defined, that value is used

  • If osDialog is set to false, and pin is undefined, an error will be returned

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:

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

Introduction

The Trust1Connector API requires a valid JWT token to be provided in the Authorization header. This JWT token can be retrieved by asking the Distribution Service to generate a token for a specific API-key. It is important that this API-key is not exposed in the front-end application as this is a security violation.

When you've received a valid JWT token from the DS you can provide this into the configuration object when initialising the Trust1Connector JS client.

When using the Trust1Connector Javascript SDK the Authorization header is automatically populated with the JWT provided while initialising.

When the Token has expired there is a function which you can call to provide a new token and which will in turn return an updated client to be used.

Retrieving a JWT token

Retrieving a valid JWT token happens via the DS. When passing a valid API-key to header of the endpoint {{ds-url}}/v3/tokens/application (GET) you wil in turn receive a valid JWT token.

Example response

Refresh JWT token

A JWT token is only valid for a certain period. After this period the API will return an error. At this point you need to request a new JWT token to be able to communicate with the API.

In the T1C JS SDK there is a function which you can use to re-initalise the client with a new valid JWT token.

The updateJWT function can be found in the Core service. After initialising you can retrieve the core as follows:

The function's interface is as follows;

This function returns an updated client which you can continue to use for your desired use-cases.