taler/exchange
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update API endpoint documentation

Browse Source
This commit is contained in:
Christian Grothoff 2020-07-12 18:45:28 +02:00
parent 895e24872d
commit fdee6830e6
No known key found for this signature in database
GPG Key ID: 939E6BE1E29FC3CC
2 changed files with 25 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/system/taler/design.tex
View File

@ -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 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 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 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. customer needs this key to recover coins of revoked denominations.
The exchange automatically transfers back to the customer's bank account any 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 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 customers to redeem their unspent coins that were signed with the compromised
private key, while refusing further deposits involving coins signed by the 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 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 amount originally signed with that key, and denomination key rotation can be
used to bound that risk. 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 likelihood of such a compromise, and how to detect and react to such an event
if it happens. 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 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 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 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 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 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 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 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 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 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 in the exchange's database (as spending/refresh operations) before it was
revoked. revoked.
The following cases are possible for payback: The following cases are possible for recoup:
\begin{enumerate} \begin{enumerate}
\item The revoked coin has never been seen by the exchange before, but the \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 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 than $n$ pairwise different $D$-coins, it must immediately
revoke $D$. An attacker can thus at most gain $nv$ by either revoke $D$. An attacker can thus at most gain $nv$ by either
refreshing into other non-revoked denominations or spending the forged $D$-coins. 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$. 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 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 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 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 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. in practice.
Unlike most other operations, the 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 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 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. 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 This change is necessary to preserve anonymity in face of the second modification, but increases
storage requirements and latency. 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 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 obtained via refreshing, the customer needs to show the transcripts for the
chain of all refresh operations and the initial withdrawal operation 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 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. and registers a new set of denomination with the auditor.
Reserves used to pay the attacker are marked as blocked in the exchange's 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 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 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 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 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 traced back to merchants that might be complicit in laundering the ransom
payment. 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 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 not affected, as only coins that were purely used for refreshing can now be
correlated. correlated.

19
doc/system/taler/implementation.tex
View File

@ -894,18 +894,23 @@ The following APIs are offered by the exchange:
supported bank accounts, revoked keys and other general information needed supported bank accounts, revoked keys and other general information needed
to use the exchange's services via the \texttt{/keys} and \texttt{/wire} to use the exchange's services via the \texttt{/keys} and \texttt{/wire}
APIs. 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, \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 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 \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, 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{/track/transfer} API that returns the list of deposits for an the merchant additionally can use the exchange's \texttt{/transfers/\$WTID} API that returns the list of deposits for a wire transfer
identifier included in the wire transfer to the merchant, as well as the \texttt{/track/transaction} API to look up 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. 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. 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 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) 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 that includes blinding factors. In the former case, the reserve is credited, in the latter case, the source coin of the