# Technical notes on the Local IO Bridge in Salto Space
> Technical notes-overview and configuration details-on the Local IO Bridge in Salto Space, intended for system administrators.


## What is the Local IO Bridge? {#what-is-the-local-io-bridge}

The Local IO Bridge is a lightweight Windows service developed by Salto that solves a fundamental connectivity problem:
the Space server, running on a remote machine, has no direct way to reach USB devices physically connected to a client machine.
The Local IO Bridge runs locally on the client machine and acts as a relay, bridging the Space server with USB devices, such as USB {{< glossary_term "encoder" >}}NCoders{{< /glossary_term >}} and {{< glossary_term "ppd" >}}PPDs{{< /glossary_term >}}.

See [System requirements](/space/user-guide/systems-admin/system-requirements) for an introduction to the Local IO Bridge and its role in the Space architecture.

The Local IO Bridge exposes a local REST API to the Space web application running in the browser, which orchestrates the communication.
The browser instructs the Local IO Bridge to open a relay connection between the Space server and the USB device, through which the Space server can operate the device directly.

![Local IO Bridge communication](images/space-local-io-bridge-communication.drawio.svg "Local IO Bridge communication")
{.zoomable-image}

## When is it required? {#when-is-it-required}

The Local IO Bridge is only needed on machines where a USB device is physically connected.

| **Scenario** | **Local IO Bridge required?** |
| --- | :---: |
| Client machine with USB NCoder | Yes |
| Client machine with USB PPD | Yes |
| Browser-only machine (no USB device attached) | No |
| Machine using an Ethernet-connected (IP) NCoder | No - IP NCoders communicate directly with the Space server over the network |

## Installation {#installation}

| **Item** | **Detail** |
| --- | --- |
| **Operating system** | Windows 10, Windows 11, or Windows Server 2016 or later |
| **Software dependency** | .NET Framework 4.8.0 (automatically installed if not present) |
| **Installer** | Download from the Space web application or from the `..\dist` folder |
| **Installation** | Double-click the installer to run a guided setup wizard. For unattended deployments, silent install is also supported: `setup_saltolocaliobridge.exe -quiet -InstallDir="C:\path"` |
| **Service startup** | Starts automatically with Windows and must be running before any USB operation is performed |

## Network and firewall considerations {#network-and-firewall-considerations}

The Local IO Bridge binds only to `localhost (127.0.0.1)`.
Its local REST API ports are not accessible from other machines on the network, so no inbound firewall rules are required at the network level.

### Local ports (browser-Local IO Bridge) {#local-ports-browser-local-io-bridge}

In default mode the Local IO Bridge randomly selects one HTTP port and one HTTPS port at each startup from the following allowed ranges:

| **Range** |
| :---: |
| 50000—50009 |
| 50110—50119 |
| 50220—50229 |
| 50330—50339 |
| 50440—50449 |
| 50550—50559 |
| 50660—50669 |
| 50770—50779 |
| 50880—50889 |
| 50990—50999 |

If a localhost firewall is in place, it must allow the Local IO Bridge process to listen on ports within these ranges.

In advanced mode, fixed port numbers can be configured.
See section [Advanced mode configuration](#advanced-mode-configuration) for further details.

### Outbound connection (Local IO Bridge-Space server) {#outbound-connection-local-io-bridge-space-server}

The Local IO Bridge establishes an outbound WebSocket connection to the Space server on TCP port 8102 (default, configurable).
When Space is configured with HTTPS, this connection is secured using WSS with the Space server's trusted CA-signed certificate.

## Advanced mode configuration {#advanced-mode-configuration}

By default the Local IO Bridge works out of the box with no configuration required: it selects random ports from the allowed ranges and uses its own built-in self-signed certificate for the local HTTPS endpoint.
In managed environments, an administrator may wish to:

- Fix the HTTPS port to a known value, avoiding port scanning by the browser.
- Use a trusted CA-signed certificate for the local HTTPS endpoint instead of the built-in self-signed one.

Both are configured by creating a file called `service.ini` in the Local IO Bridge installation folder.
The file is read once at startup and the service must be restarted after any change.
Only a user with administrator rights can create or modify this file.

{{% info-panel %}}
If `service.ini` does not exist, the Local IO Bridge keeps the default behavior.
{{% /info-panel %}}

Port and certificate configuration are independent—it is possible to configure only the port, only the certificate, or both.

### Port configuration {#port-configuration}

| **Key** | **Description** |
| --- | --- |
| `HttpsPort` | Fixed HTTPS port for the Local IO Bridge. Must be within one of the allowed ranges listed in section [Local ports](#local-ports-browser-local-io-bridge). When set, the HTTP port is not opened. |

### Certificate configuration {#certificate-configuration}

| **Key** | **Values** | **Description** |
| --- | :---: | --- |
| `HttpsCertManual` | `0` / `1` | `0` = use the built-in self-signed certificate (default).<br> `1` = use a certificate from the Windows Certificate Store. |
| `HttpsCertStoreName` | Store name | Certificate store to search within `LocalMachine`.<br> Default: `My`. |
| `HttpsCertIdentificationMethod` | `0` / `1` / `2` | Method to identify the certificate: `0` = Subject CN, `1` = Subject DN (default), `2` = Issuer. |
| `HttpsCertIdentificationMatchValue` | String | Value to match against the selected identification method. |
| `HttpsCertSelectionStrategy` | `0` / `1` | When multiple certificates match: `0` = most recent `NotBefore` date (default), `1` = latest `NotAfter` date. |

**Certificate requirements when using manual mode (`HttpsCertManual=1`)**:

- Must be signed by a Certificate Authority trusted by the client machine.
- Must not be expired.
- Must include `IP Address=127.0.0.1` in the Subject Alternative Name (SAN) field, since the Local IO Bridge binds only to localhost.

{{% info-panel %}}
When `HttpsCertManual=1`, the Local IO Bridge is accessible over **HTTPS only**—the HTTP port is not opened.
{{% /info-panel %}}

- Example:

```ini
[Https]
HttpsPort=50110
HttpsCertManual=1
HttpsCertStoreName=My
HttpsCertIdentificationMethod=0
HttpsCertIdentificationMatchValue=my-server.comtoso.com
HttpsCertSelectionStrategy=0
```

This configuration fixes the HTTPS port to 50110, uses a certificate from the Windows Certificate Store and identifies it by Subject CN matching
`my-server.comtoso.com` from the `My` store, selecting the one with the most recent `NotBefore` date if multiple matches exist.

## Data handling and privacy {#data-handling-and-privacy}

A key property of the Local IO Bridge is that it never has access to the data it relays.
All communication between the Space server and the USB device—including any card data and credentials—is encrypted end-to-end using DTLS 1.2 before it enters the relay.
The Local IO Bridge only ever forwards encrypted bytes.
It has no keys to decrypt the content and cannot read, inspect, or tamper with it in any way.

The Local IO Bridge is a blind relay by design.

![Data handling and privacy](images/space-data-handling-and-privacy.drawio.svg "Data handling and privacy")

The only data that passes between the browser and the Local IO Bridge—through the local REST API—is non-sensitive control information: port enumeration and relay management commands. No card data or credentials are ever present on this interface.

## Security summary {#security-summary}

| **Aspect** | **Detail** |
| --- | --- |
| **Blind relay** | The Local IO Bridge cannot read or tamper with card data—it is encrypted end-to-end (DTLS 1.2) between the Space server and the USB device |
| **Local REST API** | Commands exchanged between the browser and the Local IO Bridge are non-sensitive (port enumeration, relay control). No card data or credentials pass through this interface |
| **HTTPS certificate** | By default the local HTTPS endpoint uses a self-signed certificate. In advanced mode, a trusted CA-signed certificate from the Windows Certificate Store can be used instead. That certificate must include `IP Address=127.0.0.1` in its SAN field |
| **WSS connection** | When Space is configured with HTTPS, the WebSocket connection between the Local IO Bridge and the Space server uses the Space server's trusted CA-signed certificate |
| **Localhost only** | The Local IO Bridge REST API ports are bound to `localhost (127.0.0.1)`—they are not accessible from other machines on the network |