Generic Interface

Introduction

For user convenience, the Trust1Connector exposes a number of methods that make abstraction of the 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-JS will check the type of card in the reader and use the appropriate container to perform the requested action.

Interface Summary

// generic methods
containerFor(readerId: string, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>

download(callback?: (error: RestException, data: DownloadLinkResponse) => void): Promise<DownloadLinkResponse>

dumpData(readerId: string, data: OptionalPin, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>

readersCanAuthenticate(callback?: (error: RestException, data: CardReadersResponse) => void): Promise<CardReadersResponse>
authenticate(readerId: string, data: AuthenticateOrSignData, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>

readersCanSign(callback?: (error: RestException, data: CardReadersResponse) => void): Promise<CardReadersResponse>
sign(readerId: string, data: AuthenticateOrSignData, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>

readersCanVerifyPin(callback?: (error: RestException, data: CardReadersResponse) => void): Promise<CardReadersResponse>
verifyPin(readerId: string, data: OptionalPin, callback?: (error: RestException, data: DataResponse) => void): Promise<DataResponse>

Method Details

containerFor

This method will tell you the name of the container to use when interacting the the card in the reader with readerId passed in as an argument. This can be useful if you want to retain full control over the calls being made, but need to support several card types.

download

Will return an object with a url property which is a download link for the GCL component of Trust1Connector. The method will first check which operating system it is being called from and then return a link appropriate for the detected OS.

dumpData

This method will return all available data from the card. Which data this is depends on the card type, but (with a few exceptions) it is analogous with the container's allData method, with certificate parsing enabled.

readersCan[Authenticate/Sign/VerifyPin]

Returns a list of card readers that can perform the indicated action right now. The method will check all connected readers for cards inserted. For readers with cards it checks two things:

• Is the container required to communicate with this card available in the local GCL installation

• Can this card perform the requested action

If both of these conditions are met, the reader is added to the list of readers to be returned.

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-JS will check if a reader with readerId is found

2. T1C-JS 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

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:

GCLClient.initialize(gclConfig).then(function(newClient) {
        var client = newClient;
});

Check that the card supports verifyPin

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

client.readersCanVerifyPin().then(function(readers) {
    // readers.data contains a list of readers that can verifyPin
});

If we find our readerId in the list of readers in readers.data, 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:

var data = {
    pin: "0000"
}
client.verifyPin(readerId, data).then(function(result) {
    //
});

If this call returns result.success = 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:

client.readersCanAuthenticate().then(function(readers) {});

Again, if we find a reader in readers.data that has the readerId of 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:

var payload = {
    data: "I2e+u/sgy7fYgh+DWA0p2jzXQ7E=",
    algorithm_reference: "sha256",
    pin: "0000"
}
client.authenticate(readerId, payload).then(function(response){});

When the authenticate promise resolves (or callback is invoked), response.data will contain the authenticated data.

Check if we can sign data

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

client.readersCanSign().then(function(readers) {});

Sign some data

Signing the data is completely analogous to the authenticate call:

var payload = {
    pin: "0000",
    algorithm_reference: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs="
}
client.sign(readerId, payload).then(function(response) {});

When the sign promise resolves, response.data will contain the signed data.