Challenge

README.md

@@ -1,5 +1,45 @@
-Mesozoa
+# Mesozoa
 
 Why not Anubis? Because it provides no build instructions and only supports Docker.
 
-Why not using Realm completely? Because the hook system is useless and only allows filtering.
+Why not using Realm completely? Because the hook system is useless and only allows filtering.
+
+## Install
+
+Must be used behind a reverse proxy providing `X-Forwarded-For`.
+
+## Challenge protocol
+
+### Challenge generation
+
+Sent by the server as a cookie.
+
+`secret <- chosen randomly, long term`
+
+`salt <- chosen randomly, not stored`
+
+`timestamp <- UNIX time in seconds, 64 bits, big endian`
+
+`ua <- User-Agent from request header`
+
+`ip <- X-Forwarded-For from request header (client's IP)`
+
+`set-cookie: mesozoa-challenge=BASE64(salt || timestamp || SHA3-256(secret || salt || timestamp || ip || "/" || ua))`
+
+Where `BASE64` is unpadded.
+
+### Challenge verification
+
+Request must contain both cookies `mesozoa-challenge` and `mesozoa-proof`.
+
+## Security
+
+### Network handling and HTTP parsing
+
+This implementation uses cheap tricks and regexes, is probably not fully compliant to HTTP specs, etc.
+You should probably not expose it directly to an open network.
+Please use it behind a safer reverse proxy like Apache or Nginx.
+
+### Length-extension attack
+
+SHA3 (used as a MAC in the challenge cookie) is not vulnerable. Values in the hash are either fixed-length, safe, or delimited.