taler-docs

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

post-reveal-withdraw.rst (4864B)

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