diff options
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`_. | |||
343 | Managing truth | 343 | Managing truth |
344 | ^^^^^^^^^^^^^^ | 344 | ^^^^^^^^^^^^^^ |
345 | 345 | ||
346 | Truth always consists of an encrypted key share and encrypted | ||
347 | authentication data. The key share and the authentication data | ||
348 | are encrypted using different keys. Additionally, truth includes | ||
349 | the name of the authentication method, the mime-type of the | ||
350 | authentication data, and an expiration time in | ||
351 | cleartext. | ||
352 | |||
346 | This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with | 353 | This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with |
347 | the escrow provider. | 354 | the 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.) |