The LuxTrust smartcard container facilitates communication with card readers with inserted LuxTrust smartcards and LuxTrust Signing Sticks. 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 LuxTrust smartcard - which is a PKI container
Interface Summary
The Abstract LuxTrust smartcard interface is summarized in the following snippet:
Additional Remarks
The LuxTrust Signing Stick can be seen as an smartcard integrated in an USB smartcard reader. The use cases described in this wiki are valid for both LuxTrust smartcards as LuxTrust Signing Stick, as there a no technical implementation differences.
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: .
For demonstration purpose we'll add a simple console output callback, which we'll use throughout the documentation.
Just as an example, we instantiate a new gcl (local client) and ask for all connected smart card readers:
This will returns us all connected readers:
In the example you'll notice that we are using a dual interface uTrust reader and a card has been inserted.
The reader id 'c8d31f8fed44d952' can be used as parameter in the next steps in order to select a smartcard reader for the functionality we want to execute. The pinpad property can be used to decided whether to pass the pin property to the reader (e.g. when verifying the pin).
Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:
Authentication certificate
T1C-JS will return the raw base64 certificate, optionally it can also return an object representing the certificate as parsed by . To enable parsing, parseCerts must be set to true.
The root and intermediate certificates are both stored as root certificates.
Certificate Chain
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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':
Response:
Data can be signed using the LuxTrust smartcard and Signing Stick. To do so, the T1C-GCL facilitates in:
Retrieving the certificate chain (root, intermediate and non-repudiation certificate)
Perform a sign operation (private key stays on the smart card)
To get the certificates necessary for signature validation in your back-end:
Response:
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:
Without a pinpad reader
With a pinpad reader
Response is a base64 encoded signed hash:
The 'authentication_reference' property can contain the following values: sha1 and sha256.
Avoid using SHA-1: is deprecated on the interface and will not be available in the future
The LuxTrust smartcard and Signing Stick is not supporting SHA512 at the moment.
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.
For example, we want the following text to be signed using sha256:
You can use the following online tool to calculate the SHA256:
Hexadecimal result:
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:
Base64-encoded result:
Now we can sign the data (remove the pin property for pinpad readers):
Result:
When the web or native application is responsible for showing the password input, the following request is used to verify a card holder PIN:
Without a pinpad reader
With a pinpad reader
Response:
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:
Without a pinpad reader
With a pinpad reader
Response:
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 and sha256.
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 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:
The error object returned:
For the error codes and description, see ..
