From db35f09a3651973b4e6f9998a899a07a475ef9c1 Mon Sep 17 00:00:00 2001
From: John-Mark Gurney <jmg@funkthat.com>
Date: Sun, 30 Jan 2022 21:16:37 -0800
Subject: [PATCH] clean up key negotiation, and document commands and queueing
 system..

---
 PROTOCOL.md | 64 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 53 insertions(+), 11 deletions(-)

diff --git a/PROTOCOL.md b/PROTOCOL.md
index ebbd244..12e3298 100644
--- a/PROTOCOL.md
+++ b/PROTOCOL.md
@@ -16,34 +16,62 @@ reprocess the messages.  The more complicated part is dealing w/ a
 missed confirmed reply, as the state will need to be back tracked (saved)
 to decode the repeated confirm request.
 
-both sides:
-meta-AD('com.funkthat.lora.irrigation.<type>.v0.0.1')
-key(<defined by type>)
+Key Negotiation
+-------------
+
+Where type is to be:
+	shared - shared secret
+	ecdh - Results of an ECDH exchange, key = K || K_A || K_B
+	ecdhe - Results of an ECDHE exchange, key = TBD
+
+### shared
+
+Both sides initalize:
+```
+meta-AD('com.funkthat.lora.irrigation.shared.v0.0.1')
+key(<preshared key>)
+```
+
+The `preshared key` was agreed/preloaded on both sides.  They should be a
+minimum of 16 bytes, but longer, such as pass phrases are allowed, as
+the key will be properly compressed by Keccak.
 
 The following exchange is required by protocols that are not PFS
-safe, that is shared and ecdh (defined below).  This is to prevent
+safe, that is shared and ecdh (not yet defined).  This is to prevent
 replay attacks and ensure that both sides have integrated random data
 into the protocol, AND that the connection reset was requested by the
 initiator.  This is described in the second paragraph of § C.2 in the
 [strobe paper](strobe/www/papers/strobe-20191114.pdf).
 
 initiator:
+```
 send_enc(<16 bytes random data> + 'reqreset')	# nonce injection
 send_mac(8)
+```
 
 respondent:
+```
 send_enc(<16 bytes random data>)	# nonce injection
 send_mac(8)
+```
 
+both:
+```
 ratchet()	# prevent backtracking
+```
+
 
 initiator:
+```
 send_enc('confirm')
 send_mac(8)
+```
 
 respondent:
+```
 send_enc('confirmed')
 send_mac(8)
+```
 
 It seems odd to respond to the confirm message, BUT, as using strobe
 requires explicit hand off (similar to a token), in order for the
@@ -55,12 +83,10 @@ In order to handle a reset and prevent a replay attack, the existing
 session, if any is maintained till the completion of a reset request.
 Only after that, does the old connection key get removed.  This does
 mean that after a reset request, it is required that both sides attempt
-to decode each packet w/ both keys.
+to decode each packet w/ both states.
 
-Where type is to be:
-	shared - shared secret: key = common set of bytes, should be min 16 bytes.
-	ecdh - Results of an ECDH exchange, key = K || K_A || K_B
-	ecdhe - Results of an ECDHE exchange, key = TBD
+Command Phase
+-------------
 
 Once the session has been established, the initiator will send commands of the
 following format:
@@ -71,10 +97,26 @@ format.  Additional types may be added later.
 
 The following commands are defined:
 TERMINATE: 1 -- no args: terminate the session, reply confirms
-WAITFOR: 2 -- args: (length): waits for length seconds
-RUNFOR: 3 -- args: (chan, length): turns on chan for length seconds
+WAITFOR: 2 -- args: (length): enqueues a waits for length seconds
+RUNFOR: 3 -- args: (chan, length): enqueues a turn on chan for length seconds
+PING: 4 -- args: (): No op, verify connection is functional
+SETUNSET: 5 -- args: (chan, val): sets chan to val
+ADV: 6 -- args: ([cnt]): Advances to the next cnt (default 1) command
+CLEAR: 7 -- args: (): Clears all future commands, but keeps current running
 
 When the responder receives a command, it will process it, and send back
 a response w/ the same command byte as an acknowledgment.
 
+Note that the commands WAITFOR and RUNFOR are enqueued on the run queue.
+If there is not a running enqueued command, it will be started, and only
+when the current enqueued command finishes will the next one be run.
+
+The other commands are run immediately.
+
+To clear any pending enqueued commands, and end the current command, a
+CLEAR command followed by an ADV command must be sent.  This will clear
+out any scheduled commands, and then end the current command so that any
+future scheduled commands will be started, as opposed to waiting till
+the current scheduled command finishes.
+
 Note: look at: https://monocypher.org/manual/advanced/elligator when doing ECDHE