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.
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
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.
The following functions are available in the library:
The readerId is passed to theremoteloading handler object on initialization. For example, opening a session on reader with idf56c0ffe15a07d09
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.
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'
Opens a new session. Returns the sessionId, which will need to be stored by the client application for later use.
timeout (optional): session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.
Sends a command to the reader for execution.
command(tx: string, sessionId?: string, callback: (error, data))
tx: command-string to be executed
sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Activates a specific CCID feature if it is available on the reader
ccid(feature: string, command: string, sessionId?: string, callback?: (error, data))
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.
Closes currently open session.
closeSession(callback?: (error, data))
none
Checks if the card for this session is still present.
If no sessionId is provided, checks if a card is present in the reader.
isPresent(sessionId?: string, callback?: (error, data))
sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Retrieves the ATR for the card currently in the reader.
atr(sessionId?: string, callback?: (error, data))
sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
Returns a list of available CCID features for the current reader.
ccidFeatures(sessionId?: string, callback?: (error, data))
sessionId (optional): sessionId to use. Required if the session needs to be kept open after the request completes.
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.
apdu(apdu: ApduObject, sessionId?: string, callback?: (error, data))
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:
For the apduand commandfunctions, it is possible to send an array of apdu's/commands.
Executes an array of APDU calls on the current reader.
apdus(apdu: ApduObject[], sessionId?: string, callback?: (error, data))
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:
Executes an array of commands on the current reader.
commands(tx: string[], sessionId?: string, callback?: (error, data))
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.
retrieve ATR
...
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.
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)
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>;
}export enum CCIDFeature {
VERIFY_PIN_DIRECT = 'VERIFY_PIN_DIRECT',
MODIFY_PIN_DIRECT = 'MODIFY_PIN_DIRECT',
GET_TLV_PROPERTIES = 'GET_TLV_PROPERTIES'
}openSession(timeout?: number, callback?: (error, data)){
data: string // sessionId string
success: boolean
}{
data: {
tx: string, // input
rx?: string, // output
sw: string // status word
}
success: boolean
}{
data: string // ccid response
success: boolean
}{
success: true
}{
data: boolean // true if present, false if not
success: boolean
}{
data: string // ATR string
success: boolean
}{
data: Ccid[]
success: boolean
}{
cla: string
ins: string
p1: string
p2: string
data?: string
le?: string
}{
data: {
tx: string, // input
rx?: string, // output
sw: string // status word
}
success: boolean
}{
cla: string
ins: string
p1: string
p2: string
data?: string
le?: string
}{
data: {
tx: string, // input
rx?: string, // output
sw: string // status word
}[] // Array of response objects
success: boolean
}{
data: {
tx: string, // input
rx?: string, // output
sw: string // status word
}[] // Array of response objects
success: boolean
}