From ea9af7ad5fa81477c655d1e0a7a890a5cf224b6e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 18 Feb 2022 18:46:02 +0100 Subject: -update documentation --- core/api-exchange.rst | 127 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 29 deletions(-) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 955121af..ac8c44b2 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2021 Taler Systems SA + Copyright (C) 2014-2022 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -303,7 +303,8 @@ possibly by using HTTPS. // 32-bit age mask. age_mask: Integer; - cs_public_key: FIXME; + // Public key of the denomination. + cs_public_key: Cs25519Point; } @@ -1409,7 +1410,7 @@ exchange. } -.. http:post:: /csr +.. http:post:: /csr-withdraw Obtain exchange-side input values in preparation for a withdraw step for certain denomination cipher types, @@ -1438,30 +1439,21 @@ exchange. interface WithdrawPrepareRequest { - nks: WithdrawPrepareDenomNonce[]; - - } - - .. ts:def:: WithdrawPrepareDenomNonce - - interface WithdrawPrepareDenomNonce { - - // Random client-side nonce - nonce: FIXME; + // Nonce to be used by the exchange to derive + // its private inputs from. Must not have ever + // been used before. + nonce: CSNonce; // Hash of the public key of the denomination the // request relates to. denom_pub_hash: Hash; - } + } .. ts:def:: WithdrawPrepareResponse - interface WithdrawPrepareResponse { - // Responses for each request, in the same - // order that was used in the request. - ewvs: ExchangeWithdrawValue[]; - } + type WithdrawPrepareResponse + | ExchangeWithdrawValue; .. ts:def:: ExchangeWithdrawValue @@ -1487,9 +1479,6 @@ exchange. r_pub_1: CsRPublic; } - - - .. http:post:: /reserves/$RESERVE_PUB/withdraw Withdraw a coin of the specified denomination. Note that the client should @@ -1628,9 +1617,13 @@ exchange. interface CSBlindedDenominationSignature { type: "CS"; - b: FIXME; + // Signer chosen bit value, 0 or 1, used + // in Clause Blind Schnorr to make the + // ROS problem harder. + b: Integer; - s: FIXME; + // Blinded scalar calculated from c_b. + s: Cs25519Scalar; } @@ -1842,9 +1835,11 @@ denomination. interface CSDenominationSignature { type: "CS"; - cs_signature_r: FIXME; + // R value component of the signature. + cs_signature_r: Cs25519Point; - cs_signature_s: FIXME: + // s value component of the signature. + cs_signature_s: Cs25519Scalar: } @@ -2202,6 +2197,73 @@ using the ``/refresh/link`` request. While ``/refresh/link`` must be implemente the exchange to achieve taxability, wallets do not really ever need that part of the API during normal operation. + +.. http:post:: /csr-melt + + Obtain exchange-side input values in preparation for a + melt step for certain denomination cipher types, + specifically at this point for Clause-Schnorr blind + signatures. + + **Request:** The request body must be a `MeltPrepareRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `MeltPrepareResponse`. Note that repeating exactly the same request + will again yield the same response (assuming none of the denomination is expired). + :http:statuscode:`404 Not found`: + A denomination key is not known to the exchange. + :http:statuscode:`410 Gone`: + A requested denomination key is not yet or no longer valid. + It either before the validity start, past the expiration or was revoked. The response is a + `DenominationExpiredMessage`. Clients must evaluate + the error code provided to understand which of the + cases this is and handle it accordingly. + + **Details:** + + .. ts:def:: MeltPrepareRequest + + interface WithdrawPrepareRequest { + + // Master seed for the Clause-schnorr R-value + // creation. + // Must not have been used in any prior request. + rms: RefreshMasterSeed; + + // Array of denominations and coin offsets for + // each of the fresh coins with a CS-cipher + // denomination. + nks: MeltPrepareDenomNonce[]; + + } + + .. ts:def:: MeltPrepareDenomNonce + + interface MeltPrepareDenomNonce { + + // Offset of this coin in the list of + // fresh coins. May not match the array offset + // as the fresh coins may include non-CS + // denominations as well. + coin_offset: Integer; + + // Hash of the public key of the denomination the + // request relates to. Must be a CS denomination type. + denom_pub_hash: Hash; + } + + + .. ts:def:: MeltPrepareResponse + + interface MeltPrepareResponse { + // Responses for each request, in the same + // order that was used in the request. + ewvs: ExchangeWithdrawValue[]; + } + + .. _refresh: .. http:post:: /coins/$COIN_PUB/melt @@ -2262,6 +2324,13 @@ the API during normal operation. // See also ``TALER_refresh_get_commitment()``. rc: TALER_RefreshCommitmentP; + // Master seed for the Clause-schnorr R-value + // creation. Must match the /csr-melt request. + // 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. + rms?: RefreshMasterSeed; + } For details about the HKDF used to derive the new coin private keys and @@ -2451,7 +2520,7 @@ the API during normal operation. coin_ev : CoinEnvelope; // Values contributed by the exchange during the - // withdraw operation (see /csr). + // withdraw operation (see /csr-melt). ewv: ExchangeWithdrawValue; // Offset of this coin in the refresh operation. @@ -2537,7 +2606,7 @@ in using this API. denom_sig: DenominationSignature; // Exchange-contributed values during the refresh - // operation (see /csr). + // operation (see /csr-withdraw). ewv: ExchangeWithdrawValue; // Signature of `TALER_RecoupRequestPS` created with @@ -2616,7 +2685,7 @@ in using this API. denom_sig: DenominationSignature; // Exchange-contributed values during the refresh - // operation (see /csr). + // operation (see /csr-melt). ewv: ExchangeWithdrawValue; // Signature of `TALER_RecoupRefreshRequestPS` created with -- cgit v1.2.3