aboutsummaryrefslogtreecommitdiff
path: root/doc/sphinx/rest.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sphinx/rest.rst')
-rw-r--r--doc/sphinx/rest.rst39
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`_.
343Managing truth 343Managing truth
344^^^^^^^^^^^^^^ 344^^^^^^^^^^^^^^
345 345
346Truth always consists of an encrypted key share and encrypted
347authentication data. The key share and the authentication data
348are encrypted using different keys. Additionally, truth includes
349the name of the authentication method, the mime-type of the
350authentication data, and an expiration time in
351cleartext.
352
346This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with 353This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with
347the escrow provider. 354the escrow provider.
348 355
@@ -398,13 +405,6 @@ charge per truth operation using GNU Taler.
398 // Key share method, i.e. "security question", "SMS", "e-mail", ... 405 // Key share method, i.e. "security question", "SMS", "e-mail", ...
399 type: string; 406 type: string;
400 407
401 // Nonce used to compute the (iv,key) pair for encryption of the
402 // encrypted_truth.
403 nonce: [32]; //bytearray
404
405 // Authentication tag of ``encrypted_truth``.
406 aes_gcm_tag: [16]; //bytearray
407
408 // Variable-size truth. After decryption, 408 // Variable-size truth. After decryption,
409 // this contains the ground truth, i.e. H(challenge answer), 409 // this contains the ground truth, i.e. H(challenge answer),
410 // phone number, e-mail address, picture, fingerprint, ... 410 // phone number, e-mail address, picture, fingerprint, ...
@@ -412,10 +412,10 @@ charge per truth operation using GNU Taler.
412 // 412 //
413 // The nonce of the HKDF for this encryption must include the 413 // The nonce of the HKDF for this encryption must include the
414 // string "ECT". 414 // string "ECT".
415 encrypted_truth: [80]; //bytearray 415 encrypted_truth: []; //bytearray
416 416
417 // MIME type of truth, i.e. text/ascii, image/jpeg, etc. 417 // MIME type of truth, i.e. text/ascii, image/jpeg, etc.
418 truth_mime: string; 418 truth_mime?: string;
419 419
420 // For how many years from now would the client like us to 420 // For how many years from now would the client like us to
421 // store the truth? 421 // store the truth?
@@ -423,14 +423,23 @@ charge per truth operation using GNU Taler.
423 423
424 } 424 }
425 425
426.. http:get:: /truth/$UUID[?response=$H_RESPONSE] 426.. http:get:: /truth/$UUID
427 427
428 Get the stored encrypted key share. If ``$H_RESPONSE`` is specified by the client, the server checks 428 Get the stored encrypted key share.
429 if ``$H_RESPONSE`` matches the expected response specified before within the `TruthUploadRequest`_ (see ``encrypted_truth``).
430 Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). 429 Also, the user has to provide the correct *truth_encryption_key* with every get request (see below).
431 When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share.
432 The encrypted key share is returned simply as a byte array and not in JSON format. 430 The encrypted key share is returned simply as a byte array and not in JSON format.
433 431
432 :query response=H_RESPONSE: *Optional.* If ``$H_RESPONSE`` is specified by the client,
433 the server checks if ``$H_RESPONSE`` matches the expected response. This can be the
434 hash of the security question (as specified before by the client
435 within the `TruthUploadRequest`_ (see ``encrypted_truth``)), or the hash of the
436 PIN code sent via SMS, E-mail or postal communication channels.
437 When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share.
438 :query timeout_ms=NUMBER: *Optional.* If specified, the Anastasis server will
439 wait up to ``timeout_ms`` milliseconds for completion of the payment or the
440 challenge before sending the HTTP response. A client must never rely on this
441 behavior, as the backend may return a response immediately.
442
434 **Response**: 443 **Response**:
435 444
436 :http:statuscode:`200 OK`: 445 :http:statuscode:`200 OK`:
@@ -454,6 +463,10 @@ charge per truth operation using GNU Taler.
454 The server requires a valid "response" to the challenge associated with the UUID. 463 The server requires a valid "response" to the challenge associated with the UUID.
455 :http:statuscode:`404 Not found`: 464 :http:statuscode:`404 Not found`:
456 The server does not know any truth under the given UUID. 465 The server does not know any truth under the given UUID.
466 :http:statuscode:`408 Request Timeout`:
467 Accessing this truth requires satisfying an external authentication challenge
468 (and not merely passing a response in the request) and this has not happened
469 before the timeout was reached.
457 :http:statuscode:`410 Gone`: 470 :http:statuscode:`410 Gone`:
458 The server has not (recently) issued a challenge under the given UUID, 471 The server has not (recently) issued a challenge under the given UUID,
459 but a reply was provided. (This does not apply for secure question.) 472 but a reply was provided. (This does not apply for secure question.)