Remote Loader (ReLo)

Introduction

The ReLo (Remote Loading) container is provided through the T1C (Trust1Connector) in order to provide a secured communication channel to executed APDU commands that are generated from a back-end service (which can be optionally signed by a HSM).

The ReLo provides smart card operations, like for example:

• open/close session
• execute APDUs (single or in bulk)
• retrieve card/card reader features
• verify if card present
• retrieve ATR
• ...

Communication Flow

The ReLo-API is an example back-end service implementing different smart card or token profiles (there is no limitation to smart cards). The T1V (Trust1Vault) is a Trust1Team product operating as a secured vault, and integrating with a HSM.

Available Functions

The following functions are available in the T1C-JS library:

ReaderId

The readerId is passed to thereaderapi handler object on initialization. For example, opening a session on reader with idf56c0ffe15a07d09 would look like this:

// Initialize a GCL Client
GCLLib.GCLClient.initialize(gclconfig).then(client => {
    // Open a session
    client.readerapi("f56c0ffe15a07d09").openSession(10).then(res => {
        // res.data will contain sessionId
    });
});

Callback/Promise

All function return Promises by default.

If you prefer callbacks, each function also has an optional parameter to pass in a callback function. If a callback function is provided, the function will still return a promise, but the callback function will be called when the promise resolves/gets rejected.

SessionID is optional

For any function that accepts a sessionIdparameter, the parameter is optional. If a sessionId is provided, the corresponding session will be used for the request and then will be _kept open_once the request completes. This means that if this was the last request that needed to be made, the session needs to be explicitly closed with a call tocloseSession.

If no sessionId is provided, the request will still complete, but the GCL will set up a new session, perform the required action and then close the session. This means that there is _no open session_once the request completes.

When a wrong sessionID is sent in a request, an error message will be returned. The status code will be 'invalid sessionID' or 'no active session' (see Status Codes).

Response structure

All responses follow a similar structure:

{
    data: any
    success: boolean
}

The successproperty indicates whether or not the request was completed successfully. The dataproperty is where returned information will be found; the type of datavaries with each function.

Detailed Function Overview

openSession

Opens a new session. Returns the sessionId, which will need to be stored by the client application for later use.

Interface

openSession(timeout?: number, callback?: (error, data))

Parameters

• timeout (optional): session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.

Output

{
    data: string // sessionId string
    success: boolean
}

command

Sends a command to the reader for execution.

Interface

command(tx: string, sessionId?: string, callback: (error, data))

Parameters

• tx: command-string to be executed
• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }
    success: boolean
}

ccid

Checks if a feature is available for the current reader

Interface

ccid(feature: string, command: string, sessionId?: string, callback?: (error, data))

Parameters

• feature: feature to check
• command: command to send to the ccid reader (hex format)
• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: string // ccid response
    success: boolean
}

closeSession

Closes currently open session.

Interface

closeSession(callback?: (error, data))

Parameters

• none

Output

{
    success: true
}

isPresent

Checks if the card for this session is still present.

If no sessionId is provided, checks if a card is present in the reader.

Interface

isPresent(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: boolean // true if present, false if not
    success: boolean
}

atr

Retrieves the ATR for the card currently in the reader.

Interface

atr(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: string // ATR string
    success: boolean
}

ccidFeatures

Returns a list of available CCID features for the current reader.

Interface

ccidFeatures(sessionId?: string, callback?: (error, data))

Parameters

• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: Ccid[]
    success: boolean
}

apdu

Executes an APDU call on the current reader. The difference with the commandfunction is that theapdu function takes an APDU object, whereas commandtakes a string.

Interface

apdu(apdu: ApduObject, sessionId?: string, callback?: (error, data))

Parameters

• apdu: object containing the APDU to be executed
• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

APDU Object interface:

{
    cla: string
    ins: string
    p1: string
    p2: string
    data?: string
    le?: string
}

Output

{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }
    success: boolean
}

Bulk Actions

For the apduand commandfunctions, it is possible to send an array of apdu's/commands.

apdu (bulk)

Executes an array of APDU calls on the current reader.

Interface

apdu(apdu: ApduObject[], sessionId?: string, callback?: (error, data))

Parameters

• apdu: array containing the APDU objects to be executed
• sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.

APDU Object interface:

{
    cla: string
    ins: string
    p1: string
    p2: string
    data?: string
    le?: string
}

Output

{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }[] // Array of response objects
    success: boolean
}

command (bulk)

Executes an array of commands on the current reader.

Interface

command(tx: string[], sessionId?: string, callback?: (error, data))

Parameters

• tx : array containing the command strings to be executed
• sessionId (optional) : sessionId to use. Required if the session needs to be kept open after the request completes.

Output

{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }[] // Array of response objects
    success: boolean
}