Portugese eID
The Portugese eID container facilitates communication with card readers with inserted Portugese 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 Portugese eID container on the T1C-GCL (Generic Connector Library).

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
});
Get the Portugese eID container service:
var pteid = gclClient.pteid(reader_id);
Call a function for the Portugese eID container:
function callback(err,data) {
if(err){console.log("Error:",JSON.stringify(err, null, ' '));}
else {console.log(JSON.stringify(data, null, ' '));}
}
pteid.rnData(callback);

The constructor for the Portugese 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);
This function call returns:
{
"data": [
{
"card": {
"atr": "3B9813400AA503010101AD1311",
"description": ["Portugese eID Card"]
},
"id": "57a3e2e71c48cee9",
"name": "Bit4id miniLector",
"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 Bit4id miniLector, has no pin-pad capabilities, and there is a card detected with given ATR and description "Portugese 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 Portugese eID card. This must be done upon instantiation of the Portugese eID container:
var pteid = gclClient.pteid(reader_id);
All methods for pteid will use the selected reader - identified by the reader_id.

The card holder is the person identified using the Portugese 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).

Contains all card holder related data, excluding the card holder address and photo. The service can be called:
gclClient.pteid(reader_id).idData(callback);
An example callback:
function callback(err,data) {
if(err){
console.log("Error:",JSON.stringify(err, null, ' '));
}
else {
console.log(JSON.stringify(data, null, ' '));
}
}
Response:
{
"data": {
"accidental_indications": "Sem ID Esq;Sem ID Dta",
"civilian_number": "990001822",
"country": "PRT",
"date_of_birth": "19 08 1960",
"document_number": "99000182 2 ZZ2",
"document_number_pan": "9999000000026918",
"document_type": "Cartão de Cidadão",
"document_version": "001.001.11",
"gender": "F",
"given_name_father": "Carlos",
"given_name_mother": "Maria",
"health_no": "898765392",
"height": "1,68",
"issuing_entity": "República Portuguesa",
"local_of_request": "AMA",
"mrz1": "I<PRT990001822<ZZ29<<<<<<<<<<<",
"mrz2": "6008190F1610316PRT<<<<<<<<<<<8",
"mrz3": "REVOGADO<<ANA<<<<<<<<<<<<<<<<<",
"name": "Ana",
"nationality": "PRT",
"photo": "base64 encoded photo data",
"raw_data": "base64 encoded raw data",
"social_security_no": "11999999960",
"surname": "Revogado",
"surname_father": "Revogado",
"surname_mother": "Revogado",
"tax_no": "399990046",
"validity_begin_date": "08 04 2013",
"validity_end_date": "31 10 2016"
},
"success": true
}

Reading all the id data with the photo can be slow as the photo contains a lot of data. If only the data is required, the service can be called to read the id data without the photo.
gclClient.pteid(reader_id).idDataWithOutPhoto(callback);
Response:
{
"data": {
"accidental_indications": "Sem ID Esq;Sem ID Dta",
"civilian_number": "990001822",
"country": "PRT",
"date_of_birth": "19 08 1960",
"document_number": "99000182 2 ZZ2",
"document_number_pan": "9999000000026918",
"document_type": "Cartão de Cidadão",
"document_version": "001.001.11",
"gender": "F",
"given_name_father": "Carlos",
"given_name_mother": "Maria",
"health_no": "898765392",
"height": "1,68",
"issuing_entity": "República Portuguesa",
"local_of_request": "AMA",
"mrz1": "I<PRT990001822<ZZ29<<<<<<<<<<<",
"mrz2": "6008190F1610316PRT<<<<<<<<<<<8",
"mrz3": "REVOGADO<<ANA<<<<<<<<<<<<<<<<<",
"name": "Ana",
"nationality": "PRT",
"raw_data": "base64 encoded raw data",
"social_security_no": "11999999960",
"surname": "Revogado",
"surname_father": "Revogado",
"surname_mother": "Revogado",
"tax_no": "399990046",
"validity_begin_date": "08 04 2013",
"validity_end_date": "31 10 2016"
},
"success": true
}

Contains the card holder's photo stored on the smart card. The service can be called:
gclClient.pteid(reader_id).photo(callback);
Response:
{
"data": "/9j/4AAQSkZJRgABA...59aVpcklSDzyKUTEDGK//9k=",
"success": true
}

Contains the card holders address stored on the smart card. The information is proctected by the address PIN code. The service can be called:

var data = {}
gclClient.pteid(reader_id).address(data, callback);

var data = {
"pin": "...."
}
gclClient.pteid(reader_id).address(data, callback);
Response:
{
"data": {
"abbr_building_type": "",
"abbr_street_type": "AV",
"building_type": "",
"civil_parish": "110623",
"civil_parish_description": "Nossa Senhora de Fátima",
"district": "11",
"district_description": "Lisboa",
"door_no": "202",
"floor": "",
"gen_address_num": "200801",
"is_national": true,
"locality": "Lisboa",
"municipality": "1106",
"municipality_description": "Lisboa",
"place": "",
"postal_locality": "LISBOA",
"raw_data": "TgBQVAAAMTEAAExpc2JvYQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAxMTA2AAAAAExpc2JvYQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAxMTA2MjMAAAAAAABOb3NzYSBTZW5ob3JhIGRlIEbDoXRpbWEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQVYAAAAAAAAAAAAAAAAAAAAAAABBdmVuaWRhAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAANSBkZSBPdXR1YnJvAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAyMDIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAExpc2JvYQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAxMDUwAAAAADA2NQAAAExJU0JPQQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMjAwODAxAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"side": "",
"street_name": "5 de Outubro",
"street_type": "Avenida",
"type": "N",
"zip3": "065",
"zip4": "1050"
},
"success": true
}

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.

TODO

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:
gclClient.pteid(reader_id).rootCertificate({ parseCerts: true }, callback);
Response:
{
"data": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"success": true
}

Contains the 'root authentication certificate' stored on the smart card. The 'root authenticate certificate' is used to sign the 'authenticate certificate'. The service can be called:
gclClient.pteid(reader_id).rootAuthenticationCertificate({ parseCerts: true }, callback);
Response:
{
"data": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"success": true
}

Contains the root non-repudiation certificate stored on the smart card. The 'root non-repudiation certificate' is used to sign the 'non-repudiation certificate'. The service can be called:
gclClient.pteid(reader_id).rootNonRepudiationCertificate({ parseCerts: true }, callback);
Response:
{
"data": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"success": true
}

Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding the private RSA authentication key. The service can be called:
gclClient.pteid(reader_id).authenticationCertificate({ parseCerts: true }, callback);
Response:
{
"data": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"success": true
}

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:
gclClient.pteid(reader_id).nonRepudiationCertificate({ parseCerts: true }, callback);
Response:
{
"data": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"success": true
}

All data on the smart card can be dumped at once, or using a filter. In order to read all data at once:
var filter = [];
gclClient.pteid(reader_id).allData({ filters: filter, parseCerts: true }, callback);
Response:
{
"data": {
"id": {
"accidental_indications": "Sem ID Esq;Sem ID Dta",
"civilian_number": "990001822",
"country": "PRT",
"date_of_birth": "19 08 1960",
"document_number": "99000182 2 ZZ2",
"document_number_pan": "9999000000026918",
"document_type": "Cartão de Cidadão",
"document_version": "001.001.11",
"gender": "F",
"given_name_father": "Carlos",
"given_name_mother": "Maria",
"health_no": "898765392",
"height": "1,68",
"issuing_entity": "República Portuguesa",
"local_of_request": "AMA",
"mrz1": "I<PRT990001822<ZZ29<<<<<<<<<<<",
"mrz2": "6008190F1610316PRT<<<<<<<<<<<8",
"mrz3": "REVOGADO<<ANA<<<<<<<<<<<<<<<<<",
"name": "Ana",
"nationality": "PRT",
"photo": "base64 encoded photo data",
"raw_data": "base64 encoded raw data",
"social_security_no": "11999999960",
"surname": "Revogado",
"surname_father": "Revogado",
"surname_mother": "Revogado",
"tax_no": "399990046",
"validity_begin_date": "08 04 2013",
"validity_end_date": "31 10 2016"
},
"authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"non_repudiation_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_non_repudiation_certificate": {
"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':
var filter = ['id','root-authentication-certificate'];
gclClient.pteid().allData({ filters: filter, parseCerts: true }, callback);
Response:
{
"data": {
"id": {
"accidental_indications": "Sem ID Esq;Sem ID Dta",
"civilian_number": "990001822",
"country": "PRT",
"date_of_birth": "19 08 1960",
"document_number": "99000182 2 ZZ2",
"document_number_pan": "9999000000026918",
"document_type": "Cartão de Cidadão",
"document_version": "001.001.11",
"gender": "F",
"given_name_father": "Carlos",
"given_name_mother": "Maria",
"health_no": "898765392",
"height": "1,68",
"issuing_entity": "República Portuguesa",
"local_of_request": "AMA",
"mrz1": "I<PRT990001822<ZZ29<<<<<<<<<<<",
"mrz2": "6008190F1610316PRT<<<<<<<<<<<8",
"mrz3": "REVOGADO<<ANA<<<<<<<<<<<<<<<<<",
"name": "Ana",
"nationality": "PRT",
"photo": "base64 encoded photo data",
"raw_data": "base64 encoded raw data",
"social_security_no": "11999999960",
"surname": "Revogado",
"surname_father": "Revogado",
"surname_mother": "Revogado",
"tax_no": "399990046",
"validity_begin_date": "08 04 2013",
"validity_end_date": "31 10 2016"
},
"root_authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
}
},
"success": true
}

All certificates on the smart card can be dumped at once, or using a filter. In order to read all certificates at once:
var filter = [];
gclClient.pteid(reader_id).allCerts({ filters: filter, parseCerts: true }, callback);
Response:
{
"data": {
"authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"non_repudiation_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_non_repudiation_certificate": {
"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 'root-certificate' and the 'rrn-certificate':
var filter = ['root-certificate','authentication-certificate'];
gclClient.pteid(reader_id).allCerts({ filters: filter, parseCerts: true }, callback);
Response:
{
"data": {
"authentication_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
},
"root_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==",
"parsed": { // parsed certificate object }
}
},
"success": true
}

Data can be signed using the Portugese eID smart card. To do so, the T1C-GCL facilitates in:
  • Retrieving the certificate chain (root-certificate, root-non-repudiation 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:
var filter = ['root_certificate','root_non_repudiation_certificate','non_repudiaton_certificate'];
gclClient.pteid(reader_id).allCertificates({ filters: filter, parseCerts: false }, callback);
Response:
{
"non_repudiation_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg=="
},
"citizen_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg=="
},
"root_certificate": {
"base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg=="
},
}
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'.

When the web or native application is responsible for showing the password input, the following request is used to sign a given hash:
var data = {
"pin":"...",
"algorithm_reference":"sha1",
"data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
gclClient.pteid(reader_id).signData(data, callback);
Response is a base64 encoded signed hash:
{
"success": true,
"data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}
The 'authenticationreference' property can contain the following values: md5, sha1 and sha256.

When the pin entry is done on the pin-pad, the following request is used to sign a given hash:
var data = {
"algorithm_reference":"sha1",
"data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
gclClient.pteid(reader_id).signData(data, callback);
Response is a base64 encoded signed hash:
{
"success": true,
"data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}
The 'algorithm_reference' property can contain the following values: md5, sha1 and sha256.
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.

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 Portugese eID
You can use the following online tool to calculate the SHA256: calculate SHA256
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
Base64-encoded result:
E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=
Now we can sign the data:
var data = {
"pin":"...",
"algorithm_reference":"sha256",
"data":"E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs="
}
gclClient.pteid(reader_id).signData(data, callback);
Result:
{
"data": "C7SG5eix1+lzMcZXgL0bCL+rLxKhd8ngrSj6mvlgooWH7CloEU13Rj8QiQHdhHnZgAi4Q0fCMIqAc4dn9uW9OP+MRitimRpYZcaDsGrUehPi/JpOD1e+ko7xKZ67ijUU4KTmG4HXc114oJ7xxx3CGL7TNFfvuEphLbbZa+9IZSSnYDOOENJqhggqqu7paSbLJrxC2zaeMxODKb5WSexHnZH6NnLPl2OmvPTYtxiTUMrLbFRsDRAziF6/VQkgM8/xOm+1/9Expv5DSLRY8RQ+wha6/nMlJjx50JszYIj2aBQKp4AOxPVdPewVGEWF4NF9ffrPLrOA2v2d7t5M4q7yxA==",
"success": true
}
Note: If you want to convert a binary signed hash to HEX (for development) you can use for example an online hexdump tool:

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.pteid(reader_id).verifyPin(data, callback);
Response:
{
"success": true
}

When the pin entry is done on the pin-pad, the following request is used to verify a given PIN:
var data = {}
gclClient.pteid(reader_id).verifyPin(data, callback);
Response:
{
"success": true
}

In order to inform a user upon the PIN retries left, the Portugese 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 available
var pteid = connector.pteid(reader_id);
pteid.verifyPin(_body, validationCallback);
});
The following error message will be returned when PIN is wrong:
{
"code": 103,
"description": "Wrong pin, 2 tries remaining",
"success": false
}
After a second wrong PIN verification:
{
"code": 104,
"description": "Wrong pin, 1 try remaining",
"success": false
}
Note that, when the user has at least one retry left,entering a correct PIN resets the PIN retry status.
Code
Description
103
Warning: the user can try twice more to verify his PIN
104
Warning: the user has only 1 retry left, after this the PIN must be reset at the local municipally
105
Error: the PIN is blocked, the PIN must be reset at the local municipally

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.

An external challenge on a non-pinpad reader is provided in the data property of the following example:
var data = {
"pin": "...",
"algorithm_reference": "sha1",
"data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
gclClient.pteid(reader_id).authenticate(data, callback);
Response:
{
"success": true,
"data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}
The 'algorithm_reference' property can contain the following values: md5, sha1 and sha256.

An external challenge on a pinpad reader is provided in the data property of the following example:
var data = {
"algorithm_reference": "sha1",
"data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E="
}
gclClient.pteid(reader_id).authenticate(data, callback);
Response:
{
"success": true,
"data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="
}
The 'algorithm_reference' property can contain the following values: md5, sha1 and sha256.

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.

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:
function callback(err,data) {
if(err){
console.log("Error:",JSON.stringify(err, null, ' '));
}
else {
console.log(JSON.stringify(data, null, ' '));
}
}
The error object returned:
{
success: false,
description: "some error description",
code: "some error code"
}
For the error codes and description, see Status codes.
Copy link
On this page
Get Portugese eID container object
Obtain the Reader-ID
Cardholder Information
IdData
IdData without photo
Photo
Address
Certificates
Certificate Chain
Root Certificate
Root Authentication Certificate
Root Non-repudiation Certificate
Authentication Certificate
Non-repudiation Certificate
Data Filter
Filter Card Holder Data
Filter Certificates
Sign Data
Sign Hash without pin-pad
Sign Hash with pin-pad
Calculate Hash
Verify PIN
Verify PIN without pin-pad
Verify PIN with pin-pad
Verify PIN - retries left
Authentication
External Challenge without pinpad
External Challenge with pinpad
Generated Challenge
Error Handling
Error Object