# Chambersign\*

{% 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 %}

## Chambersign introduction

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

{% hint style="info" %}
The middleware of Chambersign has to be installed to be able to fully use the Chambersign

The version of the middleware supported is;\
Mac: [6.17.1](https://storage.googleapis.com/t1c-dependencies-prod/pkcs11-middleware/chambersign/scmiddleware-user_macosx_6.17.1.0.dmg)\
Windows: [6.12.0](https://storage.googleapis.com/t1c-dependencies-prod/pkcs11-middleware/chambersign/I-SCM-Desktop_Setup_6.12.0.0_user.exe)
{% endhint %}



## Interface

```javascript
export interface AbstractChambersign {
    allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
    authenticationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    nonRepudiationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;

    allCertsExtended(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsExtendedResponse) => void): Promise<TokenAllCertsExtendedResponse>;
    authenticationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
    nonRepudiationCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;

    validateSignature(body: TokenValidateSignatureRequest, callback?: (error: T1CLibException, data: TokenValidateSignatureResponse) => void): Promise<TokenValidateSignatureResponse>;

    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>;
    signRaw(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
    allAlgoRefs(callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
    resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
    tokenData(callback?: (error: T1CLibException, data: TokenInfoResponse) => void): Promise<TokenInfoResponse>;
}

```

### Models

All model information can be found in the [Token typings model page](../token-typing-models#models)

## Initialise the Trust1Connector JS

Initialise a Trust1Connector client with a valid configuration:

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

### Obtain the Reader information

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

```javascript
var core = client.core();
core.readersCardAvailable(callback);
```

This function call returns:

```javascript
{
  "data": [
    // List of reader with cards found
  ],
  "success": true
}
```

Using the generic interface can be done as follows;

```javascript
const moduleName = "chambersign";
var module = client.generic(selected_reader.id);
```

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

If you want to use the module directly you can initialise as folows (same functions are available but dont need the module to be included in the called function)

```javascript
var module = client.chambersign(selected_reader.id);
```



## Token info

You can fetch the token information via the function. this will give all the information of the token you need according to the PKCS11 specifications

```javascript
module.tokenData().then(res => {
    // see response below
})
```

```json
{
    "success": true,
    "data": {
        "info": {
            "slot": "string",
            "label": "string",
            "manufacturerId": "string",
            "model": "string",
            "serialNumber": "string",
            "flags": {
                "isRandomNumberGenerator": "boolean",
                "isWriteProtected": "boolean",
                "isLoginRequired": "boolean",
                "isUserPinInitialized": "boolean",
                "isRestoreKeyNotNeeded": "boolean",
                "isClockOnToken": "boolean",
                "isProtectedAuthenticationPath": "boolean",
                "isDualCryptoOperations": "boolean",
                "isTokenInitialized": "boolean",
                "isSecondaryAuthentication": "boolean",
                "isUserPinCountLow": "boolean",
                "isUserPinFinalTry": "boolean",
                "isUserPinLocked": "boolean",
                "isUserPinToBeChanged": "boolean",
                "isSoPinCountLow": "boolean",
                "isSoPinFinalTry": "boolean",
                "isSoPinLocked": "boolean",
                "isSoPinToBeChanged": "boolean"
            },
            "mechanisms": [
                {
                    "mechanism": "string",
                    "flags": {
                        "isHardware": "boolean",
                        "isEncrypt": "boolean",
                        "isDecrypt": "boolean",
                        "isDigest": "boolean",
                        "isSign": "boolean",
                        "isSignRecover": "boolean",
                        "isVerify": "boolean",
                        "isVerifyRecover": "boolean",
                        "isGenerate": "boolean",
                        "isGenerateKeyPair": "boolean",
                        "isWrap": "boolean",
                        "isUnwrap": "boolean",
                        "isExtension": "boolean",
                        "isEcFP": "boolean",
                        "isEcNamedcurve": "boolean",
                        "isEcUncompress": "boolean",
                        "isEcCompress": "boolean"
                    },
                    "ulMinKeySize": "number",
                    "ulMaxKeySize": "number"
                }
            ],
            "ulMaxSessionCount": "number",
            "ulSessionCount": "number",
            "ulMaxRwSessionCount": "number",
            "ulMaxPinLen": "number",
            "ulMinPinLen": "number",
            "ulTotalPubLicMemory": "number",
            "ulFreePubMemory": "number",
            "ulTotalPrivateMemory": "number",
            "ulFreePrivateMemory": "number",
            "hardwareVersion": "string",
            "firmwareVersion": "string"
        },
        "infoType": "TokenInfoType"
    }
}



//ENUM
TokenInfoType {
    Token,
    PKCS11,
    File,
    Payment,
    HSM,
    Vault,
    Wallet,
}
```

## Certificates

Exposes all the certificates publicly available on the smart card.

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

```javascript
module.authenticationCertificate(module, parseCertsBoolean, callback);
```

Response:

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

### Non-repudiation Certificate

Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key. 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:

```javascript
module.nonRepudiationCertificate(module, parseCertsBoolean, callback);
```

Response:

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

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

```javascript
var filter = [];
module.allCerts(module, parseCerts, { filters: filter}, callback);
```

Response:

```javascript
{
 "authenticationCertificate": {
  ...
 },
 "nonRepudiationCertificate": {
  ...
 }
}
```

The filter can be used to ask a list of custom data containers. For example, we want to read only the rootCertificate

```javascript
var filter = ['authenticationCertificate'];
module.allCerts(module, { filters: filter}, callback);
```

Response:

```javascript
{
 "authenticationCertificate": {
  ...
 }
}
```

## Sign Data

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

```javascript
var filter = null;
module.allCerts(module, { filters: filter}, callback);
```

Response:

```javascript
{
 "authenticationCertificate": {
  ...
 },
 "nonRepudiationCertificate": {
  ...
 }
}
```

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:

```javascript
var data = {
      "pin":"...",
      "algorithm":"sha1",
      "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
      "osDialog": true
}
module.sign(module, data, callback);
```

Response is a base64 encoded signed hash:

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

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

```javascript
var data = {
      "algorithm":"sha1",
      "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
      "osDialog": false
}
module.sign(module, data, callback);
```

Response is a base64 encoded signed hash:

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

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.

### Raw data signing

With the function `signRaw` you can sign unhashed document data. This means that the Trust1Connector will hash the value itself depending on the provided sign algorithm.

{% hint style="warning" %}
Trust1Connector only supports SHA2 hashing at this point.

When using SHA3, the Trust1Connector will convert to SHA2 implicitly
{% endhint %}

Below you can find an example

```javascript
var data = {
      "algorithm":"sha256",
      "data":"vl5He0ulthjX+VWNM46QX7vJ8VvXMq2k/Tq8Xq1bwEw=",
      "osDialog": false
}
chambersign.signRaw(data, callback);
```

The function looks the same as a regular sign operation but expects a `base64` data object that is unhashed.

Supported hash functions (SHA2) are;

* SHA256
* SHA384
* SHA512

### 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 [Bulk Sign Reset](../belgian-eid#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 = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    pin: "1234"
}
const bulk = true;
module.sign(module, 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
module.resetBulkPin(module).then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

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

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

```javascript
var data = {
      "pin":"..."
}
module.verifyPin(module, data, callback);
```

Response:

```javascript
{
  "verified": true
}
```

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

```javascript
var data = {}
module.verifyPin(module, data, callback);
```

Response:

```javascript
{
  "verified": true
}
```

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

```javascript
var data = {
  "pin": "...",
  "algorithm": "sha1",
  "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
module.authenticate(module, data, callback);
```

Response:

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

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

## Get valid algorithms to use for Sign or Authenticate

Via the Trust1Connector generic modules you are able to retrieve available algorithms to use for Signing or Authenticate

```javascript
module.allAlgoRefs(module, callback);
```

The response you can expect is a list of algorithms, an example can be found below (the values below are purely examplatory)

```javascript
{
    "success": true,
    "data": ["sha1", "sha256"]
}
```



## Validate signature

The module allows you to call a function on the token that can validate a signature. For this we need to use the `validateSignature` function. You can call this one via;

```javascript
const body = {
    "algorithm": 'sha256',
    "hash": '...',
    "signedHash": '...',
    "osDialog": false,
    "id": 'cert_id',
    "pin": 'pin_code',
    "timeout": 120 //timeout in seconds
}
module.validateSignature(body).then(response => {
    response.valid
).catch(error => {
    errorHandler(error)}
)
```

The response of this function will return a valid property that is either true or false.

```json
{
    "success": true,
    "data": {
        "valid": true
    }
}
```
