From 5ea20415d6352c4fd3102748369906058453b6a4 Mon Sep 17 00:00:00 2001
From: sqozz <sqozz@geekify.de>
Date: Sat, 17 Nov 2018 17:32:52 +0100
Subject: [PATCH] Add instructions

---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index f8aa97b..61d408d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,28 @@
+This firmware is intended to run on a NodeMCU with a relatively recent version of Arduino and its according [ESP8266 core](https://github.com/esp8266/Arduino) with BearSSL support (introduced in 2.4.2).
+
+It can be used against any server implementing the ESPhttpUpdate-"protocol" from the [Arduino ESP8266 project](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#http-server). This template is developed against the [esp-ota-update-server](https://git.geekify.de/sqozz/esp-ota-update-server) written in python which sits behind an nginx webserver for encryption with TLS1.2.
+
+It also uses [tzapu’s WiFiManager](https://github.com/tzapu/WiFiManager) to avoid exposing wifi access data in public hosted firmware binaries.
+
+The CA certificate store needs to be fetched and generated at the inital setup. You can either use [ESP8266 cores script](https://github.com/esp8266/Arduino/blob/945535ae78cad0586e5539f01335ff6bd3e6695f/libraries/ESP8266WiFi/examples/BearSSL_CertStore/certs-from-mozilla.py) to fetch the whole mozilla database (not tested) or create your own store which only trusts certain CAs.
+For my use, I rely on certificates issues by [https://letsencrypt.org](https://letsencrypt.org). To extract their CA you can use `openssl` against your domain which will host the firmware later on. I use `letsencrypt.org` here as example since it works too: 
+
+```
 openssl s_client -showcerts -servername letsencrypt.org -connect letsencrypt.org:443 </dev/null
+```
+
+Grab the according certificate and paste it into a text file. I used `le_x3_11_2018.pem`.
+
+```
 cat le_x3_11_2018.pem | openssl x509 -inform PEM -outform DER -out data/ca_le.der
 ar q data/certs.ar data/ca_le.der
+```
+
+The firmware will check on bootup if at least one CA is uploaded and will report the ammount over serial.
+The WiFiManger will only start up if a password for its configuration wlan is supplied - again, to avoid leakage over publicly hosted binaries, this password is stored out-of-band in the ESPs SPIFF flash storage and needs to be uploaded over USB once.
+
+Make sure to not include extra trailing characters since the firmware reads this file byte by byte:
+
+```
+echo -n "ChangeMe!2§" | data/config_password.txt
+```