From fdee6830e6470ff4413d5698290146fa7ba5d5c2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 12 Jul 2020 18:45:28 +0200 Subject: update API endpoint documentation --- doc/system/taler/design.tex | 26 +++++++++++++------------- doc/system/taler/implementation.tex | 19 ++++++++++++------- 2 files changed, 25 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/system/taler/design.tex b/doc/system/taler/design.tex index 8ee3ff3c9..36d167742 100644 --- a/doc/system/taler/design.tex +++ b/doc/system/taler/design.tex @@ -140,7 +140,7 @@ creates a new reserve, but making another wire transfer with the same reserve public key simply adds funds to the existing reserve. Even after all funds have been withdrawn from a reserve, customers should keep the reserve key pair until all coins from the corresponding reserve have been spent, as in the event -of a denomination key revocation (see Section \ref{sec:revocation-payback}) the +of a denomination key revocation (see Section \ref{sec:revocation-recoup}) the customer needs this key to recover coins of revoked denominations. The exchange automatically transfers back to the customer's bank account any @@ -206,7 +206,7 @@ once more coins are redeemed than the total that was signed into existence using that denomination key. Should such an incident occur, the exchange can allow authentic customers to redeem their unspent coins that were signed with the compromised private key, while refusing further deposits involving coins signed by the -compromised denomination key (see Section~\ref{sec:revocation-payback}). As a result, the +compromised denomination key (see Section~\ref{sec:revocation-recoup}). As a result, the financial damage of losing a private signing key is limited to at most the amount originally signed with that key, and denomination key rotation can be used to bound that risk. @@ -428,7 +428,7 @@ discuss different ways that the exchange can be compromised, how to reduce the likelihood of such a compromise, and how to detect and react to such an event if it happens. -\subsubsection{Compromise of Denomination Keys and Revocation}\label{sec:revocation-payback} +\subsubsection{Compromise of Denomination Keys and Revocation}\label{sec:revocation-recoup} When a denomination key pair is compromised, an attacker can ``print money'' by using it to sign coins of that denomination. An exchange (or its auditor) can detect this when the number of deposits for a certain denomination exceed the @@ -437,14 +437,14 @@ number of withdrawals for that same denomination. We allow the exchange to revoke denomination keys, and wallets periodically check for such revocations. We call a coin of a revoked denomination a revoked coin. If a denomination key has been revoked, the wallets use the -\emph{payback} protocol to recover funds from coins of revoked denominations. +\emph{recoup} protocol to recover funds from coins of revoked denominations. Once a denomination is revoked, new coins of this denomination can't be withdrawn or used as the target denomination for a refresh operation. A revoked coin cannot be spent, and can only be refreshed if its public key was recorded in the exchange's database (as spending/refresh operations) before it was revoked. -The following cases are possible for payback: +The following cases are possible for recoup: \begin{enumerate} \item The revoked coin has never been seen by the exchange before, but the customer can prove via a withdraw protocol transcript and blinding factor @@ -472,12 +472,12 @@ legitimate users $n$ times. As soon as the exchange sees more than $n$ pairwise different $D$-coins, it must immediately revoke $D$. An attacker can thus at most gain $nv$ by either refreshing into other non-revoked denominations or spending the forged $D$-coins. -The legitimate users can then request a payback for their coins, resulting in +The legitimate users can then request a recoup for their coins, resulting in a total financial damage of at most $2nv$. -With one rare exception, the payback protocol does not negatively impact the +With one rare exception, the recoup protocol does not negatively impact the anonymity of customers. We show this by looking at the three different cases -for payback on a revoked coin. Specifically, in case (1), the coin obtained +for recoup on a revoked coin. Specifically, in case (1), the coin obtained from the credited reserve is blindly signed, in case (2) the refresh protocol guarantees unlinkability of the non-revoked change, and in case (3) the revoked coin $C_R$ is assumed to be fresh. If $C_R$ from case (3) has been seen by a @@ -487,7 +487,7 @@ aborted transaction coincides with revoked denomination, which should be rare in practice. Unlike most other operations, the -payback protocol does not incur any transaction fees. The primary use of the +recoup protocol does not incur any transaction fees. The primary use of the protocol is to limit the financial loss in cases where an audit reveals that the exchange's private keys were compromised, and to automatically pay back balances held in a customers' wallet if an exchange ever goes out of business. @@ -622,7 +622,7 @@ The following modifications are made: This change is necessary to preserve anonymity in face of the second modification, but increases storage requirements and latency. - \item The payback protocol is changed so that a coin obtained + \item The recoup protocol is changed so that a coin obtained via refreshing must be recovered differently when revoked: to recover a revoked coin obtained via refreshing, the customer needs to show the transcripts for the chain of all refresh operations and the initial withdrawal operation @@ -633,9 +633,9 @@ The following modifications are made: After an attacker has been paid ransom, the exchange simply revokes all currently offered denominations and registers a new set of denomination with the auditor. Reserves used to pay the attacker are marked as blocked in the exchange's -database. Normal users can use the payback protocol to obtain back the money +database. Normal users can use the recoup protocol to obtain back the money they've previously had in revoked denominations. The attacker can try to -recover funds via the (now modified) payback protocol, but this attempt will +recover funds via the (now modified) recoup protocol, but this attempt will not be successful, as the initial reserve is blocked. The criminal could also try to spend the e-cash anonymously before it is revoked, but this is likely difficult for large amounts, and furthermore due to income transparency all @@ -643,7 +643,7 @@ transactions made between the payment of the ransom and the revocation can be traced back to merchants that might be complicit in laundering the ransom payment. -Honest customers can always use the payback protocol to transfer the funds to +Honest customers can always use the recoup protocol to transfer the funds to the initial reserve. Due to modification (1), unlinkability of transactions is not affected, as only coins that were purely used for refreshing can now be correlated. diff --git a/doc/system/taler/implementation.tex b/doc/system/taler/implementation.tex index 4aa1679fc..e9fdf7991 100644 --- a/doc/system/taler/implementation.tex +++ b/doc/system/taler/implementation.tex @@ -894,18 +894,23 @@ The following APIs are offered by the exchange: supported bank accounts, revoked keys and other general information needed to use the exchange's services via the \texttt{/keys} and \texttt{/wire} APIs. + \item[Obtaining entropy] As we cannot be sure that all client-devices have + an adequate random number generator, the exchange offers the \texttt{/seed} + endpoint to download some high-entropy value. Clients should mix this + seed with their own, locally-generated entropy into an entropy pool. \item[Reserve status and withdrawal] After having wired money to the exchange, - the status of the reserve can be checked via the \texttt{/reserve/status} API. Since + the status of the reserve can be checked via the \texttt{/reserve/\$RESERVE\_PUB/status} API. Since the wire transfer usually takes some time to arrive at the exchange, wallets should periodically - poll this API, and initiate a withdrawal with \texttt{/reserve/withdraw} once the exchange received the funds. + poll this API, and initiate a withdrawal with \texttt{/reserve/\$RESERVE\_PUB/withdraw} once the exchange received the funds. \item[Deposits and tracking] Merchants transmit deposit permissions they have received from customers - to the exchange via the \texttt{/deposit} API. Since multiple deposits are aggregated into one wire transfer, - the merchant additionally can use the exchange's \texttt{/track/transfer} API that returns the list of deposits for an - identifier included in the wire transfer to the merchant, as well as the \texttt{/track/transaction} API to look up + to the exchange via the \texttt{/coins/\$COIN\_PUB/deposit} API. Since multiple deposits are aggregated into one wire transfer, + the merchant additionally can use the exchange's \texttt{/transfers/\$WTID} API that returns the list of deposits for a wire transfer + identifier (WTID) included in the wire transfer to the merchant, as well as the \texttt{/deposits/\$H\_WIRE/\$MERCHANT\_PUB/\$H\_CONTRACT\_TERMS/\$COIN\_PUB} API to look up which wire transfer included the payment for a given deposit. - \item[Refunds] The refund API (\texttt{/refund}) can ``undo'' a deposit if the merchant gave their signature, and the aggregation deadline + \item[Refresh] Refreshing consists of two stages. First, using \texttt{/coins/\$COIN\_PUB/melt} an old, possibly dirty coin is melted and thus devaluted. The committment made by the wallet during the melt and the resulting $\gamma$-challenge from the exchange are associated with a {\em refresh session}. Then, using \texttt{/refreshes/$RCH/reveal} the wallet can answer the challenge and obtain fresh coins as change. Finally, \texttt{/coins/\$COIN\_PUB/link} provides the link deterrent against refresh abuse. + \item[Refunds] The refund API (\texttt{/coins/\$COIN\_PUB/refund}) can ``undo'' a deposit if the merchant gave their signature, and the aggregation deadline for the payment has not occurred yet. - \item[Emergency payback] The emergency payback API (\texttt{/payback}) allows customers to be compensated + \item[Recoup] The recoup API (\texttt{/coins/\$COIN\_PUB/recoup}) allows customers to be compensated for coins whose denomination key has been revoked. Customers must send either a full withdrawal transcript that includes their private blinding factor, or a refresh transcript (of a refresh that had the revoked denominations as one of the targets) that includes blinding factors. In the former case, the reserve is credited, in the latter case, the source coin of the -- cgit v1.2.3