taler-docs

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

commit f064277e00790ca3309e843d6d7e2c23c3d96aec
parent 08da115d4cc0d88ee480fc41562d78df91955f98
Author: Özgür Kesim <oec@codeblau.de>
Date:   Sat, 21 Nov 2026 17:24:47 +0100

[exchange] CS envelopes: cs_nonce must be derived from blinding_seed

The documentation named the cs_nonce of a Clause-Schnorr envelope but did
not say which value it must have.  It must be the nonce derived from the
request's blinding_seed for the coin's index (HKDF with the index as
salt, "withdraw-n" or "refresh-n" as ikm and blinding_seed as info), and
the exchange refuses an envelope with another nonce (400,
TALER_EC_GENERIC_PARAMETER_MALFORMED).  The exchange signs under the
nonce of the envelope; without the check the client chooses it, and two
different blinded challenges signed under one nonce reveal the
denomination's private key, whatever the uniqueness of blinding_seed.

Documented at CSCoinEnvelope, at the blinding_seed of the withdraw and
melt requests and at their 400 responses.  Part of protocol v46, which is not
published yet.

Issue: https://bugs.gnunet.org/view?id=12237

Diffstat:
Mcore/api-common.rst | 13++++++++++++-
Mcore/api-exchange.rst | 8+++++++-
Mcore/exchange/post-melt.rst | 5+++++
Mcore/exchange/post-withdraw.rst | 3+++
4 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst @@ -778,7 +778,18 @@ Blinded coin // See https://taler.net/papers/cs-thesis.pdf for details. interface CSCoinEnvelope { cipher: "CS" | "CS+age_restricted"; - cs_nonce: string; // Crockford `Base32` encoded + + // Session nonce, Crockford `Base32` encoded. In a withdraw or melt + // request it MUST be the nonce derived from the request's + // ``blinding_seed`` for the coin's index i in ``denoms_h``: + // HKDF (salt = i as 32-bit unsigned integer in network byte order, + // ikm = "withdraw-n" for a withdrawal or "refresh-n" for a melt, + // info = ``blinding_seed``), the same for every batch of the coin. + // The exchange refuses an envelope with another nonce (400): the + // exchange signs under the nonce of the envelope, and two different + // blinded challenges signed under one nonce reveal the denomination's + // private key. + cs_nonce: string; cs_blinded_c0: string; // Crockford `Base32` encoded cs_blinded_c1: string; // Crockford `Base32` encoded } diff --git a/core/api-exchange.rst b/core/api-exchange.rst @@ -87,7 +87,11 @@ The currently implemented protocol version is **v46**. include ``noreveal_index`` and the ``transfer_pubs`` of the batch at ``noreveal_index``; :http:post:`/melt </melt>` of a zombie coin returns the - `CoinDenominationConflictError` proof like all other paths + `CoinDenominationConflictError` proof like all other paths; + :http:post:`/withdraw </withdraw>` and :http:post:`/melt </melt>` + refuse a Clause-Schnorr envelope whose ``cs_nonce`` is not the + nonce derived from the request's ``blinding_seed`` (see + `CSCoinEnvelope`) **Upcoming versions:** @@ -240,6 +244,8 @@ exchange. // MUST NOT have been used in any prior withdraw request. // MUST be present if one of the fresh coin's // denomination is of type Clause-Schnorr. + // The ``cs_nonce`` of every Clause-Schnorr envelope in ``coin_evs`` + // MUST be derived from it, see `CSCoinEnvelope`. blinding_seed?: BlindingMasterSeed; // Array of blinded coin envelopes of type `CoinEnvelope`. diff --git a/core/exchange/post-melt.rst b/core/exchange/post-melt.rst @@ -25,6 +25,9 @@ ``TALER_EC_EXCHANGE_MELT_FEES_EXCEED_CONTRIBUTION``, ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``, or ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_COST_CALCULATION_OVERFLOW``. + A Clause-Schnorr envelope whose ``cs_nonce`` is not the one derived + from ``blinding_seed`` is refused with + ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` (since **v46**). :http:statuscode:`403 Forbidden`: One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. @@ -148,6 +151,8 @@ // Must not have been used in any prior melt request. // Must be present if one of the fresh coin's // denominations is of type Clause-Schnorr. + // The ``cs_nonce`` of every Clause-Schnorr envelope in ``coin_evs`` + // must be derived from it, see `CSCoinEnvelope`. blinding_seed?: BlindingMasterSeed; // Array of ``n`` new hash codes of denomination public keys diff --git a/core/exchange/post-withdraw.rst b/core/exchange/post-withdraw.rst @@ -33,6 +33,9 @@ ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``, ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW``, or ``TALER_EC_EXCHANGE_WITHDRAW_IDEMPOTENT_PLANCHET``. + A Clause-Schnorr envelope whose ``cs_nonce`` is not the one derived + from ``blinding_seed`` is refused with + ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` (since **v46**). :http:statuscode:`403 Forbidden`: A signature is invalid. This is usually the reserve signature. This response comes with a standard `ErrorDetail` response with