gf4
/
wagon
2
0
Fork 0
Code Issues 3 Pull Requests Projects Releases Wiki Activity
wagon/USAGE.md

6.7 KiB
Raw Permalink Blame History

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:
{
  "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
{
  "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