diff options
author | Christian Grothoff <christian@grothoff.org> | 2021-08-14 13:32:31 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2021-08-14 13:32:31 +0200 |
commit | f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6 (patch) | |
tree | 5b095579d4cc244f65472477a74c17674d329196 /doc/sphinx/rest.rst | |
parent | 71c62583d81f149cef2bdbe13870da70b50f3cbd (diff) | |
download | anastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.tar.gz anastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.tar.bz2 anastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.zip |
-more legwork for new auth method support
Diffstat (limited to 'doc/sphinx/rest.rst')
-rw-r--r-- | doc/sphinx/rest.rst | 39 |
1 files changed, 26 insertions, 13 deletions
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst index ba9d768..67c1fef 100644 --- a/doc/sphinx/rest.rst +++ b/doc/sphinx/rest.rst @@ -343,6 +343,13 @@ In the following, UUID is always defined and used according to `RFC 4122`_. Managing truth ^^^^^^^^^^^^^^ +Truth always consists of an encrypted key share and encrypted +authentication data. The key share and the authentication data +are encrypted using different keys. Additionally, truth includes +the name of the authentication method, the mime-type of the +authentication data, and an expiration time in +cleartext. + This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with the escrow provider. @@ -398,13 +405,6 @@ charge per truth operation using GNU Taler. // Key share method, i.e. "security question", "SMS", "e-mail", ... type: string; - // Nonce used to compute the (iv,key) pair for encryption of the - // encrypted_truth. - nonce: [32]; //bytearray - - // Authentication tag of ``encrypted_truth``. - aes_gcm_tag: [16]; //bytearray - // Variable-size truth. After decryption, // this contains the ground truth, i.e. H(challenge answer), // phone number, e-mail address, picture, fingerprint, ... @@ -412,10 +412,10 @@ charge per truth operation using GNU Taler. // // The nonce of the HKDF for this encryption must include the // string "ECT". - encrypted_truth: [80]; //bytearray + encrypted_truth: []; //bytearray // MIME type of truth, i.e. text/ascii, image/jpeg, etc. - truth_mime: string; + truth_mime?: string; // For how many years from now would the client like us to // store the truth? @@ -423,14 +423,23 @@ charge per truth operation using GNU Taler. } -.. http:get:: /truth/$UUID[?response=$H_RESPONSE] +.. http:get:: /truth/$UUID - Get the stored encrypted key share. If ``$H_RESPONSE`` is specified by the client, the server checks - if ``$H_RESPONSE`` matches the expected response specified before within the `TruthUploadRequest`_ (see ``encrypted_truth``). + Get the stored encrypted key share. Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). - When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share. The encrypted key share is returned simply as a byte array and not in JSON format. + :query response=H_RESPONSE: *Optional.* If ``$H_RESPONSE`` is specified by the client, + the server checks if ``$H_RESPONSE`` matches the expected response. This can be the + hash of the security question (as specified before by the client + within the `TruthUploadRequest`_ (see ``encrypted_truth``)), or the hash of the + PIN code sent via SMS, E-mail or postal communication channels. + When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share. + :query timeout_ms=NUMBER: *Optional.* If specified, the Anastasis server will + wait up to ``timeout_ms`` milliseconds for completion of the payment or the + challenge before sending the HTTP response. A client must never rely on this + behavior, as the backend may return a response immediately. + **Response**: :http:statuscode:`200 OK`: @@ -454,6 +463,10 @@ charge per truth operation using GNU Taler. The server requires a valid "response" to the challenge associated with the UUID. :http:statuscode:`404 Not found`: The server does not know any truth under the given UUID. + :http:statuscode:`408 Request Timeout`: + Accessing this truth requires satisfying an external authentication challenge + (and not merely passing a response in the request) and this has not happened + before the timeout was reached. :http:statuscode:`410 Gone`: The server has not (recently) issued a challenge under the given UUID, but a reply was provided. (This does not apply for secure question.) |