taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-reveal-withdraw.rst (4499B)


      1 .. http:post:: /reveal-withdraw
      2 
      3   Reveal previously committed values to the exchange, except for the values
      4   corresponding to the ``noreveal_index`` returned by the :http:post:`/withdraw </withdraw>` step.
      5 
      6   The request body is a `RevealWithdrawRequest`.
      7 
      8   This endpoint was introduced in this form in protocol **v32**.
      9   Since protocol **v42** the request body must also carry the
     10   ``reserve_pub`` of the original :http:post:`/withdraw </withdraw>`
     11   request: a withdraw operation is identified by the pair
     12   (``reserve_pub``, ``planchets_h``), as in
     13   :http:post:`/recoup-withdraw </recoup-withdraw>`.  A given
     14   ``planchets_h`` may legitimately exist under more than one reserve.
     15 
     16   :http:statuscode:`200 OK`:
     17     The coin's' secret material matched the commitment and the original request was well-formed.
     18     The response body is a `RevealResponse`.
     19   :http:statuscode:`400 Bad Request`:
     20     The request from the client is malformed. Error codes used are:
     21 
     22     - ``TALER_EC_GENERIC_PARAMETER_MALFORMED``
     23     - ``TALER_EC_EXCHANGE_WITHDRAW_REVEAL_INVALID_HASH``
     24 
     25   :http:statuscode:`404 Not found`:
     26     The given reserve has no withdraw operation under the provided
     27     ``planchets_h``.
     28     Error code: ``TALER_EC_EXCHANGE_WITHDRAW_COMMITMENT_UNKNOWN``
     29   :http:statuscode:`413 Request entity too large`:
     30     The uploaded body is to long, it exceeds the size limit.
     31     Returned with an error code of
     32     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     33   :http:statuscode:`500 Internal Server Error`:
     34     Returned if the server had an internal issue processing the request.
     35     Error codes include:
     36 
     37     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     38     - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
     39 
     40   :http:statuscode:`503 Service unavailable`:
     41     The server could not process the request because it is currently
     42     unavailable. Error codes include:
     43     - ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``
     44 
     45   **Details:**
     46 
     47   Request body for a ``reveal-withdraw`` request
     48   contains a JSON object with the following fields:
     49 
     50   .. ts:def:: RevealWithdrawRequest
     51 
     52     interface RevealWithdrawRequest {
     53 
     54       // Public key of the reserve that the original call to
     55       // ``/withdraw`` was made from.  Together with ``planchets_h``
     56       // this identifies the withdraw operation.
     57       // Since protocol **v42**.
     58       reserve_pub: EddsaPublicKey;
     59 
     60       // This is the running hash of all blinded planchets
     61       // from the previous call to ``/withdraw``.
     62       planchets_h: string;
     63 
     64       // Array of ``(kappa - 1)`` disclosed batch secrets,
     65       // from which for each of the n coins in a batch
     66       // their coin master secret is derived,
     67       // from which in turn their private key,
     68       // blinding, nonce (for Clause-Schnorr) and
     69       // age-restriction is calculated.
     70       disclosed_batch_seeds: AgeRestrictedPlanchetSeed[];
     71 
     72     }
     73 
     74   .. ts:def:: AgeRestrictedPlanchetSeed
     75 
     76     // The master seed material from which for n coins in a batch,
     77     // each the coins' private key ``coin_priv``,  blinding ``beta``
     78     // and nonce ``nonce`` (for Clause-Schnorr) itself are
     79     // derived as usually in wallet-core.  Given a coin's master key material,
     80     // the age commitment for the coin MUST be derived from this private key as
     81     // follows:
     82     //
     83     // Let m ∈  {1,...,M} be the maximum age group as defined in the reserve
     84     // that the wallet can commit to.
     85     //
     86     // For age group $AG ∈  {1,...m}, set
     87     //     seed = HDKF(coin_secret, "age-commitment", $AG)
     88     //   p[$AG] = Edx25519_generate_private(seed)
     89     // and calculate the corresponding Edx25519PublicKey as
     90     //   q[$AG] = Edx25519_public_from_private(p[$AG])
     91     //
     92     // For age groups $AG ∈  {m+1,...,M}, set
     93     //   f[$AG] = HDKF(coin_secret, "age-factor", $AG)
     94     // and calculate the corresponding Edx25519PublicKey as
     95     //   q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG])
     96     //
     97     type AgeRestrictedPlanchetSeed = string;
     98 
     99   .. ts:def:: PublishedAgeRestrictionBaseKey
    100 
    101     // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen
    102     // `Edx25519PublicKey` for which the private key is not known to the clients.  It is
    103     // used during the age-withdraw protocol so that clients can prove that they
    104     // derived all public keys to age groups higher than their allowed maximum
    105     // from this particular value.
    106     const PublishedAgeRestrictionBaseKey =
    107         new Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG");