Generic Interface

Introduction

For user convenience, the Trust1Connector exposes a number of methods that make abstraction of the containers. It allows users to discover readers that are ready to do a certain action (authenticate/sign data/verify pin).

Once a suitable reader is found, the user can perform the desired action with a single call. Internally, the T1C-JLIB will check the type of card in the reader and use the appropriate container to perform the requested action.

Interface Summary

Method Details

getAllDataClass

Will return the implementation classof the AllData marker interface for the current container.

getAllCertificatesClass

Will return the implementation class of the AllCertificates marker interface for the current container.

getAllDataFilters

Will return a list of available filters for the getAllData method.

getAllCertificatesFilters

Will return a list of available filters for the getAllCertificates method.

getAllData

Will return a container specific object containing all of the available card data. The object will have the implementation class from the getAllDataClass method. It is possible to pass a list of filter Strings to filter the returned data. It is also possible to pass a Boolean argument denoting whether or not the certificates, if present, will be parsed to a java.security.cert.Certificate object.

getAllCertificates

Will return a container specific object containing all of the available card certificates. The object will have the implementation class from the getAllCertificatesClass method. It is possible to pass a list of filter Strings to filter the returned data. It is also possible to pass a Boolean argument denoting whether or not the certificates, if present, will be parsed to a java.security.cert.Certificate object.

dumpData

This method will return all available data from the card. Which data is present depends on the card type, but this will always take the following form:

com.t1t.t1c.containers.smartcards.ContainerData

authenticate

Calling this method with a readerId and a data object containing data to be authenticated (and optional pincode) will trigger the following actions:

1. T1C-JLIB will check if a reader with readerId is found
2. T1C-JLIB checks if there is a card in the reader
3. If there is a card, it determines the container to be used for communication
4. Once the container is determined, it checks if this container supports the requested operation
5. If supported, check if the container is available in the local installation
6. If available, the authenticate method of the appropriate container is called and data is passed along
7. The data returned from the authenticate call is returned via callback/Promise

If the container is a secured certificate card, an additional PIN parameter is required to access the card data.

sign

Similar to the authenticate method above, but will sign data with non repudiation/signing certificate.

verifyPin

Similar to the authenticate method above, but will trigger a verify Pin action.

Note about transaction speeds

Because of the number of checks involved, using the generic interface will be (very slightly) slower than direct communication with the containers. In very time critical applications, where speed is of the utmost importance, we recommend setting up your transactions to directly interface with the containers. For all other use cases the additional time for the checks should be negligable.

Example Usage

Let's assume that we have a card inserted into a card reader connected to our system, but we don't know which container to use to communicate with it. Also, we're not 100% sure we know the pin code to this card, so we would like to check that before trying to sign or authenticate. This is an ideal use case for the generic interface.

Get connector client

First we initialize our connector client:

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

Check that the card supports verifyPin

We ask our client to return a list of readers that can perform a verifyPin action:

List<GclReader> readers = t1cClient.getPinVerificationCapableReaders();

If we find our reader in the list of readers, that means verifyPin is supported for this card.

Check that we have the correct PIN code

Now that we know that we can perform a verifyPin action, let's check if we have the correct PIN:

boolean pinVerified = t1cClient.getGenericContainer(reader).verifyPin("1234");

If this call returns pinVerified == true, we have the correct pin!

Check if we can authenticate

Much like we did for verifyPin, we can now ask the client to give us a list of readers that can authenticate some data:

List<GclReader> readers = t1cClient.getAuthenticateCapableReaders();

Again, if we find a reader in the list of readers that has the reader we want to use, we are good to go.

Authenticate data

To authenticate our data, we call the generic authenticate method with readerId, data to authenticate and optionally the PIN code:

IGenericContainer container = t1cClient.getGenericContainer(reader);
String authenticatedData = container.authenticate("mVEpdyxAT1FWgVnLsKcmqiWvsSuKP6uGAGT528AEQaQ=", DigestAlgorithm.SHA256, pin)

If successful, authenticatedData will contain the authenticated data, otherwise an exception will be thrown

Check if we can sign data

Similar to before we will first check if our reader can perform a sign data action:

List<GclReader> readers = t1cClient.getSignCapableReaders();

Sign some data

Signing the data is completely analogous to the authenticate call:

IGenericContainer container = t1cClient.getGenericContainer(reader);
String pin = "1234";
String signedData = container.sign("mVEpdyxAT1FWgVnLsKcmqiWvsSuKP6uGAGT528AEQaQ=", DigestAlgorithm.SHA256, pin);

If successful, signedData will contain the signed data, otherwise it will be null.

Get the signing certificate chain

We can ask the generic container to give us the signing certificate chain for this card

IGenericContainer container = t1cClient.getGenericContainer(reader);
Map<Integer, T1cCertificate> certChain = container.getSigningCertificateChain();

Get the authentication certificate chain

We can ask the generic container to give us the signing certificate chain for this card

IGenericContainer container = t1cClient.getGenericContainer(reader);
Map<Integer, T1cCertificate> certChain = container.getAuthenticationCertificateChain();