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

![](https://1766811608-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9hsLHDKsMEIM_b7evx%2F-L9hsQTuhZzirhBbjRTJ%2F-L9hsasDB_tLKCGha9h0%2FGCL-Remote%20Loading%20Sequence%20diagram.jpg?generation=1523335729916784\&alt=media)

Available Functions

The following functions are available in the T1C-JS 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.                      |
| command      | 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.                                      |
| apdu         | 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`readerapi` handler object on initialization. For example, opening a session on reader with id`f56c0ffe15a07d09` would look like this:

```javascript
// Initialize a GCL Client
GCLLib.GCLClient.initialize(gclconfig).then(client => {
    // Open a session
    client.readerapi("f56c0ffe15a07d09").openSession(10).then(res => {
        // res.data will contain sessionId
    });
});
```

### 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' (see [Status Codes](../../core/status-codes)).

### Response structure <a href="#relo-remoteloading-responsestructure" id="relo-remoteloading-responsestructure"></a>

All responses follow a similar structure:

```javascript
{
    data: any
    success: boolean
}
```

The `success`property indicates whether or not the request was completed successfully. The `data`property is where returned information will be found; the type of `data`varies with each function.

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

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

Checks if a feature is available for the current 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.

### apdu (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>

`apdu(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
}
```

### command (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>

`command(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
}
```
