add documents w/ notes and the start of the protocol definition...

NOTES.md

@@ -0,0 +1,65 @@
+Notes
+=====
+
+This file contains various notes about the development of this
+repository.
+
+
+This is based upon the PingPong code from heltec for Node 151[1].
+
+The STM32Cube packages are undocumented as far as I can tell.  Various
+files were copied from the PingPong code.
+
+MIT licensed code for the SX1276 is available at https://github.com/HelTecAutomation/Heltec_ESP32/tree/master/src/lora .
+
+BSD licensed code for the SX1276 is available at https://github.com/Lora-net/LoRaMac-node .
+It includes support for the STM32 micros, and so was used as the basis.
+Biggest issue is that it adds yet another HAL layer to the whole
+thing.
+
+mscgen for message diagram generation
+
+ECDH: https://tools.ietf.org/html/rfc7748#section-6.1
+
+
+Command to find and copy various files into the tree.  Almost all files
+were pulled from the STM32CubeL1 tree, but there was one or two that
+was pulled from LoRaMac-node tree.
+```
+cp $(find /tmp/Pingpong_CDC/ -name cmsis_gcc.h) stm32/
+```
+
+The following command can be used to strip CR's, and to remove any
+trailing new lines.  Note that in order to save my sanity, the files
+are committed after cleaning.  The repo does NOT contain (if it can be
+avoided) the pre-cleaned files.  The diff options `-w -b` may be used
+to ignore these cleanups.
+
+```
+# there is a ^V^I and a ^V^M in the following:
+LANG=C sed -i '' -e 's/[       ]*^M$//' $(find stm32/ -type f)
+```
+
+Running gdb
+-----------
+
+First, just run openocd, but w/o any needed command, or you can reset it:
+```
+sudo openocd -f interface/ftdi/digilent-hs1.cfg -f interface/ftdi/swd-resistor-hack.cfg -f target/stm32l1.cfg -c "init" -c "reset init"
+```
+
+Then run `arm-none-eabi-gdb` with the elf binary, and attach to OpenOCD
+with the command:
+```
+target remote localhost:3333
+```
+
+The gdb monitor command allows control of the device.  For example:
+```
+monitor reset halt
+```
+
+will reset the device, and halt it immediately, allowing setting a break
+point for main, or earlier.
+
+[1] https://heltec-automation-docs.readthedocs.io/en/latest/stm32/lora_node_151/pingpong_test.html

PROTOCOL.md

@@ -0,0 +1,57 @@
+Protocol
+========
+
+The responder will be the node under control (irrigation controler), and
+the initiator will be the server.
+
+The responder will always respond with one and only one packet.  That
+is, all timeout mechanisms will be handled by the initiator.  If the
+initiator does not receive a response to it's query, it will resend the
+request until it does.  It is required that the responder be able to
+detect this, and resend the last response.
+
+both sides:
+meta-AD('com.funkthat.lora.irrigation.<type>.v0.0.1')
+key(<defined by type>)
+
+The following exchange is required by protocols that are not PFS
+safe, that is shared and ecdh (defined below).  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)
+
+respondant:
+send_enc(<16 bytes random data>)	# nonce injection
+send_mac(8)
+
+initiator:
+send_enc('confirm')
+send_mac(8)
+
+respondant:
+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
+initiator to send any commands it needs to be "passed back".
+
+The new key/session does not become active till this point.
+
+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 conenction 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.
+
+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
+
+Note: look at: https://monocypher.org/manual/advanced/elligator when doing ECDHE