wagon/USAGE.md

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&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

2.2 API

2.2.1. List devices

TODO

2.2.2. Add device

TODO

2.2.3. Delete device

TODO

2.2.4. List users

TODO

2.2.5. Add user

TODO

2.2.6. Delete user

TODO