From f6a64e01947c2e38d4dc3ae8b29cb7ecae70e3cd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 27 Feb 2022 18:34:06 +0100 Subject: proposal to address #7064 --- doc/sphinx/core/api-common.rst | 15 +++ doc/sphinx/rest.rst | 208 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 222 insertions(+), 1 deletion(-) (limited to 'doc/sphinx') 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; + + } -- cgit v1.2.3