diff options
Diffstat (limited to 'anastasis.rst')
| -rw-r--r-- | anastasis.rst | 54 |
1 files changed, 37 insertions, 17 deletions
diff --git a/anastasis.rst b/anastasis.rst index e282b2f0..355d0d7a 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -479,6 +479,8 @@ In the following, UUID is always defined and used according to `RFC 4122`_. In that case, the server MUST additionally respond with an "304" status code in case the resource matches the provided Etag. + **Response**: + :status 200 OK: The escrow provider responds with an EncryptedRecoveryDocument_ object. :status 304 Not modified: @@ -516,6 +518,39 @@ In the following, UUID is always defined and used according to `RFC 4122`_. Anastasis server cannot fully validate the format, but MAY impose minimum and maximum size limits. + **Request**: + + :query pay: + Optional argument, any non-empty value will do, + suggested is ``y`` for ``yes``. + The client insists on making a payment for the respective + account, even if this is not yet required. The server + will respond with a ``402 Payment required``, but only + if the rest of the request is well-formed (account + signature must match). Clients that do not actually + intend to make a new upload but that only want to pay + may attempt to upload the latest backup again, as this + option will be checked before the ``304 Not modified`` + case. + + *If-Match*: Unless the client expects to upload the first encrypted recovery document to this account, the client + SHOULD provide an Etag matching the latest version already known to the server. If this + header is present, the server MUST refuse the upload if the latest known version prior to + this upload does not match the given Etag. + + *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client. + The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue" + before uploading the body. The server MUST + use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded. + The server MUST refuse the upload with a "304" status code if the Etag matches + the latest version already known to the server. + + *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to upload an encrypted recovery document. + + *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see 402 status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a 402 response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. + + **Response**: + :status 204 No Content: The encrypted recovery document was accepted and stored. "Anastasis-Version" and "Anastasis-UUID" headers incidate what version and UUID was assigned to this encrypted recovery document upload by the server. @@ -536,23 +571,6 @@ In the following, UUID is always defined and used according to `RFC 4122`_. :status 413 Request Entity Too Large: The upload is too large *or* too small. The response body may elaborate on the error. - - *If-Match*: Unless the client expects to upload the first encrypted recovery document to this account, the client - SHOULD provide an Etag matching the latest version already known to the server. If this - header is present, the server MUST refuse the upload if the latest known version prior to - this upload does not match the given Etag. - - *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client. - The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue" - before uploading the body. The server MUST - use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded. - The server MUST refuse the upload with a "304" status code if the Etag matches - the latest version already known to the server. - - *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to upload an encrypted recovery document. - - *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see 402 status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a 402 response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. - **Details:** .. _EncryptedRecoveryDocument: @@ -724,6 +742,8 @@ charge per truth operation using GNU Taler. When $RESPONSE is correct, the server responses with the encrypted key share. The encrypted key share is returned simply as a byte array and not in JSON format. + **Response**: + :status 200 OK: EncryptedKeyShare_ is returned in body (in binary). :status 202 Accepted: |