# Diplad (BeLawyer)

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

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. 193*bis* of the [Codex Deontologie voor Advocaten](https://www.advocaat.be/een-advocaat-raadplegen/wat-is-een-advocaat):

“De advocaat moet voor zijn identificatie en voor de authenticatie beschikken over de elektronische CCBE-advocatenkaart.”

More info at <https://www.diplad.be/en-GB/t/23/elektronische-advocatenkaart.aspx>.

## Interface

### Module

```javascript
export interface AbstractEidDiplad {
   allData(filters: string[] | Options, callback?: (error: T1CLibException, data: TokenAllDataResponse) => void): Promise<TokenAllDataResponse>;
  allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
  biometric(callback?: (error: T1CLibException, data: TokenBiometricDataResponse) => void): Promise<TokenBiometricDataResponse>;
  tokenData(callback?: (error: T1CLibException, data: TokenInfoResponse) => void): Promise<TokenInfoResponse>;
  address(callback?: (error: T1CLibException, data: TokenAddressResponse) => void): Promise<TokenAddressResponse>;
  picture(callback?: (error: T1CLibException, data: TokenPictureResponse) => void): Promise<TokenPictureResponse>;
  rootCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
  intermediateCertificates(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>;

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

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

## Examples

### Initializing Diplad Module

```javascript
T1cSdk.initialize(config).then(res => {
    const diplad = res.client.createEidDiplad(readerId);
}, err => {
    console.error(error)
});
```

### All Data

```javascript
diplad.allData().then(res => {
}, err => {
   console.log(err);
}
```

Response will look like:

```javascript
{
  "data": {
    "biometric": {
      "cardNumber": "cardNumber",
      "cardValidityDateEnd": "2021-01-08",
      "chipNumber": "c57c0a3f-d034-46c9-831e-a208b2e44fb6",
      "firstNames": "Tom",
      "name": "Van Cammen",
      "nationality": "BE",
      "rawData": "BASE64_ENCODED_CARD_DATA",
      "version": "1",
      "issuer": ""
    },
    "picture": {
      "picture": "BASE64_ENCODED_BYTE_ARRAY"
    }
  },
  "success": true
}
```

### Biometric Data

```javascript
diplad.biometric().then(res => {
}, err => {
   console.log(err);
}
```

�Response will look like:

```javascript
{
  "data": {
    "cardNumber": "cardNumber",
    "cardValidityDateEnd": "2021-01-08",
    "chipNumber": "c57c0a3f-d034-46c9-831e-a208b2e44fb6",
    "firstNames": "Tom",
    "name": "Van Cammen",
    "nationality": "BE",
    "rawData": "BASE64_ENCODED_CARD_DATA",
    "version": "1",
    "issuer": ""
  },
  "success": true
}
```

### Picture

```javascript
diplad.picture().then(res => {
}, err => {
   console.log(err);
}
```

Response will look like:

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

### All Certificates

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

```javascript
const filter = ['rootCertificate', 'authenticationCertificate', 'nonRepudiationCertificate'];
diplad.allCerts(parseCertsBoolean, filter).then(res => {
}, err => {
   console.log(err);
}
```

{% hint style="info" %}
The filter is optional
{% endhint %}

Response will look like:

```javascript
{
    success: true,
    data: {
       authenticationCertificate?: {
             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>
       },
    }
}
```

### Root Certificate

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

```javascript
diplad.rootCertificate(parseCertsBoolean).then(res => {
}, err => {
   console.log(err);
}
```

Response will look like:

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

### Authentication Certificate

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

```javascript
diplad.authenticationCertificate(parseCertsBoolean).then(res => {
}, err => {
   console.log(err);
}
```

Response will look like:

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

### Non-Repudiation Certificate

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

```javascript
diplad.nonRepudiationCertificate(parseCertsBoolean).then(res => {
}, err => {
   console.log(err);
}
```

Response will look like:

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

### Verify PIN&#x20;

* 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

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

Response will look like:

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

### Sign

To sign data, an algorithm must be specified in the `algorithm` property (see [Supported Algorithms](#get-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](#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 %}

The PIN can provided/entered in the same way as [Verify PIN](#verify-pin)

```javascript
const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    pin: "1234"
}
const bulk = false;
diplad.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

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

### 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 [Verify PIN](#verify-pin)

```javascript
const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    pin: "1234"
}
diplad.authenticate(data).then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

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

### Get Supported Algorithms

```javascript
diplad.allAlgoRefs().then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

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

### Bulk PIN Reset

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

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

Response will look like:

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