Spanish DNIe

The Spanish DNIe container facilitates communication with card readers with inserted Spanish DNIe (DNIe electrónico) smart card. The T1C-JLIB client library provides function to communicate with the smart card and facilitates integration into a native or Java application. 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

This document describes the functionality provided by the Spanish DNIe container on the T1C-GCL (Generic Connector Library).

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.

Just as an example, we instantiate a new Client (local client) and ask for all connected smart card readers:

List<GclReader> reader = t1cClient.getCore().getReadersWithInsertedCard();

This function call returns a list of the following objects:

com.t1t.t1c.GclReader

com.t1t.t1c.GclCard

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.

Info

Contains all card holder related data.

The service can be called:

IDnieContainer container = t1cClient.getDnieContainer(reader.getId());
GclDnieInfo info = container.getInfo();

Response:

com.t1t.t1c.GclCard

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-JLIB will return the raw base64 certificate, optionally it can also return a java.security.cert.Certificate object representing the certificate. To enable parsing, parseCerts must be set to true.

Certificate Chain

Intermediate Certificate

Contains the 'intermediate certificate' stored on the smart card. The service can be called:

boolean parseCertificates = true;
T1cCertificate intermediateCertificate = container.getIntermediateCertificate(parseCertificates);

Response:

com.t1t.t1c.model.T1cCertificate

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:

boolean parseCertificates = true;
T1cCertificate authenticationCertificate = container.getAuthenticationCertificate(parseCertificates);

Response:

com.t1t.t1c.model.T1cCertificate

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:

boolean parseCertificates = true;
T1cCertificate signingCertificate = container.getSigningCertificate(parseCertificates);

Response:

com.t1t.t1c.model.T1cCertificate

Data Filter

Filter Card Holder Data

All data on the smart card can be dumped at once, or using a filter. In order to read all data at once:

DnieAllData allData = container.getAllData();

Response:

com.t1t.t1c.containers.smartcards.eid.dni.DnieAllData

The filter can be used to ask a list of custom data containers. A list of available filters can be retrieved with the getAllDataFilters() method. For example, we want to read only the 'info' and 'intermediate certificate':

List<String> filters = Arrays.asList("intermediate-certificate","info");
// or to get a list of available filters
filters = container.getAllDataFilters();
boolean parseFilters = true;
DnieAllData allData = container.getAllData(filters, 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:

DnieAllCertificates allCerts = container.getAllCertificates();

Response:

com.t1t.t1c.containers.smartcards.eid.dni.DnieAllCertificates

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

List<String> filters = Arrays.asList("authentication-certificate","signing-certificate");
boolean parseCertificates = true;
DnieAllCertificates allCerts = container.getAllCertificates(filters, parseCertificate);

Response:

com.t1t.t1c.containers.smartcards.eid.dni.DnieAllCertificates

Verify PIN

Verify PIN without pin-pad

When the native or Java application is responsible for showing the password input, the following request is used to verify a card holder PIN:

Boolean pinVerified = container.verifyPin("1234");

Response:

java.lang.Boolean

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:

Boolean pinVerified = container.verifyPin();

Response:

java.lang.Boolean

Verify PIN - retries left

After an unsuccesfull PIN verification, the container will throw a com.t1t.t1c.exceptions.VerifyPinException

 Boolean pinVerified = container.verifyPin("1235");

The following exception will be thrown when PIN is wrong:

com.t1t.t1c.exceptions.VerifyPinException

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

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:

DnieAllCertificates allCertificates = container.getAllCertificates();
// Or directly retrieve the signing certificate chain in the form of Map<Integer, T1cCertificate>. The leaf certificate will always have 0 as key
Map<Integer, T1cCertificate> signingCertificateChain = container.getSigningCertificateChain();

Response:

com.t1t.t1c.containers.smartcards.eid.dni.DnieAllCertificates

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 native or Java application is responsible for showing the password input, the following request is used to sign a given hash:

String signedData = container.authenticate(
                //data
                "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
                //Digest algorithn
                DigestAlgorithm.SHA256,
                //Optional PIN
                "1234"
);

Response is a String representation of a base64 encoded signed hash:

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

String signedData = container.authenticate(
                //data
                "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
                //Digest algorithn
                DigestAlgorithm.SHA256
);

Response is a base64 encoded signed hash:

"W7wqvWA8m9SBALZPxN0qUCZfB1O/WLaM/silenLzSXXmeR+0nzB7hXC/Lc/fMru82m/AAqCuGTYMPKcIpQG6MtZ/SGVpZUA/71jv3D9CatmGYGZc52cpcb7cqOVT7EmhrMtwo/jyUbi/Dy5c8G05owkbgx6QxnLEuTLkfoqsW9Q="

The 'algorithmReference' property can contain the following values: DigestAlgorithm.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 algorithmReference property provided in the sign request.
The algorithmReference 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 DNIE smartcard

You can use the following online tool to calculate the SHA1: http://www.sha1-online.com

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

Base64-encoded result:

OTY4ODM2ODg3ODg3YWViYzdlZDBiMDgwMjQxZGQ5N2M4N2ZlMWRhZQ==

Now we can sign the data:

String signedData = container.authenticate(
                //data
                "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
                //Digest algorithn
                DigestAlgorithm.SHA256,
                //Optional PIN
                "1234"
);

Result:

"C7SG5eix1+lzMcZXgL0bCL+rLxKhd8ngrSj6mvlgooWH7CloEU13Rj8QiQHdhHnZgAi4Q0fCMIqAc4dn9uW9OP+MRitimRpYZcaDsGrUehPi/JpOD1e+ko7xKZ67ijUU4KTmG4HXc114oJ7xxx3CGL7TNFfvuEphLbbZa+9IZSSnYDOOENJqhggqqu7paSbLJrxC2zaeMxODKb5WSexHnZH6NnLPl2OmvPTYtxiTUMrLbFRsDRAziF6/VQkgM8/xOm+1/9Expv5DSLRY8RQ+wha6/nMlJjx50JszYIj2aBQKp4AOxPVdPewVGEWF4NF9ffrPLrOA2v2d7t5M4q7yxA==",

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.

To get the certificates necessary for signature validation in your back-end:

// The leaf certificate will always have 0 as key
Map<Integer, T1cCertificate> signingCertificateChain = container.getAuthenticationCertificateChain();

External Challenge

Without a pinpad

An external challenge is provided in the data property of the following example:

String authenticatedData = container.authenticate(
                //data
                "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
                //Digest algorithn
                DigestAlgorithm.SHA256,
                //Optional PIN
                "1234"
);

Response:

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

String authenticatedData = container.authenticate(
                //data
                "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
                //Digest algorithn
                DigestAlgorithm.SHA256
);

Response:

"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 Java library.
In order to do so, an additional contract must be provided with the 'OCV API' (Open Certificate Validation API).