The Belgian eID container facilitates communication with card readers with inserted Belgian eID smart card. The T1C-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 Belgian eID container on the T1C-GCL (Generic Connector Library).
Get Belgian eID container object
For more information on how to configure the T1C-JS client library see Client Configuration.
Initialize a gclClient:
GCLLib.GCLClient.initialize(config,function(err, gclClient) {// gclClient ready to use});
The constructor for the Belgian eID 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.
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:
var core =gclClient.core();core.readersCardAvailable(callback);
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 Bit4id miniLector, has no pin-pad capabilities, and there is a card detected with given ATR and description "Belgian eID Card".
An ATR (Answer To Reset) 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 Belgian eID card.
This must be done upon instantiation of the Belgian eID container:
var beid =gclClient.beid(reader_id);
All methods for beid will use the selected reader - identified by the reader_id.
Cardholder Information
The card holder is the person identified using the Belgian 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).
RnData
Contains all card holder related data, excluding the card holder address and photo.
The service can be called:
Exposes all the certificates publicly available on the smart card.
T1C-JS will return the raw base64 certificate, optionally it can also return an object representing the certificate as parsed by PKI.js. To enable parsing, parseCerts must be set to true.
Certificate Chain
Root Certificate
Contains the 'root certificate' stored on the smart card. The root certificate is used to sign the 'citizen CA certificate'.
The service can be called:
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.
The service can be called:
Contains the citizen certificate stored on the smart card. The 'citizen certificate' is used to sign the 'authentication certificate' and the 'non-repudiation certificate'.
The service can be called:
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:
Contains the 'rrn certificate' stored on the smart card. The 'rrn certificate' corresponds to the private key used to sign the 'Rn' and 'Address' data.
The service can be called:
The 'algorithm_reference' property can contain the following values: sha1, sha256, sha512, md5.
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.
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 Belgian eID
You can use the following online tool to calculate the SHA256: calculate SHA256
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
Base64-encoded result:
E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=
Now we can sign the data:
var data = {"pin":"...","algorithm_reference":"sha256","data":"E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs="}gclClient.beid(reader_id).signData(data, callback);
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":"..."}gclClient.beid(reader_id).verifyPin(data, callback);
Response:
{"success": 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:
var data = {}gclClient.beid(reader_id).verifyPin(data, callback);
Response:
{"success": true}
Verify PIN - retries left
In order to inform a user upon the PIN retries left, the Belgian eID doesn't provide a request to retrieve this information. After an unsuccesfull PIN verification, the error code indicates the number of retries left. For example, when executuing:
$("#buttonValidate").on('click',function () {var _body={};_body.pin =$("#psw").val(); //only when no pin-pad availablevar beid =connector.beid(reader_id);beid.verifyPin(_body, validationCallback); });
The following error message will be returned when PIN is wrong:
Note that, when the user has at least one retry left,entering a correct PIN resets the PIN retry status.
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:
var data = {"pin":"...","algorithm_reference":"sha1","data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="}gclClient.beid(reader_id).authenticate(data, callback);
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: