# Luxembourg ID

## Introduction

The Luxembourg ID container facilitates communication with card readers with inserted Luxembourg ID smart card. The 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 module

## Interface Summary

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

```javascript
export interface AbstractEidLux {
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>;
  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>;
  rootCertificateExtended(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>;

  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>;}


export class PinType {
  static PIN = 'Pin';
  static CAN = 'Can';
}

```

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

## Get Luxembourg ID container object

For more information on how to configure the T1C-JS client library see [Client Configuration](https://t1t.gitbook.io/t1c-js-guide-v3/3.6.x/token/broken-reference).\
Initialize a gclClient:

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

Get the Luxembourg ID container service:

```javascript
var module = client.luxeid(reader_id, pin, pinType);
```

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

Call a function for the Luxembourg ID container:

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

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](https://t1t.gitbook.io/t1c-js-guide-v3/3.6.x/token/broken-reference).\
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:

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

This function call returns:

```javascript
{
  "data": [
    {
      "card": {
        "atr": "3B8F800180318065B0850300EF120FFF82900073",
        "description":["Grand Duchy of Luxembourg / Identity card with LuxTrust certificate (eID)"
      },
      "id": "57a3e2e71c48cee9",
      "name": "iDentiv CL",
      "pinpad": false
    }
  ],
  "success": true
}
```

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 (**A**nswer **T**o **R**eset) 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:

```javascript
var module = client.luxeid(reader_id, pin, pinType);
```

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:

```javascript
client.luxeid(reader_id, pin, pinType).biometric(callback);
```

An example callback:

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

Response:

```javascript
{
  "data": {
    "birthDate": "830819",
    "documentNumber": "SPEC04168",
    "documentType": "ID",
    "firstName": "SPECIMEN",
    "gender": "F",
    "issuingState": "LUX",
    "lastName": "SPECIMEN",
    "nationality": "LUX",
    "validityEndDate": "251116",
    "validityStartDate": "151116"
  },
  "success": true
}
```

### Address

Contains the card holder's address. The service can be called:

```javascript
client.luxeid(reader_id, pin, pinType).address(callback);
```

Response:

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

### Picture

Contains the card holder's picture stored on the smart card. The service can be called:

```javascript
client.luxeid(reader_id, pin, pinType).picture(callback);
```

Response:

```javascript
{
  "data": {
    "height": 320,
    "image": "/0//UQAvAAAAAADwAAABQAAAAAAAAAAAAAAA8AAA....uq9eK159DRO61Ufrf9ICA/9k=",
    "width": 240
  },
  "success": true
}
```

### Signature Image

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

```javascript
client.luxeid(reader_id, pin, pinType).signatureImage(callback);
```

Response:

```javascript
{
  "data": {
    "image": "/0//UQAvAAAAAADwAAABQAAAAAAAAAAAAAAA8AAA....uq9eK159DRO61Ufrf9ICA/9k=",
    "raw_data": "/0//UQAAAAAADwAAARLKEQDAAAAAAAAAAAAAA8AAA....dl42fgr367PCSA321/9k="
  },
  "success": true
}
```

## 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 [PKI.js](https://pkijs.org/). To enable parsing, `parseCerts` must be set to `true`.

![The root and intermediate certificates are both stored as root certificates.](https://1945252052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FElpUaD46PuXaqGsQm4Rz%2Fuploads%2FGkxNqTXtqoOSC4fqGLfG%2Fimage.png?alt=media\&token=fb20e475-b839-4e4e-96bc-b4a26e2ce188)

## Certificate Chain

### Extended certificates

You can also fetch the extended versions of the certificates via the functions

```
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>;
encryptionCertificateExtended(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateExtendedResponse) => void): Promise<TokenCertificateExtendedResponse>;
```

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

for a single certificate the response looks like:

```json
{
    "success" : true
    "data" : {
        "certificates": [{
            "certificate"?: string,
            "certificateType"?: string,
            "id"?: string,
            "subject"?: string,
            "issuer"?: string,
            "serialNumber"?: string,
            "url"?: string,
            "hashSubPubKey"?: string,
            "hashIssPubKey"?: string,
            "exponent"?: string,
            "remainder"?: string,
            "parsedCertificate"?: Certificate
        }]
    }
}
```

the `allCertsExtended` returns the following, with the contents of the certificates as the one you can see above;

```json
{
    "success" : true
    "data" : {
        "authenticationCertificate": {
            "certificates": [...]
        },
        "nonRepudiationCertificate": {
            "certificates": [...]
        },
        "rootCertificate": {
            "certificates": [...]
        }        
   }
}
```

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

```javascript
client.luxeid(reader_id, pin, pinType).rootCertificate({ parseCerts: true }, callback);
```

Response:

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

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

```javascript
client.luxeid(reader_id, pin, pinType).authenticationCertificate({ parseCerts: true }, 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.\
The service can be called:

```javascript
client.luxeid(reader_id, pin, pinType).nonRepudiationCertificate({ parseCerts: true }, callback);
```

Response:

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

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

```javascript
var filter = [];
client.luxeid(reader_id, pin, pinType).allData({ filters: filter, parseCerts: true }, callback);
```

Response:

```javascript
{
  "data": {
    "authentication_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "parsed": { // parsed certificate object }
    },
    "biometric": {
      "birthDate": "830819",
      "documentNumber": "SPEC04168",
      "documentType": "ID",
      "firstName": "SPECIMEN",
      "gender": "F",
      "issuingState": "LUX",
      "lastName": "SPECIMEN",
      "nationality": "LUX",
      "validityEndDate": "251116",
      "validityStartDate": "151116"
    },
    "non_repudiation_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "parsed": { // parsed certificate object }
    },
    "picture": {
      "height": 320,
      "image": "/0//UQAvAAAAAADwAAABQAAAAAAAAAA...f9ICA/9k=",
      "width": 240
    },
    "root_certificates": [
      {
        "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
        "parsed": { // parsed certificate object }
      },
      {
        "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
        "parsed": { // parsed certificate object }
      }
    ]
  },
  "success": true
}
```

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

```javascript
// filter entries := ["authentication-certificate","biometric","non-repudiation-certificate","picture","root-certificates"]
var filter = ["biometric","authentication-certificate"];
client.luxeid(reader_id, pin, pinType).allData({ filters: filter, parseCerts: true }, callback);
```

Response:

```javascript
{
  "data": {
    "biometric": {
      "birthDate": "830819",
      "documentNumber": "SPEC04168",
      "documentType": "ID",
        "firstName": "SPECIMEN",
        "gender": "F",
        "issuingState": "LUX",
        "lastName": "SPECIMEN",
        "nationality": "LUX",
        "validityEndDate": "251116",
        "validityStartDate": "151116"
    },
    "authentication_certificate": {
      "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
      "parsed": { // parsed certificate object }
    }
  },
  "success": true
}
```

### 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 = [];
client.luxeid(reader_id, pin, pinType).allCerts({ filters: filter, parseCerts: true }, callback);
```

Response:

```javascript
{
 "rootCertificate": {
  ...
 },
 "authenticationCertificate": {
  ...
 },
 "nonRepudiationCertificate": {
  ...
 },
 "intermediateCertificates": {
  ...
 },
 "encryptionCertificate": {
  ...
 }
}
```

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

```javascript
// filter entries := ["authentication-certificate","non-repudiation-certificate","root-certificates"];
var filter = ['authentication-certificate'];
client.luxeid(reader_id, pin, pinType).allCerts({ filters: filter, parseCerts: true }, callback);
```

Response:

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

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

```javascript
var filter = ['root-certificates','authentication-certificate','non-repudiaton-certificate'];
client.luxeid(reader_id, pin, pinType).allCertificates({ filters: filter, parseCerts: false }, callback);
```

Response:

```javascript
{
 "rootCertificate": {
  ...
 },
 "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

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="
}
client.luxeid(reader_id, pin, pinType).sign(data, callback);
```

Response is a base64 encoded signed hash:

```javascript
{
  "success": true,
  "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}
```

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

```
This is sample text to demonstrate siging with Luxembourg eID
```

You can use the following online tool to calculate the SHA256: [calculate SHA256](http://www.xorbin.com/tools/sha256-hash-calculator)

Hexadecimal result:

```
135b870026cfbe12dec348069811fcde5bed28800ac54dbf45ecdf04eb13e95b
```

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: [hex to base64 converter](http://tomeko.net/online_tools/hex_to_base64.php?lang=en)

Base64-encoded result:

```
E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=
```

Now we can sign the data:

```javascript
var data = {
      "pin":"...",
      "algorithm":"sha256",
      "data":"E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs="
}
client.luxeid(reader_id, pin, pinType).sign(data, callback);
```

Result:

```javascript
{
  "data": "C7SG5eix1+lzMcZXgL0bCL+rLxKhd8ngrSj6mvlgooWH7CloEU13Rj8QiQHdhHnZgAi4Q0fCMIqAc4dn9uW9OP+MRitimRpYZcaDsGrUehPi/JpOD1e+ko7xKZ67ijUU4KTmG4HXc114oJ7xxx3CGL7TNFfvuEphLbbZa+9IZSSnYDOOENJqhggqqu7paSbLJrxC2zaeMxODKb5WSexHnZH6NnLPl2OmvPTYtxiTUMrLbFRsDRAziF6/VQkgM8/xOm+1/9Expv5DSLRY8RQ+wha6/nMlJjx50JszYIj2aBQKp4AOxPVdPewVGEWF4NF9ffrPLrOA2v2d7t5M4q7yxA==",
  "success": true
}
```

### 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
}
luxidClient.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

## 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":"..."
}
client.luxeid(reader_id, pin, pinType).verifyPin(data, callback);
```

Response:

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

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

```javascript
  $("#buttonValidate").on('click', function () {
      var _body={};
      _body.pin = $("#psw").val(); //only when no pin-pad available
      var luxeid = client.luxeid(reader_id, pin, pinType));
      luxeid.verifyPin(_body, validationCallback);
  });
```

Note that, when the user has at least one retry left,entering a correct PIN resets the `PIN retry status`.

For more information about the error codes you can check the [Error codes page](https://t1t.gitbook.io/t1c-js-guide-v3/3.6.x/core/status-codes)

## Authentication

The T1C 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="
  }
  client.luxeid(reader_id, pin).authenticate(data, callback);
  ```

  Response:

  ```javascript
  {
  "success": true,
  "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
  }
  ```

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

```
The calculated digest of the hash is prefixed with:
DigestInfo ::= SEQUENCE {
      digestAlgorithm AlgorithmIdentifier,
      digest OCTET STRING
  }
Make sure this has been taken into consideration in order to validate the signature in a backend process.
```

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

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

The error object returned:

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

For the error codes and description, see [Status codes](https://t1t.gitbook.io/t1c-js-guide-v3/3.6.x/token/broken-reference).