From 24646c56d0aae56bd18d2d2ffa2acf1616cc2a62 Mon Sep 17 00:00:00 2001 From: Itamar Turner-Trauring Date: Thu, 11 Nov 2021 11:29:05 -0500 Subject: [PATCH] Updates based on review. --- docs/proposed/http-storage-node-protocol.rst | 43 ++++++++------------ 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst index 19a64f5ca..44bda1205 100644 --- a/docs/proposed/http-storage-node-protocol.rst +++ b/docs/proposed/http-storage-node-protocol.rst @@ -397,22 +397,15 @@ For example:: Either renew or create a new lease on the bucket addressed by ``storage_index``. -For a renewal, the renew secret and cancellation secret should be included as ``X-Tahoe-Authorization`` headers. +The renew secret and cancellation secret should be included as ``X-Tahoe-Authorization`` headers. For example:: X-Tahoe-Authorization: lease-renew-secret X-Tahoe-Authorization: lease-cancel-secret -For a new lease, ``X-Tahoe-Set-Authorization`` headers should be used instead. -For example:: - - X-Tahoe-Set-Authorization: lease-renew-secret - X-Tahoe-Set-Authorization: lease-cancel-secret - -For renewal, the expiration time of that lease will be changed to 31 days after the time of this operation. -If the renewal secret does not match, a new lease will be created, but clients should still not rely on this behavior if possible, and instead use the appropriate new lease headers. - -For the creation path, +If the ``lease-renew-secret`` value matches an existing lease +then the expiration time of that lease will be changed to 31 days after the time of this operation. +If it does not match an existing lease then a new lease will be created with this ``lease-renew-secret`` which expires 31 days after the time of this operation. ``lease-renew-secret`` and ``lease-cancel-secret`` values must be 32 bytes long. @@ -433,7 +426,9 @@ Discussion `````````` We considered an alternative where ``lease-renew-secret`` and ``lease-cancel-secret`` are placed in query arguments on the request path. -We chose to put these values into the request body to make the URL simpler. +This increases chances of leaking secrets in logs. +Putting the secrets in the body reduces the chances of leaking secrets, +but eventually we chose headers as the least likely information to be logged. Several behaviors here are blindly copied from the Foolscap-based storage server protocol. @@ -461,13 +456,13 @@ For example:: {"share-numbers": [1, 7, ...], "allocated-size": 12345} -The request must include ``X-Tahoe-Set-Authorization`` HTTP headers that set the various secrets—upload, lease renewal, lease cancellation—that will be later used to authorize various operations. +The request must include ``X-Tahoe-Authorization`` 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:: - X-Tahoe-Set-Authorization: lease-renew-secret - X-Tahoe-Set-Authorization: lease-cancel-secret - X-Tahoe-Set-Authorization: upload-secret + X-Tahoe-Authorization: lease-renew-secret + X-Tahoe-Authorization: lease-cancel-secret + X-Tahoe-Authorization: upload-secret The response body includes encoded information about the created buckets. For example:: @@ -475,12 +470,6 @@ For example:: {"already-have": [1, ...], "allocated": [7, ...]} The upload secret is an opaque _byte_ string. -It will be generated by hashing a combination of:b - -1. A tag. -2. The storage index, so it's unique across different source files. -3. The server ID, so it's unique across different servers. -4. The convergence secret, so that servers can't guess the upload secret for other servers. Discussion `````````` @@ -508,7 +497,7 @@ The response includes ``already-have`` and ``allocated`` for two reasons: Regarding upload secrets, the goal is for uploading and aborting (see next sections) to be authenticated by more than just the storage index. -In the future, we will want to generate them in a way that allows resuming/canceling when the client has issues. +In the future, we may want to generate them in a way that allows resuming/canceling when the client has issues. In the short term, they can just be a random byte string. The key security constraint is that each upload to each server has its own, unique upload key, tied to uploading that particular storage index to this particular server. @@ -566,7 +555,7 @@ Responses: This cancels an *in-progress* upload. -The request must include a ``Authorization`` header that includes the upload secret:: +The request must include a ``X-Tahoe-Authorization`` header that includes the upload secret:: X-Tahoe-Authorization: upload-secret @@ -743,9 +732,9 @@ Immutable Data POST /v1/immutable/AAAAAAAAAAAAAAAA Authorization: Tahoe-LAFS nurl-swissnum - X-Tahoe-Set-Authorization: lease-renew-secret efgh - X-Tahoe-Set-Authorization: lease-cancel-secret jjkl - X-Tahoe-Set-Authorization: upload-secret xyzf + X-Tahoe-Authorization: lease-renew-secret efgh + X-Tahoe-Authorization: lease-cancel-secret jjkl + X-Tahoe-Authorization: upload-secret xyzf {"share-numbers": [1, 7], "allocated-size": 48}