|author||Christian Grothoff <email@example.com>||2021-08-14 13:32:31 +0200|
|committer||Christian Grothoff <firstname.lastname@example.org>||2021-08-14 13:32:31 +0200|
-more legwork for new auth method support
Diffstat (limited to 'doc/sphinx/rest.rst')
1 files changed, 26 insertions, 13 deletions
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst
index ba9d768..67c1fef 100644
@@ -343,6 +343,13 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
+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
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", ...
- // Nonce used to compute the (iv,key) pair for encryption of the
- // encrypted_truth.
- nonce: ; //bytearray
- // Authentication tag of ``encrypted_truth``.
- aes_gcm_tag: ; //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: ; //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.
@@ -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.
The server has not (recently) issued a challenge under the given UUID,
but a reply was provided. (This does not apply for secure question.)