T1C-JS Guide (v3)
Search…
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

1
interface AbstractRemoteLoading {
2
atr(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
3
apdu(apdu: APDU, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
4
apdus(apdu: APDU[], sessionId?: string, callback?: (error: T1CLibException, data: CommandsResponse) => void): Promise<CommandsResponse>;
5
ccid(feature: CCIDFeature, command: string, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
6
ccidFeatures(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
7
command(tx: string, sessionId?: string, callback?: (error: T1CLibException, data: CommandResponse) => void): Promise<CommandResponse>;
8
commands(tx: string[], sessionId?: string, callback?: (error: T1CLibException, data: CommandsResponse) => void): Promise<CommandsResponse>;
9
closeSession(sessionId?: string, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
10
isPresent(sessionId?: string, callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
11
openSession(timeout?: number, callback?: (error: T1CLibException, data: DataResponse) => void): Promise<DataResponse>;
12
}
Copied!

Objects

1
export enum CCIDFeature {
2
VERIFY_PIN_DIRECT = 'VERIFY_PIN_DIRECT',
3
MODIFY_PIN_DIRECT = 'MODIFY_PIN_DIRECT',
4
GET_TLV_PROPERTIES = 'GET_TLV_PROPERTIES'
5
}
Copied!

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

1
openSession(timeout?: number, callback?: (error, data))
Copied!

Parameters

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

Output

1
{
2
data: string // sessionId string
3
success: boolean
4
}
Copied!

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

1
{
2
data: {
3
tx: string, // input
4
rx?: string, // output
5
sw: string // status word
6
}
7
success: boolean
8
}
Copied!

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

1
{
2
data: string // ccid response
3
success: boolean
4
}
Copied!

closeSession

Closes currently open session.

Interface

closeSession(callback?: (error, data))

Parameters

    none

Output

1
{
2
success: true
3
}
Copied!

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

1
{
2
data: boolean // true if present, false if not
3
success: boolean
4
}
Copied!

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

1
{
2
data: string // ATR string
3
success: boolean
4
}
Copied!

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

1
{
2
data: Ccid[]
3
success: boolean
4
}
Copied!

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:
1
{
2
cla: string
3
ins: string
4
p1: string
5
p2: string
6
data?: string
7
le?: string
8
}
Copied!

Output

1
{
2
data: {
3
tx: string, // input
4
rx?: string, // output
5
sw: string // status word
6
}
7
success: boolean
8
}
Copied!

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:
1
{
2
cla: string
3
ins: string
4
p1: string
5
p2: string
6
data?: string
7
le?: string
8
}
Copied!

Output

1
{
2
data: {
3
tx: string, // input
4
rx?: string, // output
5
sw: string // status word
6
}[] // Array of response objects
7
success: boolean
8
}
Copied!

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

1
{
2
data: {
3
tx: string, // input
4
rx?: string, // output
5
sw: string // status word
6
}[] // Array of response objects
7
success: boolean
8
}
Copied!
Last modified 4mo ago