SCION HTTP Forward Proxy

The SCION HTTP Forward Proxy provides access to HTTP(S) resources via SCION by using a configured proxy for all SCION-enabled domains. It is implemented as a Caddy plugin, and can be used with any compatible Caddy server version. If you are looking for the reverse proxy, see Reverse Proxy.

Prerequisites

• A SCION-enabled host in a SCION-enabled network (see Access and Host Configuration).

Build for Linux and install

A Debian package will be made available soon. In the meantime, you can download the latest release available or build the plugin from source as follows:

• Download the source code from the SCION HTTP Proxy repository.

• Build the plugin by running the following command in the root directory of the repository:

  make build scion-caddy
  

• or (if you only want to build the forward proxy)

  make build scion-caddy-forward
  

Then, you can follow the steps below to install the plugin:

• Ensure that you are running the scion-endhost stack as described in the SCION documentation.

• Copy the binary to /usr/local/bin or any other directory in your $PATH.

• Add a data directory for the plugin to store its data:

  sudo mkdir -p /usr/share/scion/caddy-scion
  sudo chown -R $USER:$USER /usr/share/scion
  

• Install the systemd service file by copying it to /etc/systemd/system and enabling it (you can take as a reference the file scion-caddy-forward-proxy.service in the examples folder):

  sudo cp scion-caddy-forward-proxy.service /etc/systemd/system/
  sudo systemctl enable scion-caddy-forward-proxy.service
  

• You can use the scion-caddy-forward-proxy.json file in latest realease or in examples folder as a configuration file. Move it to /etc/scion/ or the path that you have configured in the systemd service file.

• Start the service:

  sudo systemctl start scion-caddy-forward-proxy.service
  

• If you are running the forward proxy as a local proxy, please follow the localhost configuration instructions to integrate it with your browser.

Build for MacOS and install

At the moment, you can download the latest release available or build the plugin from source as follows:

• Download the source code from the SCION HTTP Proxy repository.

• Build the plugin by running the following command in the root directory of the repository:

  make build-macos scion-caddy
  

• or (if you only want to build the forward proxy)

  make build-macos scion-caddy-forward
  

Then, you can follow the steps below to install the plugin:

• Ensure that you are running the scion-endhost stack as described in the SCION documentation.

• Apply the necessary permissions to the binary:

  chmod +x scion-caddy
  

• Add a data directory for the plugin to store its data:

  sudo mkdir -p /usr/local/scion/caddy-scion
  sudo chown -R $USER /usr/local/scion
  

• You can use the scion-caddy-forward-proxy.json file in latest realease or in examples folder as a configuration file. Next, modify the JSON configuration file to point to the correct paths for the plugin data directory. Mainly, replace /usr/share/scion/caddy-scion with /usr/local/scion/caddy-scion.

• Run the binary with the configuration file:

  ./scion-caddy -conf /path/to/your/scion-caddy-forward-proxy.json
  

• If you are running the forward proxy as a local proxy, please follow the localhost configuration instructions to integrate it with your browser.

Note

Instructions to run the HTTP Forward Proxy on MacOS as launchd service will be provided in the future. Likewise, we will work on providing a Homebrew formula.

Build for Windows and install

At the moment, you can download the latest release available or build the plugin from source as follows:

• Download the source code from the SCION HTTP Proxy repository.

• Build the plugin by running the following command in the root directory of the repository:

  make build-windows scion-caddy
  

• or (if you only want to build the forward proxy)

  make build-windows scion-caddy-forward
  

Then, you can follow the steps below to install the plugin:

• Ensure that you are running the scion-endhost stack as described in the SCION documentation.

• Add a data directory for the plugin to store its data (in a PowerShell terminal):

  mkdir -p AppData\\scion\\caddy-scion
  

• You can use the scion-caddy-forward-proxy.json file in latest realease or in examples folder as a configuration file. Next, modify the JSON configuration file to point to the correct paths for the plugin data directory. Mainly, replace /usr/share/scion/caddy-scion with C:\\Users\\<username>\\AppData\\scion\\caddy-scion.

• Run the binary with the configuration file:

  .\\scion-caddy run -conf \\path\\to\\your\\scion-caddy-forward-proxy.json
  

• If you are running the forward proxy as a local proxy, please follow the localhost configuration instructions to integrate it with your browser.

Warning

The SCION endhost stack is not officially supported on Windows, but it can be built and run with some limitations. Mainly, the dispatcher is not supported on Windows, but you can run SCION applications in environments that do not require the dispatcher. This is applicable if your network provider runs SCION version > 0.11.0, available from the Releases.

Configuration

The SCION HTTP Forward Proxy is configured via the Caddy JSON config. The location of the JSON config is specified in the systemd service file or when running the binary via the -conf flag.

You can find examples of JSON configurations in the examples folder of the repository. For more information on how to configure Caddy, see the Caddy documentation.

Session Key for Cookie Storage

Our implementation uses gorilla session <https://github.com/gorilla/sessions> to manage session cookies. A session key can be provided in the system environment variable SESSION_KEY to achieve persistence upon system restarts, i.e., existing session cookies will remain valid and the user will not have to log in again. It is the responsibility of the caddy administrator to handle this key securely, i.e., rotation, authorization, etc. If no session key is provided, a random key will be generated upon each restart.

You may need to restart the service after setting the environment variable.

sudo systemctl daemon-reload
sudo systemctl restart scion-caddy-forward-proxy.service

TLS Certificates

The Caddy server allows for different certificates configurations that can be specified in the JSON configuration. For more information, see the Caddy TLS configuration and Caddy PKI configuration.

Running the SCION HTTP Forward Proxy locally

End users can run the SCION HTTP Forward Proxy locally by following the installation steps above. To ensure interoperability with their browser navigation, the user is required to add an entry to resolve the configured name for the forward proxy to the local IP address, e.g., by adding the following line to the /etc/hosts file:

127.0.0.1 forward-proxy.scion

Most browsers or HTTPS clients will not trust the self-signed certificate used by the SCION HTTP Forward Proxy by default. To avoid certificate warnings, the user must either:

• Import the root certificate use into the browser trust store. If the user has followed the installation examples in the examples folder, the root certificate can be found in the /usr/share/scion/caddy-scion directory. For MacOS, the root certificate can be found in the /usr/local/scion/caddy-scion directory. Please, use the Keychain Access application to import the root certificate.

• Disable certificate verification in the browser or client, e.g.: - Run chrome with, chrome --ignore-certificate-errors - Use the --insecure and --proxy-insecure flag with curl, e.g.:

  curl --insecure --proxy-insecure -x http://forward-proxy.scion:8080 https://www.example.org
  

Running the SCION HTTP Forward Proxy as in-network service

The SCION HTTP Forward Proxy can be run as an in-network service out of the box. Nonetheless, the local network administrator must:

• Implement a proper resolution for forward-proxy.scion to the IP address of the host running the SCION HTTP Forward Proxy. - This can be done by adding an entry to the local DNS server or by adding an entry to the /etc/hosts file of all the hosts in the network via some orchestrator.

• Disseminate the root certificate to all the hosts in the network. - This can be done by adding the root certificate to the trust store of all the hosts in the network or by using a configuration management tool to distribute the certificate.

Note

We are working on a user-friendly solution that network operators can use as reference and implement in their networks to facilitate the deployment of the SCION HTTP Forward Proxy as an in-network service. Nonetheless, any solution that achieves the previous requirements is valid.

SCION address resolution

The SCION HTTP Forward Proxy implements the following address resolution mechanism:

• Inspect if a valid entry exists for the host name in etc/hosts and /etc/scion/hosts file.

• [Deprecated] Request a RAINS query for the host name. If a valid SCION address is found, it will be used.

• Request a DNS TXT record for the host name. If a valid SCION address is found, it will be used.

• It falls back to IPv4/6 using the default DNS mechanism for the underlay system.

For test purposes, the proxy administrator (or the user if running it locally) can add an entry to the /etc/scion/hosts file to resolve a domain to a SCION address, if no DNS TXT record is available, e.g.:

61-ffaa:0:1101,129.132.121.164 www.yourdomain.org

SCION enabled domains

We explained in section SCION address resolution how the SCION HTTP Forward Proxy resolves SCION addresses. The SCION-WWW ecosystem is currently spawning, this is why we provide a list of SCION-enabled domains that can be accessed through SCION.

Note

We will try to keep this list updated as new domains are added to the SCION ecosystem. Ideally, if you are trying to reach a SCION-enabled service, the DNS mechanism should do the job transparently. Otherwise, we provide some mappings that you can manually add to your /etc/scion/hosts file.

SCION production network

• https://ethz.ch

Other domains are also accessible:

• https://www.ovgu.de

• https://dfw.source.kernel.org

• https://ucdb.br

If you are a regular user using an in-network proxy, you do not have to worry about the information below.

If you are running your own local proxy or you are the administrator for the in-network proxy, the domains have to be manually configured in the /etc/scion/hosts file:

71-2:0:4a,[141.44.25.151] ovgu.de www.ovgu.de
71-2:0:48,[127.0.0.1]       dfw.source.kernel.org
71-2:0:5c,[127.0.0.1]       ucdb.br

SCIONLab network

• https://www.scionlab.org

• http://www.scion-architecture.net

• https://www.netsys.ovgu.de