diff options
Diffstat (limited to 'doc/sphinx/rest.rst')
| -rw-r--r-- | doc/sphinx/rest.rst | 318 |
1 files changed, 233 insertions, 85 deletions
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst index 0a081c4..79c1355 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 @@ -28,12 +28,14 @@ REST API .. _config: +----------------------- Receiving Configuration -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- .. http:get:: /config Obtain the configuration details of the escrow provider. + This specification corresponds to ``current`` protocol being version **0**. **Response:** @@ -53,6 +55,9 @@ Receiving Configuration // The format is "current:revision:age". version: string; + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; // Currency in which this provider processes payments. currency: string; @@ -79,7 +84,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; } @@ -97,8 +102,9 @@ Receiving Configuration .. _terms: +-------------------------- Receiving Terms of Service -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- .. http:get:: /terms @@ -122,8 +128,9 @@ Receiving Terms of Service .. _manage-policy: -Manage policy -^^^^^^^^^^^^^ +--------------- +Managing policy +--------------- This API is used by the Anastasis client to deposit or request encrypted recovery documents with the escrow provider. Generally, a client will deposit @@ -138,6 +145,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`` @@ -170,8 +217,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. @@ -184,7 +229,6 @@ In the following, UUID is always defined and used according to `RFC 4122`_. *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has received before from the server. The client SHOULD send this header with every request (except for the first request) to avoid unnecessary downloads. - *Anastasis-Account-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to download the requested encrypted recovery document. The purpose used MUST be ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401). .. http:post:: /policy/$ACCOUNT_PUB @@ -214,7 +258,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`` @@ -223,15 +267,19 @@ 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**: :http:statuscode:`204 No content`: - The encrypted recovery document was accepted and stored. ``Anastasis-Version`` and ``Anastasis-UUID`` headers - indicate what version and UUID was assigned to this encrypted recovery document upload by the server. + The encrypted recovery document was accepted and stored. ``Anastasis-Version`` + indicates what version was assigned to this encrypted recovery document upload by the server. + ``Anastasis-Policy-Expiration`` indicates the time until the server promises to store the policy, + in seconds since epoch. :http:statuscode:`304 Not modified`: The same encrypted recovery document was previously accepted and stored. ``Anastasis-Version`` header indicates what version was previously assigned to this encrypted recovery document. @@ -272,18 +320,17 @@ In the following, UUID is always defined and used according to `RFC 4122`_. .. ts:def:: RecoveryDocument interface RecoveryDocument { - // Account identifier at backup provider, AES-encrypted with - // the (symmetric) master_key, i.e. an URL - // https://sync.taler.net/$BACKUP_ID and - // a private key to decrypt the backup. Anastasis is oblivious - // to the details of how this is ultimately encoded. - backup_account: []; //bytearray of undefined length + // Human-readable name of the secret + secret_name?: string; + + // Encrypted core secret. + encrypted_core_secret: string; // bytearray of undefined length // List of escrow providers and selected authentication method. - methods: EscrowMethod[]; + escrow_methods: EscrowMethod[]; // List of possible decryption policies. - policy: DecryptionPolicy[]; + policies: DecryptionPolicy[]; } @@ -292,7 +339,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. interface EscrowMethod { // URL of the escrow provider (including possibly this Anastasis server). - provider_url : string; + url : string; // Type of the escrow method (e.g. security question, SMS etc.). escrow_type: string; @@ -302,21 +349,23 @@ In the following, UUID is always defined and used according to `RFC 4122`_. // Key used to encrypt the `Truth` this `EscrowMethod` is related to. // Client has to provide this key to the server when using ``/truth/``. - truth_encryption_key: [32]; //bytearray + truth_key: [32]; //bytearray + + // Salt used to hash the security answer if appliccable. + question_salt: [32]; //bytearray - // Salt used to encrypt the truth on the Anastasis server. - truth_salt: [32]; //bytearray + // Salt from the provider to derive the user ID + // at this provider. + provider_salt: [32]; //bytearray - // The challenge to give to the user (i.e. the security question + // The instructions to give to the user (i.e. the security question // if this is challenge-response). // (Q: as string in base32 encoding?) // (Q: what is the mime-type of this value?) // - // For some methods, this value may be absent. - // // The plaintext challenge is not revealed to the // Anastasis server. - challenge: []; //bytearray of undefined length + instructions: string; } @@ -326,22 +375,23 @@ 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. - 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 // escrow methods identified by UUID. - encrypted_master_key: [32]; //bytearray + master_key: [32]; //bytearray // List of escrow methods identified by their UUID. - uuid: string[]; + uuids: string[]; } .. _Truth: +-------------- Managing truth -^^^^^^^^^^^^^^ +-------------- Truth always consists of an encrypted key share and encrypted authentication data. The key share and the authentication data @@ -363,10 +413,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 @@ -419,23 +470,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. @@ -444,46 +494,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. - *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 @@ -509,44 +563,138 @@ charge per truth operation using GNU Taler. } - .. _KeyShare: - .. ts:def:: KeyShare interface KeyShare { - // Key material to concatenate with policy_salt and KDF to derive - // the key to decrypt the master key. + // Key material to derive the key to decrypt the master key. key_share: [32]; //bytearray + } - // Signature over method, UUID, and ``key_share``. - account_sig: EddsaSignature; + + .. _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; // What is the target IBAN? - credit_iban: String; + credit_iban: string; // What is the receiver name? - business_name: String; + 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; + 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; } |