206 lines
6.7 KiB
Markdown
206 lines
6.7 KiB
Markdown
# Wagon usage
|
|
|
|
## 1. User service
|
|
|
|
### 1.1. Frontend
|
|
|
|
The sample frontend shows a user's devices in a table like this:
|
|
|
|
> ```
|
|
> Host SSL
|
|
> mypc.myuser.mynet cert / key [DELETE]
|
|
> myphone.myuser.mynet cert / key [DELETE]
|
|
> mylaptop.myuser.mynet cert / key [DELETE]
|
|
> ```
|
|
|
|
The first column is each host's domain name. The next column has links for users to download an SSL cert/key for that device. Finally there is a button to delete that host. (Every host has a DELETE button, but the backend will not let you delete the device you are connecting from)
|
|
|
|
Below the devices list is a self-explanitory place to add a device:
|
|
|
|
> ### Add a peer
|
|
>
|
|
> To add a new peer, type in a hostname and click add. The hostname must be 3-10 lowercase letters and numbers `/[a-z0-9]{3,10}/`. Keep it short for your own sake!
|
|
>
|
|
> _______________ [ADD]
|
|
>
|
|
> After clicking "Add", the new peer's config will appear below. Copy and paste it into your wireguard client and start the service. **This configuration will not be shown again!** If you lose the config, you will need to delete the peer and recreate it.
|
|
|
|
As it says, there is no renaming of peers (yet), only deleting and re-adding.
|
|
|
|
### 1.2. API
|
|
|
|
There are four endpoints that power the user dashboard. Since the IP source address is used for authentication, a token must be provided when making changes (adding/deleting peers) to prevent IP spoofing. That is, a hacker at `10.99.6.1` should not be able to change our user's `10.99.1.0/24` network. However, this hacker could spoof their source IP to send a "delete" request and not care about receiving a response.
|
|
|
|
To prevent this, a token is generated on the server and sent to the user when requesting the `list`. This token can only be recieved by the actual source address, so a user can make a `list` request, get the token, and use it to authenticate `add` and `delete` requests. A spoofer would never recieve the token and not be able to send such changes. Thus, to `add` or `delete` a peer, two requests must be made; one for the token, and one for the actual command.
|
|
|
|
#### 1.2.1. List devices
|
|
|
|
- **REQUEST:** `GET /`
|
|
- **FILE:** `back/lib/dashboard/peer/list`
|
|
- **QUERYSTRING:** None
|
|
- **RESPONSE:** JSON with a token and array of user peers:
|
|
```json
|
|
{
|
|
"token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
|
"peers": [
|
|
{
|
|
"domain": "myhost1.myuser.mynet",
|
|
"ipv4": "10.99.1.1",
|
|
"ipv6": "fd69:1337:0:420:f4:99:1:1",
|
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
|
}, {
|
|
"domain": "myhost2.myuser.mynet",
|
|
"ipv4": "10.99.1.2",
|
|
"ipv6": "fd69:1337:0:420:f4:99:1:2",
|
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 1.2.2. Add device
|
|
|
|
- **REQUEST:** `POST /`
|
|
- **FILE:** `back/lib/dashboard/peer/add`
|
|
- **QUERYSTRING:** `?token=XXXX&name=mynewhostname`
|
|
- `token`: The token provided in a `list devices` response
|
|
- `name`: The new hostname for the peer
|
|
- **RESPONSE:**
|
|
- **202:** Success
|
|
- **403:** Wrong token provided
|
|
- **409:** Hostname already exists
|
|
- **500:** Other server-side error
|
|
|
|
#### 1.2.3. Delete device
|
|
|
|
- **REQUEST:** `DELETE /`
|
|
- **FILE:** `back/lib/dashboard/peer/del`
|
|
- **QUERYSTRING:** `?token=XXXX&pubkey=XXXX`
|
|
- `token`: The token provided in a `list devices` response
|
|
- `pubkey`: The peer's wireguard public key
|
|
- **RESPONSE:**
|
|
- **202:** Success
|
|
- **403:** Wrong token provided
|
|
- **500:** Other server-side error
|
|
|
|
### 1.2.4. Get SSL certs
|
|
|
|
- **REQUEST:** `GET /ssl`
|
|
- **FILE:** `back/lib/dashboard/ssl`
|
|
- **QUERYSTRING:** `?host=myhostname&type=cert`
|
|
- `host`: get file for which host?
|
|
- `type`: `cert` for certs or `key` for keys
|
|
- **RESPONSE:** The requested SSL certificate or key file
|
|
|
|
## 2. Admin service
|
|
|
|
### 2.1. Dashboard
|
|
|
|
There are four sections to the admin dashboard (then, at the bottom, a place where new configs are shown)
|
|
|
|
#### Add user
|
|
|
|
This is where you add a new user. You'll have to provide a hostname for their initial device. Adding a user like this will generate a wireguard configuration that you can send to the invited person over a secure channel.
|
|
|
|
#### Delete user
|
|
|
|
Deletes a user and all their peers. Totally removes the user from the network and deletes all their data.
|
|
|
|
#### Peer list
|
|
|
|
A (possibly long) list of all peers on the network, including servers (don't delete them!). Here you can delete a single peer from any user.
|
|
|
|
#### Add peer
|
|
|
|
This section lets you add a new peer for any existing user.
|
|
|
|
### 2.2 API
|
|
|
|
The admin API has no authentication so it should be blocked to all except admin IP ranges.
|
|
|
|
#### 2.2.1. List devices
|
|
|
|
- **REQUEST:** `GET /peer`
|
|
- **FILE:** `back/lib/admin/peer/list`
|
|
- **QUERYSTRING:** `?un=$username`
|
|
- `un`: A username, optionally, to show only that user's peers
|
|
- **RESPONSE:** A token and array of peers in JSON
|
|
```json
|
|
{
|
|
"token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
|
"peers": [
|
|
{
|
|
"domain": "myhost1.myuser.mynet",
|
|
"ipv4": "10.99.1.1",
|
|
"ipv6": "fd69:1337:0:420:f4:99:1:1",
|
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
|
}, {
|
|
"domain": "myhost2.myuser.mynet",
|
|
"ipv4": "10.99.1.2",
|
|
"ipv6": "fd69:1337:0:420:f4:99:1:2",
|
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
|
}
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
#### 2.2.2. Add device
|
|
|
|
- **REQUEST:** `POST /peer`
|
|
- **FILE:** `back/lib/admin/peer/add`
|
|
- **QUERYSTRING:** `?t=$token&host=$newhostname&user=$username&num=$usernumber`
|
|
- `t`: The token from a GET request
|
|
- `host`: The hostname chosen for the new peer
|
|
- `user`: The user's username
|
|
- `num`: The user's subnet number
|
|
- **RESPONSE:**
|
|
- `202`: Added
|
|
- `400`: Invalid input
|
|
- `403`: Bad token
|
|
- `409`: Hostname already exists
|
|
- `500`: Error
|
|
|
|
#### 2.2.3. Delete device
|
|
|
|
- **REQUEST:** `DELETE /peer`
|
|
- **FILE:** `back/lib/admin/peer/del`
|
|
- **QUERYSTRING:** `?t=$token&pubkey=$pubkey`
|
|
- `t`: The token from a GET request
|
|
- `pubkey`: Wireguard public key of the peer to remove
|
|
- **RESPONSE:**
|
|
- `202`: Deleted
|
|
- `400`: Attempted to delete self
|
|
- `403`: Bad token
|
|
- `404`: Peer not found
|
|
- `500`: Other server error
|
|
|
|
#### 2.2.4. Add user
|
|
|
|
- **REQUEST:** `POST /user`
|
|
- **FILE:** `back/lib/admin/user/add`
|
|
- **QUERYSTRING:** `?t=$token&host=$hostname&user=$username`
|
|
- `t`: The token from a GET request
|
|
- `host`: The hostname chosen for the new peer
|
|
- `user`: The username chosen
|
|
- **RESPONSE:**
|
|
- `202`: Added
|
|
- `400`: Invalid input
|
|
- `403`: Bad token
|
|
- `409`: Username already taken
|
|
- `500`: Error
|
|
|
|
#### 2.2.5. Delete user
|
|
|
|
- **REQUEST:** `DELETE /user`
|
|
- **FILE:** `back/lib/admin/user/del`
|
|
- **QUERYSTRING:** `?t=$token&user=$username&un=$usernumber`
|
|
- `t`: The token from a GET request
|
|
- `user`: The username to delete
|
|
- `un`: The user's subnet number
|
|
- **RESPONSE:**
|
|
- `202`: Deleted
|
|
- `400`: Bad username or number
|
|
- `403`: Bad token
|
|
- `500`: Other server error
|