diff --git a/USAGE.md b/USAGE.md index d3be02e..ba706f4 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,8 +1,8 @@ # Wagon usage -This hasn't been written yet, but it will contain good information on all the dashboards and API endpoints. +## 1. User service -## User dashboard +### 1.1. Frontend The sample frontend shows a user's devices in a table like this: @@ -15,18 +15,111 @@ The sample frontend shows a user's devices in a table like this: 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 place to add a device: +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&ext=crt` + - `host`: get file for which host? + - `ext`: `crt` for certs or `key` for keys +- **RESPONSE:** The requested SSL certificate or key file + +## 2. Admin service + +### 2.1. Dashboard -## User API +### 2.2 API + +#### 2.2.1. List devices TODO -## Admin dashboard +#### 2.2.2. Add device TODO -## Admin API +#### 2.2.3. Delete device + +TODO + +#### 2.2.4. List users + +TODO + +#### 2.2.5. Add user + +TODO + +#### 2.2.6. Delete user TODO