More details on the hmac

manual/manual.typ

@@ -15,91 +15,78 @@
   table-index: (enabled: false),
   listing-index: (enabled: false)
 )
-// #show link: set text(stroke: blue)
-
-// #show: mantys(
-//   name: "SchoolBOX WS",
-//   version: "0.0.1",
-//   authors: (
-//     "Jurn Wubben",
-//   ),
-//   license: "MIT",
-//   description: "Websocket comminucation between the SchoolBox device and the associated server.",
-//   repository: "https://git.jsw.tf/jsw/schoolbox-ws",
-
-//   title: "SchoolBox WS",
-//   date: datetime.today(),
-// )
 
 = Messages
 == Heartbeat
 === Server
-<ping>```json
+- ```json
 {"c": "ping"}
-```
-<pongmissed>```json
+```<ping>
+- ```json
 {"e": 0, "info": "Pong missed"}
-```
+```<pongmissed>
 
 === Device
-<pong>```json
+- ```json
 {"c": "pong"}
-```
+```<pong>
 
 == Registration
 === Server
-<reg_pin>```json
-{"c": "reg_pin", "d": {"pin": 1234}} // Pin is an integer.
-```
-<reg_ok>```json
+- ```json
+{"c": "reg_pin", "d": {"pin": 1234}} // Pin is a random integer. Length doesn't really matter, as long as it fits on the screen.
+```<reg_pin>
+- ```json
 {"c": "reg_ok"}
-```
+```<reg_ok>
 
 === Device
-<reg_start>```json
+- ```json
 {"c": "reg_start"}
-```
+```<reg_start>
 
 
 == Authentication
 === Server
-<auth_nonce>```json
-{"c": "auth_nonce", "d": {"nonce": "random_string"}}
-```
-<auth_ok>```json
+- ```json
+{"c": "auth_nonce", "d": {"nonce": "random_string"}} // Should be a long, random generated string.
+```<auth_nonce>
+- ```json
 {"c": "auth_ok"}
-```
-<auth_error_id>```json
+```<auth_ok>
+- ```json
 {"e": 1, "info": "Invalid packet, wrong ID."}
-```
-<auth_error_sig>```json
+```<auth_error_id>
+- ```json
 {"e": 2, "info": "Invalid signature."} // the info doesn't matter
-```
-<auth_error_takeover>```json
+```<auth_error_sig>
+- ```json
 {"e": 3, "info": "Logged in at other place."} // the info doesn't matter
-```
+```<auth_error_takeover>
 
 === Device
-<auth_start>```json
-{"c": "auth_start"}
-```
-<auth_validate>```json
+- ```json
+{"c": "auth_start", "d": {"id": "id"}} // Id that is provided with registration.
+```<auth_start>
+- ```json
 {"c": "auth_validate", "d": {"signature": "HMAC hash of nonce"}}
-```
-
+```<auth_validate>
+	- The HMAC is a SHA256 with the password as the key, and the nonce as the data.
+	- The returned signature is encoded as hex.
+	- #link("https://git.jsw.tf/jsw/schoolbox-ws/src/commit/6acc935609d5c0de52aa752b69ccbaea84301b87/src/auth.ts#L9-L32")[Example implementation in JS.]
 == Session
 === Server
-<session_start>```json
+- ```json
 {"c": "session_start", "d": {"text": "Question?"}}
-```
-<session_stop>```json
+```<session_start>
+- ```json
 {"c": "session_stop"}
-```
+```<session_stop>
 
 === Device
-<session_vote>```json
+- ```json
 {"c": "session_vote", "d": {"vote": 1}} // Vote is an integer in the range of 1..5
-```
+```<session_vote>
 
 
 = General flow