Remote loading

Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.

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 library:

JavaScript API

Function	Input	Output	Description
openSession	session timeout in seconds	sessionId	Opens a remote session, the session will be accessible through a session-id. The T1C will keep the session open and reusable.
command	tx, sessionId (optional)	command response	A single command to be executed remotely. When no session is available, a new session will be opened and immediately closed after execution of the command.
commands	tx[], sessionId (optional)	command response[]	One or more command to be executed remotely and sequentially. When no session is available, a new session will be opened and immediately closed after execution of the commands.
ccid	feature, command, sessionId (optional)	ccid response	Trigger a specific CCID feature.
closeSession	N/A	N/A	Close a session. When no session is available, a new session will be opened and closed. The T1C will be in its initial state.
isPresent	sessionId (optional)	boolean	Verify if a card is present. When no session is available, a new session will be opened and closed. The T1C will be in its initial state.
atr	sessionId (optional)	ATR for card	Retrieve ATR from card. When no session is available, a new session will be opened and closed. The T1C will be in its initial state.
ccidFeatures	sessionId (optional)	list of features	List of card readers features available for CCID. When no session is available, a new session will be opened and closed. The T1C will be in its initial state.
apdu	apdu object, sessionId (optional)	apdu response	Execute a single APDU command. When no session is available, a new session will be opened and closed. The T1C will be in its initial state.
apdus	apdu[], sessionId (optional)	apdu response[]	Execute one or more APDU commands (APDU bulk). When no session is available, a new session will be opened and closed. The T1C will be in its initial state.

ReaderId

The readerId is passed to theremoteloading handler object on initialization. For example, opening a session on reader with idf56c0ffe15a07d09

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'

Interface

interface AbstractRemoteLoading {
    atr(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
    apdu(apdu: APDU, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
    apdus(apdu: APDU[], sessionId?: string, callback?: (error: T1CLibException, data: CommandsResponse) => void): Promise<CommandsResponse>;
    ccid(feature: CCIDFeature, command: string, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
    ccidFeatures(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
    command(tx: string, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
    commands(tx: string[], sessionId?: string, callback?: (error: T1CLibException, data: CommandsResponse) => void): Promise<CommandsResponse>;
    closeSession(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
    isPresent(sessionId?: string, callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
    openSession(timeout?: number, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
}

Objects

export enum CCIDFeature {
    VERIFY_PIN_DIRECT = 'VERIFY_PIN_DIRECT',
    MODIFY_PIN_DIRECT = 'MODIFY_PIN_DIRECT',
    GET_TLV_PROPERTIES = 'GET_TLV_PROPERTIES'
}

Detailed Function Overview

openSession

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

The sessions are opened in shared mode

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

Activates a specific CCID feature if it is available on the 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.

apdus (bulk)

Executes an array of APDU calls on the current reader.

Interface

apdus(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
}

commands (bulk)

Executes an array of commands on the current reader.

Interface

commands(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
}