From 125c937d466db13e27ab06cc40e5d68aa5d93d28 Mon Sep 17 00:00:00 2001
From: Itamar Turner-Trauring <itamar@itamarst.org>
Date: Thu, 28 Oct 2021 10:49:08 -0400
Subject: [PATCH] Switch to HTTP header scheme.

---
 docs/proposed/http-storage-node-protocol.rst | 38 ++++++++++++--------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst
index d5b6653be..fd1db5c4c 100644
--- a/docs/proposed/http-storage-node-protocol.rst
+++ b/docs/proposed/http-storage-node-protocol.rst
@@ -450,16 +450,22 @@ A lease is also created for the shares.
 Details of the buckets to create are encoded in the request body.
 For example::
 
-  {"renew-secret": "efgh", "cancel-secret": "ijkl",
-   "upload-secret": "xyzf",
-   "share-numbers": [1, 7, ...], "allocated-size": 12345}
+  {"share-numbers": [1, 7, ...], "allocated-size": 12345}
+
+The request must include ``WWW-Authenticate`` HTTP headers that set the various secrets—upload, lease renewal, lease cancellation—that will be later used to authorize various operations.
+Typically this is a header sent by the server, but in Tahoe-LAFS keys are set by the client, so may as well reuse it.
+For example::
+
+   WWW-Authenticate: x-tahoe-renew-secret <base64-renew-secret>
+   WWW-Authenticate: x-tahoe-cancel-secret <base64-cancel-secret>
+   WWW-Authenticate: x-tahoe-upload-secret <base64-upload-secret>
 
 The response body includes encoded information about the created buckets.
 For example::
 
   {"already-have": [1, ...], "allocated": [7, ...]}
 
-The uplaod secret is an opaque _byte_ string.
+The upload secret is an opaque _byte_ string.
 It will be generated by hashing a combination of:b
 
 1. A tag.
@@ -521,9 +527,9 @@ If any one of these requests fails then at most 128KiB of upload work needs to b
 The server must recognize when all of the data has been received and mark the share as complete
 (which it can do because it was informed of the size when the storage index was initialized).
 
-The request body looks this, with data and upload secret being bytes::
+The request must include a ``Authorization`` header that includes the upload secret::
 
-    { "upload-secret": "xyzf", "data": "thedata" }
+    Authorization: x-tahoe-upload-secret <base64ed-upload-secret>
 
 Responses:
 
@@ -727,9 +733,11 @@ Immutable Data
 1. Create a bucket for storage index ``AAAAAAAAAAAAAAAA`` to hold two immutable shares, discovering that share ``1`` was already uploaded::
 
      POST /v1/immutable/AAAAAAAAAAAAAAAA
-     {"renew-secret": "efgh", "cancel-secret": "ijkl",
-      "upload-secret": "xyzf",
-      "share-numbers": [1, 7], "allocated-size": 48}
+     WWW-Authenticate: x-tahoe-renew-secret efgh
+     WWW-Authenticate: x-tahoe-cancel-secret jjkl
+     WWW-Authenticate: x-tahoe-upload-secret xyzf
+
+     {"share-numbers": [1, 7], "allocated-size": 48}
 
      200 OK
      {"already-have": [1], "allocated": [7]}
@@ -738,22 +746,22 @@ Immutable Data
 
      PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
      Content-Range: bytes 0-15/48
-
-     {"upload-secret": b"xyzf", "data": "first 16 bytes!!"
+     Authorization: x-tahoe-upload-secret xyzf
+     <first 16 bytes of share data>
 
      200 OK
 
      PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
      Content-Range: bytes 16-31/48
-
-     {"upload-secret": "xyzf", "data": "second 16 bytes!"
+     Authorization: x-tahoe-upload-secret xyzf
+     <second 16 bytes of share data>
 
      200 OK
 
      PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
      Content-Range: bytes 32-47/48
-
-     {"upload-secret": "xyzf", "data": "final 16 bytes!!"
+     Authorization: x-tahoe-upload-secret xyzf
+     <final 16 bytes of share data>
 
      201 CREATED