From 8abd2bc77ab3adfcc95f9cca24e43acc81dc8e19 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 12 Apr 2022 21:19:13 +0200 Subject: clean up status codes, remove old endpoint from API docs --- doc/sphinx/rest.rst | 149 ---------------------------------------------------- 1 file changed, 149 deletions(-) (limited to 'doc/sphinx') diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst index 4a5aad5..835ac6f 100644 --- a/doc/sphinx/rest.rst +++ b/doc/sphinx/rest.rst @@ -468,155 +468,6 @@ charge per truth operation using GNU Taler. } -.. http:get:: /truth/$UUID - - OLD API: - - Get the stored encrypted key share. - Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). - 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`: - `EncryptedKeyShare`_ is returned in body (in binary). - :http:statuscode:`202 Accepted`: - The escrow provider will respond out-of-band (i.e. SMS). - The body may contain human- or machine-readable instructions on next steps. - In case the response is in JSON, the format is given - by `ChallengeInstructionMessage`_. - :http:statuscode:`208 Already Reported`: - An authentication challenge was recently send, client should - simply respond to the pending challenge. - :http:statuscode:`303 See other`: - The provider redirects for authentication (i.e. video identification/WebRTC). - If the client is not a browser, it should launch a browser at the URL - given in the ``Location`` header and allow the user to re-try the operation - after successful authorization. - :http:statuscode:`402 Payment required`: - The service requires payment for access to truth. - See the Taler payment protocol specification for how to pay. - The response body MAY provide alternative means for payment. - :http:statuscode:`403 Forbidden`: - 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.) - :http:statuscode:`417 Expectation Failed`: - The decrypted ``truth`` does not match the expectations of the authentication - backend, i.e. a phone number for sending an SMS is not a number, or - an e-mail address for sending an E-mail is not a valid e-mail address. - :http:statuscode:`429 Too Many Requests`: - The client exceeded the number of allowed attempts at providing - a valid response for the given time interval. - The response format is given by `RateLimitedMessage`_. - :http:statuscode:`503 Service Unavailable`: - Server is out of Service. - - *Anastasis-Truth-Decryption-Key*: Key used to encrypt the **truth** (see encrypted_truth within `TruthUploadRequest`_) and which has to provided by the user. The key is stored with - the according `EscrowMethod`_. The server needs this key to get the info out of `TruthUploadRequest`_ needed to verify the ``$RESPONSE``. - - **Details:** - - .. _EncryptedKeyShare: - .. ts:def:: EncryptedKeyShare - - interface EncryptedKeyShare { - // Nonce used to compute the decryption (iv,key) pair. - nonce_i: [32]; //bytearray - - // Authentication tag. - aes_gcm_tag_i: [16]; //bytearray - - // Encrypted key-share in base32 encoding. - // After decryption, this yields a `KeyShare`. Note that - // the `KeyShare` MUST be encoded as a fixed-size binary - // block (instead of in JSON encoding). - // - // HKDF for the key generation must include the - // string "eks" as salt. - // Depending on the method, - // the HKDF may additionally include - // bits from the response (i.e. some hash over the - // answer to the security question). - encrypted_key_share_i: [32]; //bytearray - - } - - - interface KeyShare { - // Key material to derive the key to decrypt the master key. - key_share: [32]; //bytearray - } - - - .. _ChallengeInstructionMessage: - .. ts:def:: ChallengeInstructionMessage - - type ChallengeInstructionMessage = - | IbanChallengeInstructionMessage; - - interface IbanChallengeInstructionMessage { - - // What kind of challenge is this? - method: "iban"; - - // How much should be wired? - amount: Amount; - - // What is the target IBAN? - credit_iban: string; - - // What is the receiver name? - business_name: string; - - // What is the expected wire transfer subject? - wire_transfer_subject: number; - - // Hint about the origin account that must be used. - debit_account_hint: string; - - } - - - .. _RateLimitedMessage: - .. ts:def:: RateLimitedMessage - - interface RateLimitedMessage { - - // Taler error code, TALER_EC_ANASTASIS_TRUTH_RATE_LIMITED. - code: number; - - // How many attempts are allowed per challenge? - request_limit: number; - - // At what frequency are new challenges issued? - request_frequency: RelativeTime; - - // The error message. - hint: string; - - } - - - .. http:post:: /truth/$UUID/solve -- cgit v1.2.3