# Remote loading

{% hint style="warning" %}
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.
{% endhint %}

## 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.

![](https://3581000150-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MA0NIpdSCJTdfFxKB45%2F-MBhTlbT0QLww-9FjWLF%2F-MBhnzel0qSYhTMSe7Ht%2Fimage.png?alt=media\&token=62c5d09a-649f-4e29-9aa9-838da2583c8f)

### 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 <a href="#relo-remoteloading-readerid" id="relo-remoteloading-readerid"></a>

The readerId is passed to the`remoteloading` handler object on initialization. For example, opening a session on reader with id`f56c0ffe15a07d09`

### Callback/Promise <a href="#relo-remoteloading-callback-promise" id="relo-remoteloading-callback-promise"></a>

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 <a href="#relo-remoteloading-sessionidisoptional" id="relo-remoteloading-sessionidisoptional"></a>

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 to`closeSession`.

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

```javascript
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

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

## Detailed Function Overview <a href="#relo-remoteloading-detailedfunctionoverview" id="relo-remoteloading-detailedfunctionoverview"></a>

### openSession <a href="#relo-remoteloading-opensession" id="relo-remoteloading-opensession"></a>

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

{% hint style="info" %}
The sessions are opened in `shared mode`
{% endhint %}

#### Interface <a href="#relo-remoteloading-interface" id="relo-remoteloading-interface"></a>

```javascript
openSession(timeout?: number, callback?: (error, data))
```

#### Parameters <a href="#relo-remoteloading-parameters" id="relo-remoteloading-parameters"></a>

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

#### Output <a href="#relo-remoteloading-output" id="relo-remoteloading-output"></a>

```javascript
{
    data: string // sessionId string
    success: boolean
}
```

### command <a href="#relo-remoteloading-command" id="relo-remoteloading-command"></a>

Sends a command to the reader for execution.

#### Interface <a href="#relo-remoteloading-interface.1" id="relo-remoteloading-interface.1"></a>

`command(tx: string, sessionId?: string, callback: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.1" id="relo-remoteloading-parameters.1"></a>

* **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 <a href="#relo-remoteloading-output.1" id="relo-remoteloading-output.1"></a>

```javascript
{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }
    success: boolean
}
```

### ccid <a href="#relo-remoteloading-ccid" id="relo-remoteloading-ccid"></a>

Activates a specific CCID feature if it is available on the reader

#### Interface <a href="#relo-remoteloading-interface.2" id="relo-remoteloading-interface.2"></a>

`ccid(feature: string, command: string, sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.2" id="relo-remoteloading-parameters.2"></a>

* **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 <a href="#relo-remoteloading-output.2" id="relo-remoteloading-output.2"></a>

```javascript
{
    data: string // ccid response
    success: boolean
}
```

### closeSession <a href="#relo-remoteloading-closesession" id="relo-remoteloading-closesession"></a>

Closes currently open session.

#### Interface <a href="#relo-remoteloading-interface.3" id="relo-remoteloading-interface.3"></a>

`closeSession(callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.3" id="relo-remoteloading-parameters.3"></a>

* none

#### Output <a href="#relo-remoteloading-output.3" id="relo-remoteloading-output.3"></a>

```javascript
{
    success: true
}
```

### isPresent <a href="#relo-remoteloading-ispresent" id="relo-remoteloading-ispresent"></a>

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 <a href="#relo-remoteloading-interface.4" id="relo-remoteloading-interface.4"></a>

`isPresent(sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.4" id="relo-remoteloading-parameters.4"></a>

* **sessionId** _(optional)_: sessionId to use. Required if the session needs to be kept open after the request completes.

#### Output <a href="#relo-remoteloading-output.4" id="relo-remoteloading-output.4"></a>

```javascript
{
    data: boolean // true if present, false if not
    success: boolean
}
```

### atr <a href="#relo-remoteloading-atr" id="relo-remoteloading-atr"></a>

Retrieves the ATR for the card currently in the reader.

#### Interface <a href="#relo-remoteloading-interface.5" id="relo-remoteloading-interface.5"></a>

`atr(sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.5" id="relo-remoteloading-parameters.5"></a>

* **sessionId** _(optional)_: sessionId to use. Required if the session needs to be kept open after the request completes.

#### Output <a href="#relo-remoteloading-output.5" id="relo-remoteloading-output.5"></a>

```javascript
{
    data: string // ATR string
    success: boolean
}
```

### ccidFeatures <a href="#relo-remoteloading-ccidfeatures" id="relo-remoteloading-ccidfeatures"></a>

Returns a list of available CCID features for the current reader.

#### Interface <a href="#relo-remoteloading-interface.6" id="relo-remoteloading-interface.6"></a>

`ccidFeatures(sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.6" id="relo-remoteloading-parameters.6"></a>

* **sessionId** _(optional)_: sessionId to use. Required if the session needs to be kept open after the request completes.

#### Output <a href="#relo-remoteloading-output.6" id="relo-remoteloading-output.6"></a>

```javascript
{
    data: Ccid[]
    success: boolean
}
```

### apdu <a href="#relo-remoteloading-apdu" id="relo-remoteloading-apdu"></a>

Executes an APDU call on the current reader. The difference with the `command`function is that the`apdu` function takes an APDU object, whereas `command`takes a string.

#### Interface <a href="#relo-remoteloading-interface.7" id="relo-remoteloading-interface.7"></a>

`apdu(apdu: ApduObject, sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.7" id="relo-remoteloading-parameters.7"></a>

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

```javascript
{
    cla: string
    ins: string
    p1: string
    p2: string
    data?: string
    le?: string
}
```

#### Output <a href="#relo-remoteloading-output.6" id="relo-remoteloading-output.6"></a>

```javascript
{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }
    success: boolean
}
```

## Bulk Actions <a href="#relo-remoteloading-bulkactions" id="relo-remoteloading-bulkactions"></a>

For the `apdu`and `command`functions, it is possible to send an array of apdu's/commands.

### apdus (bulk) <a href="#relo-remoteloading-apdu-bulk" id="relo-remoteloading-apdu-bulk"></a>

Executes an array of APDU calls on the current reader.

#### Interface <a href="#relo-remoteloading-interface.8" id="relo-remoteloading-interface.8"></a>

`apdus(apdu: ApduObject[], sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.8" id="relo-remoteloading-parameters.8"></a>

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

```javascript
{
    cla: string
    ins: string
    p1: string
    p2: string
    data?: string
    le?: string
}
```

#### Output <a href="#relo-remoteloading-output.6" id="relo-remoteloading-output.6"></a>

```javascript
{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }[] // Array of response objects
    success: boolean
}
```

### commands (bulk) <a href="#relo-remoteloading-command-bulk" id="relo-remoteloading-command-bulk"></a>

Executes an array of commands on the current reader.

#### Interface <a href="#relo-remoteloading-interface.9" id="relo-remoteloading-interface.9"></a>

`commands(tx: string[], sessionId?: string, callback?: (error, data))`

#### Parameters <a href="#relo-remoteloading-parameters.9" id="relo-remoteloading-parameters.9"></a>

*   **tx**

    : array containing the command strings to be executed
*   **sessionId**&#x20;

    _(optional)_

    : sessionId to use. Required if the session needs to be kept open after the request completes.

#### Output <a href="#relo-remoteloading-output.9" id="relo-remoteloading-output.9"></a>

```javascript
{
    data: {
        tx: string, // input
        rx?: string, // output
        sw: string  // status word
    }[] // Array of response objects
    success: boolean
}
```
