taler-docs

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

post-reveal-withdraw.rst (4188B)

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