wagon/USAGE.md

206 lines
6.7 KiB
Markdown
Raw Permalink Normal View History

2023-04-08 00:49:39 -06:00
# Wagon usage
2023-04-09 13:42:39 -06:00
## 1. User service
2023-04-08 00:49:39 -06:00
2023-04-09 13:42:39 -06:00
### 1.1. Frontend
2023-04-08 00:49:39 -06:00
2023-04-08 15:21:40 -06:00
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)
2023-04-09 13:42:39 -06:00
Below the devices list is a self-explanitory place to add a device:
2023-04-08 15:21:40 -06:00
2023-04-09 13:42:39 -06:00
> ### 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.
2023-04-08 15:21:40 -06:00
2023-04-09 13:42:39 -06:00
As it says, there is no renaming of peers (yet), only deleting and re-adding.
2023-04-08 00:49:39 -06:00
2023-04-09 13:42:39 -06:00
### 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="
2023-04-12 21:59:51 -06:00
}, {
2023-04-09 13:42:39 -06:00
"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`
2023-04-09 13:42:39 -06:00
- `host`: get file for which host?
- `type`: `cert` for certs or `key` for keys
2023-04-09 13:42:39 -06:00
- **RESPONSE:** The requested SSL certificate or key file
## 2. Admin service
### 2.1. Dashboard
2023-04-12 21:59:51 -06:00
There are four sections to the admin dashboard (then, at the bottom, a place where new configs are shown)
2023-04-09 13:42:39 -06:00
2023-04-12 21:59:51 -06:00
#### 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.
2023-04-09 13:42:39 -06:00
### 2.2 API
2023-04-12 21:59:51 -06:00
The admin API has no authentication so it should be blocked to all except admin IP ranges.
2023-04-09 13:42:39 -06:00
#### 2.2.1. List devices
2023-04-12 21:59:51 -06:00
- **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="
}
]
}
```
2023-04-09 13:42:39 -06:00
#### 2.2.2. Add device
2023-04-12 21:59:51 -06:00
- **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
2023-04-09 13:42:39 -06:00
#### 2.2.3. Delete device
2023-04-12 21:59:51 -06:00
- **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
2023-04-09 13:42:39 -06:00
2023-04-12 22:06:51 -06:00
#### 2.2.4. Add user
2023-04-08 00:49:39 -06:00
2023-04-12 22:06:51 -06:00
- **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
2023-04-08 00:49:39 -06:00
2023-04-12 22:06:51 -06:00
#### 2.2.5. Delete user
2023-04-08 00:49:39 -06:00
2023-04-12 22:06:51 -06:00
- **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