diff options
Diffstat (limited to 'doc/sphinx/rest.rst')
| -rw-r--r-- | doc/sphinx/rest.rst | 256 |
1 files changed, 203 insertions, 53 deletions
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst index a1c5810..d1fb790 100644 --- a/doc/sphinx/rest.rst +++ b/doc/sphinx/rest.rst @@ -1,6 +1,6 @@ .. This file is part of Anastasis - Copyright (C) 2019-2021 Anastasis SARL + Copyright (C) 2019-2022 Anastasis SARL Anastasis is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -35,6 +35,7 @@ Receiving Configuration .. http:get:: /config Obtain the configuration details of the escrow provider. + This specification corresponds to ``current`` protocol being version **0**. **Response:** @@ -54,8 +55,12 @@ Receiving Configuration // The format is "current:revision:age". version: string; - // Currency in which this provider processes payments. - currency: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + + // Name of the business operating the service (for display to the user). + business_name?: string; // Supported authorization methods. methods: AuthorizationMethodConfig[]; @@ -80,7 +85,7 @@ Receiving Configuration // **provider salt** is then used in various operations to ensure // cryptographic operations differ by provider. A provider must // never change its salt value. - server_salt: string; + provider_salt: string; } @@ -141,6 +146,46 @@ In the following, UUID is always defined and used according to `RFC 4122`_. .. _`RFC 4122`: https://tools.ietf.org/html/rfc4122 +.. http:get:: /policy/$ACCOUNT_PUB/meta[?max_version=$NUMBER] + + Get meta data about a customer's encrypted recovery documents. + If ``max_version`` is specified, only return results up to the + given version number. The response may not contain meta data + for all versions if there are way too many. In this case, + ``max_version`` must be used to incrementally fetch more versions. + + **Response**: + + :http:statuscode:`200 OK`: + The escrow provider responds with a RecoveryMetaSummary_ object. + :http:statuscode:`400 Bad request`: + The ``$ACCOUNT_PUB`` is not an EdDSA public key. + :http:statuscode:`402 Payment Required`: + The account's balance is too low for the specified operation. + See the Taler payment protocol specification for how to pay. + :http:statuscode:`404 Not found`: + The requested resource was not found. + + **Details:** + + .. _RecoveryMetaSummary: + .. ts:def:: RecoveryMetaSummary + + interface RecoveryMetaSummary { + // Version numbers as a string (!) are used as keys. + "$VERSION": MetaData; + } + + interface MetaData { + // The meta value can be NULL if the document + // exists but no meta data was provided. + meta: string; + + // Server-time indicative of when the recovery + // document was uploaded. + upload_time: Timestamp; + } + .. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER] Get the customer's encrypted recovery document. If ``version`` @@ -173,8 +218,6 @@ In the following, UUID is always defined and used according to `RFC 4122`_. :http:statuscode:`402 Payment Required`: The account's balance is too low for the specified operation. See the Taler payment protocol specification for how to pay. - :http:statuscode:`403 Forbidden`: - The required account signature was invalid. :http:statuscode:`404 Not found`: The requested resource was not found. @@ -216,7 +259,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. :query timeout_ms=NUMBER: *Optional.* If specified, the Anastasis server will wait up to ``timeout_ms`` milliseconds for completion of the payment before sending the HTTP response. A client must never rely on this behavior, as the - backend may return a response immediately. + backend may return a response immediately. If a ``timeout_ms`` is not given, the Anastasis server may apply a default timeout (usually 30s) when talking to the merchant backend. *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client. The client SHOULD also set the ``Expect: 100-Continue`` header and wait for ``100 continue`` @@ -225,9 +268,11 @@ In the following, UUID is always defined and used according to `RFC 4122`_. The server MUST refuse the upload with a ``304`` status code if the Etag matches the latest version already known to the server. + *Anastasis-Policy-Meta-Data*: Encrypted meta data to be stored by the server and returned with the respective endpoint to provide an overview of the available policies. Encrypted using a random nonce and a key derived from the user ID using the salt "rmd". The plaintext metadata must consist of the policy hash (for deduplication) and the (human readable) secret name. + *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to upload an encrypted recovery document. - *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see ``402`` status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a ``402`` response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. + *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see ``402`` status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a ``402`` response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. If a payment identifier is given, the Anastasis backend may block for the payment to be confirmed by Taler as specified by the ``timeout_ms`` argument. **Response**: @@ -308,7 +353,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. truth_key: [32]; //bytearray // Salt used to hash the security answer if appliccable. - truth_salt: [32]; //bytearray + question_salt: [32]; //bytearray // Salt from the provider to derive the user ID // at this provider. @@ -331,7 +376,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. interface DecryptionPolicy { // Salt included to encrypt master key share when // using this decryption policy. - salt: [32]; //bytearray + master_salt: [32]; //bytearray // Master key, AES-encrypted with key derived from // salt and keyshares revealed by the following list of @@ -369,10 +414,11 @@ charge per truth operation using GNU Taler. .. http:post:: /truth/$UUID + **Request:** + Upload a `TruthUploadRequest`_-Object according to the policy the client created before (see `RecoveryDocument`_). If request has been seen before, the server should do nothing, and otherwise store the new object. - **Request:** :query timeout_ms=NUMBER: *Optional.* If specified, the Anastasis server will wait up to ``timeout_ms`` milliseconds for completion of the payment before @@ -425,23 +471,22 @@ charge per truth operation using GNU Taler. // For how many years from now would the client like us to // store the truth? - storage_duration_years: Integer; + storage_duration_years: number; } -.. http:get:: /truth/$UUID - Get the stored encrypted key share. - Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). + .. http:post:: /truth/$UUID/solve + + Solve the challenge and get the stored encrypted key share. + Also, the user has to provide the correct *truth_encryption_key* with the 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 + **Request**: + + Upload a `TruthSolutionRequest`_-Object. + + :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. @@ -450,46 +495,50 @@ charge per truth operation using GNU Taler. :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. + The `h_response` provided is not a good response to the challenge associated + with the UUID, or at least the answer is not valid yet. A generic + response is provided with an error code. :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:** + .. _TruthSolutionRequest: + .. ts:def:: TruthSolutionRequest + + interface TruthSolutionRequest { + + // Hash over the response that solves the challenge + // issued for this truth. 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. + // Only when ``$H_RESPONSE`` is correct, the server responds with the encrypted key share. + h_response: HashCode; + + // Key that was 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`_ to verify the ``h_response``. + truth_decryption_key: ANASTASIS_TruthKeyP; + + // Reference to a payment made by the client to + // pay for this request. Optional. + payment_secret?: ANASTASIS_PaymentSecretP; + } + + .. _EncryptedKeyShare: .. ts:def:: EncryptedKeyShare @@ -522,16 +571,90 @@ charge per truth operation using GNU Taler. } + .. _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/challenge + + NEW API (#7064): + + Initiate process to solve challenge associated with the given truth object. + + **Request**: + + Upload a `TruthChallengeRequest`_-Object. + + **Response**: + + :http:statuscode:`200 Ok`: + 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:`402 Payment required`: + The service requires payment to issue a challenge. + See the Taler payment protocol specification for how to pay. + The response body MAY provide alternative means for payment. + :http:statuscode:`403 Forbidden`: + This type of truth does not permit requests to trigger a challenge. + This is the case for security questions and TOTP methods. + :http:statuscode:`404 Not found`: + The server does not know any truth under the given UUID. + :http:statuscode:`424 Failed Dependency`: + 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:`503 Service Unavailable`: + Server is out of Service. + + **Details:** + + .. _TruthChallengeRequest: + .. ts:def:: TruthChallengeRequest + + interface TruthChallengeRequest { + + // Key that was 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`_ to verify the ``h_response``. + truth_decryption_key: ANASTASIS_TruthKeyP; + + // Reference to a payment made by the client to + // pay for this request. Optional. + payment_secret?: ANASTASIS_PaymentSecretP; + } + + .. _ChallengeInstructionMessage: .. ts:def:: ChallengeInstructionMessage type ChallengeInstructionMessage = - | IbanChallengeInstructionMessage; + | FileChallengeInstructionMessage + | IbanChallengeInstructionMessage + | PinChallengeInstructionMessage; interface IbanChallengeInstructionMessage { // What kind of challenge is this? - method: "iban"; + method: "IBAN_WIRE"; // How much should be wired? amount: Amount; @@ -543,9 +666,36 @@ charge per truth operation using GNU Taler. business_name: string; // What is the expected wire transfer subject? - wire_transfer_subject: Integer; + wire_transfer_subject: string; + + // What is the numeric code (also part of the + // wire transfer subject) to be hashed when + // solving the challenge? + answer_code: number; // Hint about the origin account that must be used. debit_account_hint: string; } + + interface PinChallengeInstructionMessage { + + // What kind of challenge is this? + method: "TAN_SENT"; + + // Where was the PIN code sent? Note that this + // address will most likely have been obscured + // to improve privacy. + tan_address_hint: string; + + } + + interface FileChallengeInstructionMessage { + + // What kind of challenge is this? + method: "FILE_WRITTEN"; + + // Name of the file where the PIN code was written. + filename: string; + + } |