proposal to address #7064

2 files changed, 222 insertions, 1 deletions

diff --git a/doc/sphinx/core/api-common.rst b/doc/sphinx/core/api-common.rst
index a7d77ba..423de2d 100644
--- a/doc/sphinx/core/api-common.rst
+++ b/doc/sphinx/core/api-common.rst
@@ -297,6 +297,14 @@ denoting microseconds since the UNIX Epoch.  ``UINT64_MAX`` represents "never".
   struct GNUNET_TIME_AbsoluteNBO {
     uint64_t abs_value_us__;       // in network byte order
   };
+  struct GNUNET_TIME_Timestamp {
+    // must be round value (multiple of seconds)
+    struct GNUNET_TIME_Absolute abs_time;
+  };
+  struct GNUNET_TIME_TimestampNBO {
+    // must be round value (multiple of seconds)
+    struct GNUNET_TIME_AbsoluteNBO abs_time;
+  };
 
 Cryptographic primitives
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -318,6 +326,13 @@ uses 512-bit hash codes (64 bytes).
      uint8_t ecdh_pub[32];
    };
 
+.. _ANASTASIS_TruthKeyP:
+.. sourcecode:: c
+
+   struct ANASTASIS_TruthKeyP {
+     struct GNUNET_HashCode key;
+   };
+
 .. sourcecode:: c
 
    struct UUID {
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst
index b5ab50d..18b389e 100644
--- a/doc/sphinx/rest.rst
+++ b/doc/sphinx/rest.rst
@@ -407,10 +407,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
@@ -469,6 +470,8 @@ 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.
@@ -611,3 +614,206 @@ charge per truth operation using GNU Taler.
       hint: string;
 
     }
+
+
+
+
+  .. 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.
+
+  **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.
+
+  **Response**:
+
+  :http:statuscode:`200 OK`:
+    `EncryptedKeyShare`_ is returned in body (in binary).
+  :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 `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:`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.
+
+  **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;
+    }
+
+
+  .. _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
+    }
+
+
+  .. _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;
+    }
+
+
+  .. _ChallengeInstructionMessage:
+  .. ts:def:: ChallengeInstructionMessage
+
+    type ChallengeInstructionMessage =
+      | IbanChallengeInstructionMessage
+      | PinChallengeInstructionMessage;
+
+    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;
+
+    }
+
+    interface PinChallengeInstructionMessage {
+
+      // What kind of challenge is this?
+      method: "pin";
+
+      // Where was the PIN code sent? Note that this
+      // address will most likely have been obscured
+      // to improve privacy.
+      address_hint: string;
+
+    }