Remote loading

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:

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.

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
}