taler-docs

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

post-reveal-withdraw.rst (4184B)

      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 ``/withdraw`` step.
      5 
      6   The base URL for ``/reveal-withdraw``-request may differ from the main base URL of
      7   the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
      8   coin during melt operations. The exchange MUST return a
      9   307 or 308 redirection to the correct base URL if the client failed to
     10   respect the ``reveal_base_url`` or if the allocation has changed.
     11 
     12   The request body is a `RevealWithdrawRequest`.
     13 
     14   This endpoint was introduced in this form in protocol **v32**.
     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     - ``TALER_EC_GENERIC_PARAMETER_MALFORMED``
     22     - ``TALER_EC_EXCHANGE_WITHDRAW_REVEAL_INVALID_HASH``
     23   :http:statuscode:`404 Not found`:
     24     The provided commitment $RCH is unknown.
     25     Error code: ``TALER_EC_EXCHANGE_WITHDRAW_COMMITMENT_UNKNOWN``
     26   :http:statuscode:`413 Request entity too large`:
     27     The uploaded body is to long, it exceeds the size limit.
     28     Returned with an error code of
     29     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     30   :http:statuscode:`500 Internal Server Error`:
     31     Returned if the server had an internal issue processing the request.
     32     Error codes include:
     33     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     34     - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
     35   :http:statuscode:`503 Service unavailable`:
     36     The server could not process the request because it is currently
     37     unavailable. Error codes include:
     38     - ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``
     39 
     40   **Details:**
     41 
     42   Request body for a ``reveal-withdraw`` request
     43   contains a JSON object with the following fields:
     44 
     45   .. ts:def:: RevealWithdrawRequest
     46 
     47     interface RevealWithdrawRequest {
     48 
     49       // This is the running hash of all blinded planchets
     50       // from the previous call to ``/withdraw``.
     51       planchets_h: string;
     52 
     53       // Array of ``(kappa - 1)`` disclosed batch secrets,
     54       // from which for each of the n coins in a batch
     55       // their coin master secret is derived,
     56       // from which in turn their private key,
     57       // blinding, nonce (for Clause-Schnorr) and
     58       // age-restriction is calculated.
     59       disclosed_batch_seeds: AgeRestrictedPlanchetSeed[];
     60 
     61     }
     62 
     63   .. ts:def:: AgeRestrictedPlanchetSeed
     64 
     65     // The master seed material from which for n coins in a batch,
     66     // each the coins' private key ``coin_priv``,  blinding ``beta``
     67     // and nonce ``nonce`` (for Clause-Schnorr) itself are
     68     // derived as usually in wallet-core.  Given a coin's master key material,
     69     // the age commitment for the coin MUST be derived from this private key as
     70     // follows:
     71     //
     72     // Let m ∈  {1,...,M} be the maximum age group as defined in the reserve
     73     // that the wallet can commit to.
     74     //
     75     // For age group $AG ∈  {1,...m}, set
     76     //     seed = HDKF(coin_secret, "age-commitment", $AG)
     77     //   p[$AG] = Edx25519_generate_private(seed)
     78     // and calculate the corresponding Edx25519PublicKey as
     79     //   q[$AG] = Edx25519_public_from_private(p[$AG])
     80     //
     81     // For age groups $AG ∈  {m+1,...,M}, set
     82     //   f[$AG] = HDKF(coin_secret, "age-factor", $AG)
     83     // and calculate the corresponding Edx25519PublicKey as
     84     //   q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG])
     85     //
     86     type AgeRestrictedPlanchetSeed = string;
     87 
     88   .. ts:def:: PublishedAgeRestrictionBaseKey
     89 
     90     // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen
     91     // `Edx25519PublicKey` for which the private key is not known to the clients.  It is
     92     // used during the age-withdraw protocol so that clients can prove that they
     93     // derived all public keys to age groups higher than their allowed maximum
     94     // from this particular value.
     95     const PublishedAgeRestrictionBaseKey =
     96         new Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG");