commit f4dc6f0386c040ac6f5704481361c3999d0b0b32
parent a2947052a4ff1af4e8d50772ba34155d30f2e287
Author: Özgür Kesim <oec@kesim.org>
Date: Tue, 25 Feb 2025 12:24:30 +0100
[exchange] move commitment hashes from url to body
In both, /reveal-withdraw und /reveal-melt, the
commitment has been moved from the URL to the
json request.
Diffstat:
1 file changed, 18 insertions(+), 20 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1730,7 +1730,7 @@ Withdraw
:http:statuscode:`201 Created`:
The request was successful, and ``max_age`` was set.
The response is a `AgeWithdrawResponse`. The client is expected
- to call ``/reveal-withdraw/$ACH`` next.
+ to call ``/reveal-withdraw`` next.
Note that repeating exactly the same request will again yield the same
response, so if the network goes down during the transaction or before the
client can commit the coins signature to disk, the coins are not lost.
@@ -1835,8 +1835,6 @@ Withdraw
// respond with an index ``gamma``, which is the index
// that shall remain undisclosed during the subsequent
// reveal phase.
- // The SHA512 hash $ACH over the blinded coin envelopes is the
- // commitment that is later used as the key to the reveal-URL.
// This hash value along with the reserve's public key
// will also be used for recoup operations, if needed.
coin_evs: CoinEnvelope[];
@@ -1893,7 +1891,7 @@ Withdraw
interface AgeWithdrawResponse {
// index of the commitments that the client doesn't
// have to disclose in the subsequent call to
- // ``/reveal-withdraw/$ACH``.
+ // ``/reveal-withdraw``.
noreveal_index: Integer;
// Signature of `TALER_WithdrawConfirmationPS` whereby
@@ -2085,14 +2083,11 @@ These endpoints are called by the client
and prove that the age restriction was set correctly.
-.. http:post:: /reveal-melt/$RCH
+.. http:post:: /reveal-melt
Reveal previously committed values to the exchange, except for the values
corresponding to the ``noreveal_index`` returned by the ``/melt`` step.
- ``$RCH`` is the hash over the melt commitment from the ``/melt/`` step,
- i.e. the SHA256 value of the `TALER_MeltCommitmentPS` from that prior request.
-
The base URL for ``/reveal-melt``-request may differ from the main base URL of
the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
coin during melt operations. The exchange MUST return a
@@ -2105,7 +2100,7 @@ These endpoints are called by the client
The coin's' secret material matched the commitment and the original request was well-formed.
The response body is a `RevealResponse`.
:http:statuscode:`404 Not found`:
- The provided commitment $RCH is unknown.
+ The provided commitment is unknown.
:http:statuscode:`409 Conflict`:
There is a problem between the original commitment and the revealed secret data.
The returned information is proof of the mismatch,
@@ -2122,6 +2117,11 @@ These endpoints are called by the client
.. ts:def:: RevealMeltRequest
interface RevealMeltRequest {
+ // The hash over the melt commitment from the ``/melt/`` step,
+ // i.e. the SHA512 value of the `TALER_MeltCommitmentPS`
+ // from that prior request.
+ melt_commitment_h: string;
+
// Array of ``(kappa - 1)`` disclosed batch secrets,
// from which for each of the n coins in a batch
// their coin master secret is derived,
@@ -2176,15 +2176,11 @@ These endpoints are called by the client
}
-.. http:post:: /reveal-withdraw/$ACH
+.. http:post:: /reveal-withdraw
Reveal previously committed values to the exchange, except for the values
corresponding to the ``noreveal_index`` returned by the ``/withdraw`` step.
- ``$ACH`` is the running hash over all commitments from the former withdraw request.
- Note that the value for $ACH is calculated independently by both sides
- and has never appeared *explicitly* in the protocol before.
-
The base URL for ``/reveal-withdraw``-request may differ from the main base URL of
the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
coin during melt operations. The exchange MUST return a
@@ -2213,7 +2209,7 @@ These endpoints are called by the client
Error code:
``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``.
- The computation of the hash of the commitment with provided input does
- result in the value $ACH.
+ result in the value of field ``withdraw_commitment_h``.
Error code:
``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH``
@@ -2225,19 +2221,21 @@ These endpoints are called by the client
.. ts:def:: RevealWithdrawRequest
interface RevealWithdrawRequest {
+ // The hash of the withdraw commitment (`TALER_WithdrawCommitmentHashP`)
+ // from the previous call to /withdraw.
+ withdraw_commitment_h: string;
+
// Array of ``(kappa - 1)`` disclosed batch secrets,
// from which for each of the n coins in a batch
// their coin master secret is derived,
// from which in turn their private key,
// blinding, nonce (for Clause-Schnorr) and
// age-restriction is calculated.
- //
- // TODO: add details about the derivation.
- disclosed_batch_seeds: AgeRestrictedBatchSeed[];
+ disclosed_batch_seeds: AgeRestrictedPlanchetSeed[];
}
- .. ts:def:: AgeRestrictedBatchSeed
+ .. ts:def:: AgeRestrictedPlanchetSeed
// The master seed material from which for n coins in a batch,
// each the coins' private key ``coin_priv``, blinding ``beta``
@@ -2260,7 +2258,7 @@ These endpoints are called by the client
// and calculate the corresponding Edx25519PublicKey as
// q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG])
//
- type AgeRestrictedBatchSeed = string;
+ type AgeRestrictedPlanchetSeed = string;
.. ts:def:: PublishedAgeRestrictionBaseKey
