# Spanish DNIe The Spanish DNIe container facilitates communication with card readers with inserted Spanish DNIe (DNIe electrónico) smart card. The T1C-JS client library provides function to communicate with the smart card and facilitates integration into a web or native applications.\ At the moment the container supports DNIe and DNIE 3.0 cards. **References** The most relevant specifications and standards are: * ISO/IEC 7816-4 * ISO/IEC 7816-8 * ISO/IEC 7816-9 * CWA-14890-1 Official document describing the DNie (in spanish) * [Manual de Comandos del DNIe](https://www.dnielectronico.es/PDFs/Manual_de_Comandos_para_Desarrolladores_102.pdf) This document describes the functionality provided by the Spanish DNIe container on the T1C-GCL (Generic Connector Library). ## Interface Summary The Abstract DNIe smartcard interface is summarized in the following snippet: ```javascript interface AbstractDnie{ allData({ filters: string[], parseCerts: boolean }, callback?: (error: RestException, data: AllDataResponse) => void): void | Promise; allCerts({ filters: string[], parseCerts: boolean }, callback?: (error: RestException, data: AllCertsResponse) => void): void | Promise; info(callback?: (error: RestException, data: InfoResponse) => void): void | Promise intermediateCertificate({ parseCerts: boolean }, callback?: (error: RestException, data: DataResponse) => void): void | Promise; authenticationCertificate({ parseCerts: boolean }, callback?: (error: RestException, data: DataResponse) => void): void | Promise; signingCertificate({ parseCerts: boolean }, callback?: (error: RestException, data: DataResponse) => void): void | Promise; authenticate: (body: any, callback: () => void) => void | Promise signData: (body: any, callback: () => void) => void | Promise verifyPin: (body: OptionalPin, callback?: () => void) => void | Promise } ``` ## Retrieve a connected card reader In order to start with any use case, we need to select a card reader. The targeted reader will be passed as a parameter to the subsequent methods provided. This is part of the core Trust1Connector functionality. More information about core service functionality can be found on the following page: [Core Services](/t1c-js-guide/core/core-services.md). For demonstration purpose we'll add a simple console output callback, which we'll use throughout the documentation. ```javascript function callback(err,data) { if(err){console.log("Error:",JSON.stringify(err, null, ' '));} else {console.log(JSON.stringify(data, null, ' '));} ``` Just as an example, we instantiate a new gcl (local client) and ask for all connected smart card readers: ```javascript GCLLib.GCLClient.initialize(config, function(err, gclClient) { gclClient.core().readers(callback); }); ``` This will returns us all connected readers: ```javascript { "data": [ { "card": { "atr": "3B7F380000006A444E496520024C340113039000", "description": [ "DNI electronico (Spanish electronic ID card)" ] }, "id": "fd74d09231051bdb", "name": "Precise Biometrics Sense MC", "pinpad": false } ], "success": true } ``` In the example you'll notice that we are using a Precise Biometrics Sense MC reader, and a card has been inserted. The reader id 'fd74d09231051bdb' can be used as parameter in the next steps in order to select a smartcard reader for the functionality we want to execute. ### RnData Contains all card holder related data. The service can be called: ```javascript gclClient.dnie(reader_id).info(callback); ``` Response: ```javascript { "data": { "info": { "firstLastName": "ESCOBAR", "firstName": "DIANA CAROLINA", "idesp": "AMF...0", "number": "5....L", "secondLastName": "MEJIA", "serialNumber": "8644....4" } }, "success": true } ``` or ```javascript var filter = ['info']; gclClient.dnie(reader_id).allData(filter,callback); ``` Response: ```javascript { "data": { "info": { "firstLastName": "ESCOBAR", "firstName": "DIANA CAROLINA", "idesp": "AMF...0", "number": "5....L", "secondLastName": "MEJIA", "serialNumber": "8644....4" } }, "success": true } ``` ## Certificates Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card: * Intermediate certificate * Signing certificate * Authentication 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`. ### Certificate Chain #### Intermediate Certificate Contains the 'root certificate' stored on the smart card.\ The service can be called: ```javascript gclClient.dnie(reader_id).intermediateCertificate({ parseCerts: true }, callback); ``` Response: ```javascript { "data": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "success": true } ``` ### 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 signing.\ The service can be called: ```javascript gclClient.dnie(reader_id).authenticationCertificate({ parseCerts: true }, callback); ``` Response: ```javascript { "data": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "success": true } ``` ### Signing 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 gclClient.dnie(reader_id).signingCertificate({ parseCerts: true }, callback); ``` Response: ```javascript { "data": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "success": true } ``` ## Data Filter ### Available Data Filters ### 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 = []; gclClient.dnie(reader_id).allCerts({ filters: filter, parseCerts: true }, callback); ``` Response: ```javascript { "data": { "authentication_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "intermediate_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "signing_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 'authentication\_certificate': ```javascript var filter = ['authentication-certificate','signing-certificate']; gclClient.dnie(reader_id).allCerts({ filters: filter, parseCerts: true }, callback); ``` Response: ```javascript { "data": { "intermediate_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } }, "signing_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==", "parsed": { // parsed certificate object } } }, "success": true } ``` ## Verify PIN #### Without a pinpad 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":"...", } gclClient.dnie(reader_id).verifyPin(data, callback); ``` Response: ```javascript { "success": true } ``` #### With a pinpad When the pin entry is done on the pin-pad, the following request is used to verify a card holder PIN: ```javascript var data = {} gclClient.dnie(reader_id).verifyPin(data, callback); ``` Response: ```javascript { "success": true } ``` ## Sign Data Data can be signed using the Spanish DNIe smartcard. To do so, the T1C-GCL facilitates in: * Retrieving the certificate chain (intermediate and signing 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 = []; gclClient.dnie(reader_id).allCertificates({ filters: filter, parseCerts: false }, callback); ``` Response: ```javascript { "data": { "authentication_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==" }, "intermediate_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==" }, "signing_certificate": { "base64": "MIIFjjCCA3agAwI...rTBDdrlEWVaLrY+M+xeIctrC0WnP7u4xg==" } }, "success": true } ``` 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 a pinpad 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_reference":"sha1", "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" } gclClient.dnie(reader_id).signData(data, callback); ``` Response is a base64 encoded signed hash: ```javascript { "success": true, "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q=" } ``` #### With a pinpad When the pin entry is done on the pin-pad, the following request is used to sign a given hash: ```javascript var data = { "algorithm_reference":"sha1", "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" } gclClient.dnie(reader_id).signData(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 'algorithm\_reference' property can contain the following values: sha1 (sha256 is supposed to be supported as well). 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: sha1, sha256 and sha512.\ For example, we want the following text to be signed using: ``` This is sample text to demonstrate siging with Aventra smartcard ``` You can use the following online tool to calculate the SHA1: Hexadecimal result: ``` OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ== ``` Notice that the length of the SHA1 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: ``` OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ== ``` Now we can sign the data: ```javascript var data = { "pin":"...", "algorithm_reference":"sha1", "data":"OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ==" } gclClient.dnie(reader_id).signData(data, callback); ``` Result: ```javascript { "data": "C7SG5eix1+lzMcZXgL0bCL+rLxKhd8ngrSj6mvlgooWH7CloEU13Rj8QiQHdhHnZgAi4Q0fCMIqAc4dn9uW9OP+MRitimRpYZcaDsGrUehPi/JpOD1e+ko7xKZ67ijUU4KTmG4HXc114oJ7xxx3CGL7TNFfvuEphLbbZa+9IZSSnYDOOENJqhggqqu7paSbLJrxC2zaeMxODKb5WSexHnZH6NnLPl2OmvPTYtxiTUMrLbFRsDRAziF6/VQkgM8/xOm+1/9Expv5DSLRY8RQ+wha6/nMlJjx50JszYIj2aBQKp4AOxPVdPewVGEWF4NF9ffrPLrOA2v2d7t5M4q7yxA==", "success": 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 #### Without a pinpad An external challenge is provided in the data property of the following example: ```javascript var data = { "pin": "...", "algorithm_reference": "sha1", "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" } gclClient.dnie(reader_id).authenticate(data, callback); ``` Response: ```javascript { "success": true, "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q=" } ``` #### Without a pinpad An external challenge is provided in the data property of the following example: ```javascript var data = { "algorithm_reference": "sha1", "data":"I2e+u/sgy7fYgh+DWA0p2jzXQ7E=" } gclClient.dnie(reader_id).authenticate(data, callback); ``` Response: ```javascript { "success": true, "data": "W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q=" } ``` The 'algorithm\_reference' property can contain the following values: sha1 (sha256 is supposed to be supporeted as well). ### 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](/t1c-js-guide/core/status-codes.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://t1t.gitbook.io/t1c-js-guide/containers/eid/spanish-dnie.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.