# Truststore API

{% hint style="success" %}
This module is available starting from v3.8.5
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

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

```javascript
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](https://t1t.gitbook.io/t1c-js-guide-v3/token/token-typing-models#models)

## Get Truststore container object

Initialise a Trust1Connector client:

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

Get the container service:

```javascript
var ts = client.truststore();
```

Call a function for the container:

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

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

Response:

```javascript
{
    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

<pre class="language-javascript"><code class="lang-javascript"><strong>let filter = new Options(['authenticationCertificate']) //filter out only AuthenticationCertificates
</strong><strong>// The filter parameter is optional
</strong><strong>ts.allCerts(filter).then().catch()
</strong></code></pre>

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

## Sign Data

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
Truststore pop-up for mac will open a session on the Keychain
{% endhint %}

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

```javascript
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:

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

Response is a base64 encoded signed hash:

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

## Authenticate Data

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
Truststore pop-up for mac will open a session on the Keychain
{% endhint %}

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

```javascript
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:

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

Response is a base64 encoded signed hash:

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

### Bulk Signing

{% hint style="info" %}
Bulk signing is not active yet for Truststore, this will be released in a later update.
{% endhint %}

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](#bulk-pin-reset) method is called.

{% hint style="danger" %}
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.
{% endhint %}

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

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

Response will look like:

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

## Verify PIN

{% hint style="danger" %}
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.
{% endhint %}

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

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

Response:

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