Truststore API

This module is available starting from v3.8.5

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

The Truststore API has been introduced to allow using any PKCS11 compatible smart card, which is available in the OS certificate or keystore. The Trust1Connector will interface to the Windows Certificate manager or the Mac Keystore using native OS mappings.

Certificates available in the certificate manager or keystore will be availabe through the generic Trust1Connector interface.

Interface

export interface AbstractTruststore {
  allCerts(filters?: string[] | Options): Promise<GenericT1CResponse<TruststoreAllCertificatesResponse>>;
  rootCertificates(): Promise<GenericT1CResponse<CertificatesResponse>>;
  intermediateCertificates(): Promise<GenericT1CResponse<CertificatesResponse>>;
  authenticationCertificates(): Promise<GenericT1CResponse<CertificatesResponse>>;
  nonRepudiationCertificates(): Promise<GenericT1CResponse<CertificatesResponse>>;
  encryptionCertificates(): Promise<GenericT1CResponse<CertificatesResponse>>;
  getCertificate(id: string): Promise<GenericT1CResponse<TruststoreCertificate>>;

  verifyPin(body: TruststoreVerifyPinRequest): Promise<GenericT1CResponse<boolean>>;
  authenticate(body: TruststoreAuthenticateOrSignRequest): Promise<GenericT1CResponse<TruststoreAuthenticateOrSignResponse>>;
  sign(body: TruststoreAuthenticateOrSignRequest, bulk?: boolean): Promise<GenericT1CResponse<TruststoreAuthenticateOrSignResponse>>;
  allAlgoRefs(): Promise<GenericT1CResponse<string>>;
  resetBulkPin(): Promise<GenericT1CResponse<boolean>>;
}

Models

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

Get Truststore container object

Initialise a Trust1Connector client:

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

Get the container service:

var ts = client.truststore();

Call a function for the container:

ts.allCerts();

Certificates

Exposes all the certificates publicly available on the store.

this has the capabilities to return multiple certificates if the store has multiple of any type.

Fetching Certificate information

Below you can find all the functions to retrieve a specific type of certificates

ts.authenticationCertificates().then().catch();
ts.rootCertificates().then().catch();
ts.intermediateCertificates().then().catch();
ts.encryptionCertificates().then().catch();
ts.nonRepudiationCertificates().then().catch();

Response:

{
    success: true,
    data: {
        certificates: [{
            "certificate": "MIIEd..jRTii/DF8nHZiNmm5w==",
            "id": "4d4eebf..43ddf00042e",
            "subject": "C=B...ication)",
            "serialNumber": "10:00:00:00...2:e8:26:6e"
        }],     
    }    
}

You can also fetch all the certificates, separated by type, at once

let filter = new Options(['authenticationCertificate']) //filter out only AuthenticationCertificates
// The filter parameter is optional
ts.allCerts(filter).then().catch()

{
  "success": true,
  "data": {
    "authenticationCertificate": {
      "certificates": [
        {
          "certificate": "MIAKBggqhkjOPQQDAwNnADBkAj5w==",
          "id": "4d4eebf5f4df00042e",
          "subject": "C=BEtication)",
          "serialNumber": "10:00:e8:26:6e"
        }
      ]
    }
  }
}

Sign Data

On MacOS it is not possible to provide a pin yet, this will be resolved in a future version; this feature depends on the availability of this funcitonality on the MacOS.

Truststore pop-up for mac will open a session on the Keychain

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

var filter = null;
ts.allCerts({ filters: filter});

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:

var data = {
      "pin":"...",
      "certId:"...",
      "data":"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
      "osDialog": true
}
ts.sign(data);

Response is a base64 encoded signed hash:

{
  "success": true,
  "data": {
    "data" : "W7wqvWA8m9S...="
  }
}

Authenticate Data

On MacOS it is not possible to provide a pin yet, this will be resolved in a future version; this feature depends on the availability of this funcitonality on the MacOS.

Truststore pop-up for mac will open a session on the Keychain

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

var filter = null;
ts.allCerts({ filters: filter});

Authenticate Hash

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

var data = {
      "pin":"...",
      "certId:"...",
      "data":"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
      "osDialog": true
}
ts.authenticate(data);

Response is a base64 encoded signed hash:

{
  "success": true,
  "data": {
    "data" : "W7wqvWA8m9S...="
  }
}

Bulk Signing

Bulk signing is not active yet for Truststore, this will be released in a later update.

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

const data = {
      "pin":"...",
      "certId:"...",
      "data":"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
      "osDialog": true
}
const bulk = true;
ts.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})

Bulk PIN Reset

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

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

Response will look like:

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

Verify PIN

On MacOS it is not possible to provide a pin yet, this will be resolved in a future version; this feature depends on the availability of this funcitonality on the MacOS.

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:

var data = {
      pin?: string;
      osDialog?: boolean;
      timeout?: Number;
      certId?: string;
}
ts.verifyPin(data);

Response:

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