From 54d980afcbd6f0011d6a162e0003587d26a3e311 Mon Sep 17 00:00:00 2001
From: Rasmus Dahlberg <rasmus@rgdd.se>
Date: Mon, 25 Dec 2023 13:37:53 +0100
Subject: Describe HTTP API

---
 docs/http-api.md | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/docs/http-api.md b/docs/http-api.md
index 51a5ec4..d78f2ee 100644
--- a/docs/http-api.md
+++ b/docs/http-api.md
@@ -1,8 +1,29 @@
-# Server API
+# HTTP API
 
-docdoc
+The monitor listens for HTTP POST requests on a well-known endpoint.  For
+example, the well-known endpoint might be `https://example.com/add-chain` or
+`http://exampled3jsb2t6n2f5f6r4v4gkqmqd7h4hjucwb7y5.onion/add-chain`.
 
-## Authentication
-## Endpoints
-### get-status
-### add-chain
+The HTTP POST request body should be an X.509v3 chain in PEM format.  The first
+certificate must be a leaf.  The remaining certificates must be CA certificates.
+
+To authenticate the node adding a certificate chain to the monitor, the HTTP
+authorization header needs to be present and carry a valid value.
+
+    Authorization: TYPE NAME:VALUE
+
+`TYPE`: custom HTTP authorization type used by the monitor, set to "silent-ct".
+
+`NAME`: identifier that the monitor uses to locate the right pre-shared secret.
+
+`VALUE`: HMAC with SHA256 as the hash function for the entire HTTP POST request
+body.  The HMAC key is derived by the node and the monitor from the pre-shared
+secret `SECRET`, node name `NAME`, and HTTP authorization type `TYPE`.  In Go:
+
+    hkdf := hkdf.New(sha256.New, SECRET, TYPE, NAME)
+    key := make([]byte, 16)
+    io.ReadFull(hkdf, key)
+
+On successful processing of a request, the monitor outputs HTTP 200 OK.  If the
+HMAC value is incorrect or the node is not allowed to request certificates for
+the domain names in the request body, the monitor outputs HTTP 401 Unauthorized.
-- 
cgit v1.2.3