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 sessionId
parameter, 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
Objects
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
Parameters
timeout (optional): session timeout in seconds. If not provided, will default to value set in GCLConfig. Must be a number > 0.
Output
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
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
closeSession
Closes currently open session.
Interface
closeSession(callback?: (error, data))
Parameters
none
Output
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
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
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
apdu
Executes an APDU call on the current reader. The difference with the command
function is that theapdu
function takes an APDU object, whereas command
takes 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:
Output
Bulk Actions
For the apdu
and command
functions, 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:
Output
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
Last updated