🔔 Belltower 🔔
===============

Belltower is a simple HTTP-based relay for sending Wake-on-LAN requests (and pings) to private subnets. Also includes a proxy mode for use in subnets that cannot be reached by WoL packets directly (usually due to filtering of broadcast packets).

All communication is encrypted and authenticated via the XChaCha20Poly1305 scheme using pre-shared keys. Keys for this scheme can be generated conveniently via `belltower keygen`.

Check `belltower --help` for a full overview on how to use this program. Note that the Belltower server itself does **not** come with a web frontend and is instead intended to be used as a backend for some other application.

The implementation is currently limited to Unix systems. Feel free to open an issue (or a PR!) if you need Windows support.

API
===

Belltower is intended to be used in internal networks and thus does not use HTTPS encryption to spare you the hassle of wrangling TLS certificates. Instead, Belltower listens for plain HTTP requests that are encrypted with the XChaCha20Poly1305 scheme. The nonce used for this encryption and authentication scheme must be given in the `Nonce` HTTP header in base64 encoding. The request body simply contains the encrypted payload (see below) encoded in whatever encoding scheme is set in the HTTP headers. Since the encryption is symmetric, the secret key needs to be shared beforehand (see example config files).

The encrypted payload is a JSON object that has the following shape:
```json
{
    "method": "<GET or POST>",
    "endpoint": "<name of API endpoint>",
    "timestamp": "<current time to prevent replay attacks>",
    "parameters": {
        "<some_paramter>": "<some value>"
    }
}
```

The following endpoints are defined for Belltower running as a master relay:
| Endpoint | Method | Parameters | Description                                |
|----------|--------|------------|--------------------------------------------|
| hosts    | GET    | -          | Get a list of all hosts known to Belltower |
| ping     | GET    | host       | Ping the given host and report the result  |
| wake     | POST   | host       | Send a WoL packet to the given host        |

The response is a JSON encoded object sent back with the same encryption schemes as above.

Demo
====

An example for a frontend written in PHP can be found in the `frontend` folder. This frontend is designed to work with the example configs in the `example_config` folder. The encryption is handled by libsodium, so this frontend requires the `sodium` PHP module to be installed. Check `php -m` to see if this module is active. If not, consult installation instructions for your distribution and ensure that the module is enabled in the `php.ini` file.

For a quick test, run these three commands in different shells:
```bash
cargo run --release -- -c example_config/belltower_localtest_master.toml -l /tmp/master.log master
cargo run --release -- -c example_config/belltower_localtest_proxy.toml -l /tmp/proxy.log -p 41781 proxy
cd frontend && php -S localhost:8080
```
Note: running the master relay and a proxy on the same computer does not make much sense usually, but this is just a demonstration.

**IF YOU COPY THE EXAMPLE CONFIGS FOR AN ACTUAL DEPLOYMENT, REMEMBER TO CHANGE THE ENCRYPTION KEYS. YOU HAVE BEEN WARNED!**