LuxTrust Smartcard and Signing Stick

The LuxTrust smartcard container facilitates communication with card readers with inserted LuxTrust smartcards and LuxTrust Signing Sticks. The T1C-JLIB client library provides function to communicate with the smart card and facilitates integration into a native or Java application. This document describes the functionality provided by the LuxTrust smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library).

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.

Get LuxTrust container object

For more information on how to configure the T1C-JLIB client library see Client Configuration. Initialize a T1cClient:

LibConfig conf = new LibConfig();
conf.setEnvironment(Environment.DEV);
conf.setDsUri(DS_URI);
conf.setOcvUri(OCV_URI);
conf.setGclClientUri(URI_T1C_GCL);
conf.setApiKey(API_KEY);
conf.setHardwarePinPadForced(false);
conf.setDefaultPollingIntervalInSeconds(5);
conf.setDefaultPollingTimeoutInSeconds(10);
conf.setSessionTimeout(60);
T1cClient t1cClient = new T1cClient(conf);

Get the LuxTrust container service:

LuxTrustContainer container = t1cClient.getLuxTrustContainer(reader);

For demonstration purpose we will use the aforementioned callback, which only outputs the data and eventual error messages. During integration meaningful functionality should be provided.

Obtain the GclReader object

The constructor for the LuxTrust container expects a GclReader object as parameter. A GclReader 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:

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

This function call returns a list of the following objects:

com.t1t.t1c.GclReader

com.t1t.t1c.GclCard

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 "LuxTrust Card". An ATR (Answer To Reset) identifies the type of a smart-card. The container must be instantiated with the GclReader object containing the LuxTrust card and its PIN:

LuxTrustContainer container = t1cClient.getLuxTrustContainer(reader);

All methods for container will use the selected reader - identified by the reader object.

Card activation status

To request whether the card is in operational activated mode, the activated endpoint can be used:

LuxTrustContainer container = t1cClient.getLuxTrustContainer(reader);
boolean activated = container.isActivated();

Response:

java.lang.Boolean

Certificates

Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:

• Root certificates
• Intermediate certificate
• Authentication certificate
• Signing certificate

T1C-JLIB will return the raw base64 certificate, optionally it can also return an java.securtity.Certificate object representing the certificate. To enable parsing, parseCerts must be set to true.

The root and intermediate certificates are both stored as root certificates.

Certificate Chain

Root Certificates

Contains the 'root certificates' stored on the smart card. The root certificate is used to sign the 'intermediate certificate'.
The service can be called:

List<T1cCertificate> rootCertificates = container.getRootCertificates(true);

Response:

java.util.List<com.t1t.t1c.model.T1cCertificate>

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:

T1cCertificate authenticationCertificate = container.getAuthenticationCertificate(true);

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:

T1cCertificate signingCertificate = container.getSigningCertificate(true)

Response:

com.t1t.t1c.model.T1cCertificate

Data Filter

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:

LuxTrustAllCertificates certificates = container.getAllCertificates();

Response:

com.t1t.t1c.containers.smartcards.eid.lux.LuxIdAllData

The filter can be used to ask a list of custom data containers. For example, we want to read only the 'authenticationCertificate':

List<String> filter = Arrays.asList("authentication-certificate");
boolean parseCertificates = true;
LuxTrustAllCertificates certificates = container.getAllCertificates(filter, parseCertificates)

Sign Data

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)
• Return the signed hash

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

List<String> filters = Arrays.asList("root-certificates","authentication-certificate","signing-certificate");
boolean parseCertificates = true;
LuxTrustAllCertificates certificates = container.getAllCertificates(filter, parseCertificates);
// 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();

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

When the native or Java application is responsible for showing the password input, the following request is used to sign a given hash:

Without a pinpad reader

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

With a pinpad reader

String signedData = container.sign(
                //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: 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.

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. For example, we want the following text to be signed using SHA256:

This is sample text to demonstrate siging with LuxTrust smartcard or signing stick

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 (remove the pin property for pinpad readers):

String signedData = container.sign(
                //data
                "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
                //Digest algorithn
                DigestAlgorithm.SHA256,
                //Optional PIN
                "123456"
);

Result:

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

Verify PIN

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

Without a pinpad reader

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

With a pinpad reader

Boolean pinVerified = container.verifyPin();

Response:

java.lang.Boolean

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.

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

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

Without a pinpad reader

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

With a pinpad reader

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

Take notice that the PIN property can be omitted when using a smart card reader with pin-pad capabilities.
The 'algorithmReference' property can contain the following values: SHA1 and SHA256.

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).