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

Download for your target platform

You can download the SCION HTTP Forward Proxy pre-built binaries in releases. Otherwise, you can build the plugin for your target platform as described below.

Build for your target platform

You can build the caddy server containing the SCION plugin from source as follows:

Download the source code from the Caddy SCION repository.

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

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./build/scion-caddy-forward./cmd/scion-caddy-forward

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

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./build/scion-caddy ./cmd/scion-caddy

Adapt the GOOS and GOARCH variables to your target platform, e.g., GOOS=darwin GOARCH=amd64 for MacOS or GOOS=windows GOARCH=amd64 for Windows.

Installation for Linux

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
```
If you intend to configure the proxy to run on well-known ports, add network capabilities to the binary:
```
sudo setcap 'cap_net_bind_service=+ep' scion-caddy
```
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

Optionally you can create a systemd service and enable it. You can use the example service file scion-caddy.service in the examples.
You can use the forward.json file in examples folder as reference configuration file. The configuration is passed using the -config flag when running the binary. If you created a service, move it to /etc/scion/ or the path that you have configured in the systemd service file.
If you are running the forward proxy as a local proxy, please follow the localhost configuration instructions to integrate it with your browser.

Installation for MacOS

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
```
If you intend to configure the proxy to run on well-known ports, add network capabilities to the binary:
```
sudo setcap 'cap_net_bind_service=+ep' 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 forward.json file in examples folder as reference configuration file. The configuration is passed using the -config flag when running the binary. 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.

Installation for Windows

Note

Experimental option. The SCION HTTP forward proxy has not been tested on Windows yet.

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 forward.json file in examples folder as reference configuration file. The configuration is passed using the -config flag when running the binary. 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.12.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.

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.

Add the following line on /etc/hosts before running the SCION HTTP Forward Proxy:

127.0.0.1 forward-proxy.scion

The primary option for connecting to the SCION HTTP Forward Proxy is over HTTPS. 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 used 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/pki/authorities/local/root.crt directory.

For Linux and Windows, you can import the root certificate into the system trust store. The chromium-based browsers require the root certificate to be imported into the browser trust store as well.

Go to chrome://certificate-manager/ -> “Installed by you” -> “Import” -> select the root.crt retrieved previously.

For MacOS, 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 --proxy-insecure flag with curl, e.g.:
curl --proxy-insecure -x https://forward-proxy.scion:9443 https://www.example.org

Alternatively, you can enable plain HTTP support for the SCION HTTP Forward Proxy by adding the http port to the configuration file:

{
"apps": {
    "http": {
        "http_port": 9080,
        "https_port": 9443,
        "servers": {
            "forward": {
                "logs": {},
                "metrics": {},
                "listen": [
                    ":9080",
                    ":9443"
                ]
            }
        }
    }
    ...
}

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.
- Alternatively, the administrator can make use of WPAD (Web Proxy Auto-Discovery Protocol). This mechanism is used to automatically detect the proxy settings in your network. The SCION Browser Extension supports WPAD on a generic URL generic WPAD URL http://wpad/wpad_scion.dat. Check the Proxy Configuration documentation for more information.
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.
- Alternatively, see Using WebPKI with ACME DNS below to use publicly trusted certificates instead.

Using WebPKI with ACME DNS

Instead of distributing Caddy’s internal root certificate to all hosts, the administrator can obtain a publicly trusted (WebPKI) certificate for the forward proxy. This eliminates the need for certificate distribution entirely, since all clients already trust public CAs.

This requires that the proxy hostname is a valid FQDN that a public CA can issue a certificate for. By leveraging the network’s DNS search domain, the proxy can be reached at forward-proxy.scion.<search-domain> (e.g., forward-proxy.scion.example.com), which is a valid domain name for which a certificate can be obtained.

Prerequisites:

The administrator controls the DNS zone for <search-domain> and can create DNS records for forward-proxy.scion.<search-domain>.
The scion-caddy-forward-acmedns binary is used instead of scion-caddy-forward. This variant includes the ACME-DNS module and can be built with:
```
make scion-caddy-forward-acmedns
```

DNS setup:

Create an A/AAAA record for forward-proxy.scion.<search-domain> pointing to the proxy host IP.
Register the domain with the ACME-DNS server and create a CNAME record for _acme-challenge.forward-proxy.scion.<search-domain> pointing to the ACME-DNS subdomain.
Configure DHCP to advertised the DNS search domain or manually configure the DNS search domain on clients so that all client hosts resolve forward-proxy.scion to forward-proxy.scion.<search-domain>.

Configuration example:

The following configuration uses the ACME protocol with DNS-01 challenges via ACME-DNS to obtain a publicly trusted certificate for forward-proxy.scion.<search-domain>:

{
    "apps": {
        "http": {
            "http_port": 9080,
            "https_port": 9443,
            "servers": {
                "forward": {
                    "logs": {},
                    "metrics": {},
                    "listen": [
                        ":9080",
                        ":9443"
                    ],
                    "automatic_https": {
                        "disable_redirects": true
                    },
                    "routes": [
                        {
                            "handle": [
                                {
                                    "handler": "forward_proxy",
                                    "hosts": [
                                        "forward-proxy.scion.<search-domain>"
                                    ]
                                }
                            ]
                        }
                    ],
                    "tls_connection_policies": [
                        {}
                    ]
                }
            }
        },
        "tls": {
            "certificates": {
                "automate": [
                    "forward-proxy.scion.<search-domain>"
                ]
            },
            "automation": {
                "policies": [
                    {
                        "subjects": [
                            "forward-proxy.scion.<search-domain>"
                        ],
                        "issuers": [
                            {
                                "module": "acme",
                                "challenges": {
                                    "dns": {
                                        "provider": {
                                            "name": "acmedns",
                                            "server_url": "https://acme-dns.example.com",
                                            "username": "<acme-dns-username>",
                                            "password": "<acme-dns-password>",
                                            "subdomain": "<acme-dns-subdomain>"
                                        }
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
        }
    },
    "logging": {
        "logs": {
            "default": {
                "level": "INFO"
            }
        }
    }
}

Note

The ACME-DNS credentials (server_url, username, password, subdomain) are obtained when registering the domain with the ACME-DNS server. Refer to the caddy-dns/acmedns documentation for setup instructions.

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:

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]       web.git.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

SCION HTTP Forward Proxy

Prerequisites

Download for your target platform

Build for your target platform

Installation for Linux

Installation for MacOS

Installation for Windows

Configuration

Session Key for Cookie Storage

TLS Certificates

Running the SCION HTTP Forward Proxy locally

Running the SCION HTTP Forward Proxy as in-network service

Using WebPKI with ACME DNS

SCION address resolution

SCION enabled domains

SCION production network

SCIONLab network