From e2021873b0aa8ec4a756a1306213d885b15f4b55 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 17 May 2016 10:03:06 +0200 Subject: typo --- api-exchange.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-exchange.rst b/api-exchange.rst index 33b77305..f78a8cb3 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -1026,7 +1026,7 @@ typically also view the balance.) Provide the wire transfer identifier associated with an (existing) deposit operation. - **Request:** The request body most be a `WtidRequest`_ JSON object. + **Request:** The request body must be a `WtidRequest`_ JSON object. **Response:** -- cgit v1.2.3 From 6de85db6421e3a3176c9af63420f39fd477dcbd9 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 20 May 2016 10:17:05 +0200 Subject: more details on /admin/add/incoming --- api-exchange.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/api-exchange.rst b/api-exchange.rst index f78a8cb3..a6a913af 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -1261,7 +1261,10 @@ Administrative API: Bank transactions // When was the transaction executed execution_date: Timestamp; - // Wire details + // Client's wire details, so that the exchange knows from whom money comes from. + // We strees again that in order to create a reserve on any exchange, an equivalent + // amount of money must be wire transferred from the client's to the exchange's + // bank account wire: any; } -- cgit v1.2.3 From ce6b80c60bc49218f86bc52f4e83c9d13831ac10 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 20 May 2016 10:19:56 +0200 Subject: typo --- api-exchange.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-exchange.rst b/api-exchange.rst index a6a913af..b7b36765 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -302,7 +302,7 @@ exchange. .. note:: The client currently does not have to demonstrate knowledge of the private key of the reserve to make this request, which makes the reserve's public - key privliged information known only to the client, their bank, and the + key privileged information known only to the client, their bank, and the exchange. In future, we might wish to revisit this decision to improve security, such as by having the client EdDSA-sign an ECDHE key to be used to derive a symmetric key to encrypt the response. This would be useful if -- cgit v1.2.3 From 13b2205836d1d91e58d973648b2a47870ad7f76d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 20 May 2016 14:29:28 +0200 Subject: clarify that wire details must be unique --- api-exchange.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/api-exchange.rst b/api-exchange.rst index b7b36765..28acac75 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -1262,9 +1262,15 @@ Administrative API: Bank transactions execution_date: Timestamp; // Client's wire details, so that the exchange knows from whom money comes from. - // We strees again that in order to create a reserve on any exchange, an equivalent + // In order to create a reserve on any exchange, an equivalent // amount of money must be wire transferred from the client's to the exchange's - // bank account + // bank account. + // The wire details given here should include some unique identifier + // for each transaction. The exchange will check that the details + // given are unique, and if the wire details are identical to previous + // wire details will treat the request as a duplicate and not actually + // do any update. This is true even if the amount or execution date + // differs. wire: any; } -- cgit v1.2.3 From b981558c685503b50e26b295fa51dc43b917dd53 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 26 May 2016 15:06:22 +0200 Subject: remove dead /hash-contract API logic --- impl-merchant.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/impl-merchant.rst b/impl-merchant.rst index 330b6d1a..38f354a4 100644 --- a/impl-merchant.rst +++ b/impl-merchant.rst @@ -65,20 +65,6 @@ The Merchant Backend HTTP API The following API are made available by the merchant's `backend` to the merchant's `frontend`. -.. http:post:: /hash-contract - - Ask the backend to compute the hash of the `contract` given in the POST's body (the full contract - should be the value of a JSON field named `contract`). This feature allows frontends to verify - that names of resources which are going to be sold are actually `in` the paid cotnract. Without - this feature, a malicious wallet can request resource A and pay for resource B without the frontend - being aware of that. - - **Response** - - :status 200 OK: - hash succesfully computed. The returned value is a JSON having one field called `hash` containing - the hashed contract - .. http:post:: /contract Ask the backend to add some missing (mostly related to cryptography) information to the contract. -- cgit v1.2.3 From e3fd0565cef4fb9c542d824e0f39d7d0bb6f5dcf Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 26 May 2016 15:23:32 +0200 Subject: change edate to wire_transfer_deadline/delay (#4521) --- api-exchange.rst | 2 +- impl-merchant.rst | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/api-exchange.rst b/api-exchange.rst index 28acac75..d9dc14aa 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -514,7 +514,7 @@ denomination. // indicative time by which the exchange undertakes to transfer the funds to // the merchant, in case of successful payment. - edate: Timestamp; + pay_deadline: Timestamp; // 64-bit transaction id for the transaction between merchant and customer transaction_id: number; diff --git a/impl-merchant.rst b/impl-merchant.rst index 38f354a4..7ae4e3d1 100644 --- a/impl-merchant.rst +++ b/impl-merchant.rst @@ -117,9 +117,11 @@ The following API are made available by the merchant's `backend` to the merchant **Request:** The `frontend` passes the :ref:`deposit permission ` - received from the wallet, and optionally adding a field named `edate`, + received from the wallet, and optionally adding a field named `pay_deadline`, indicating a deadline by which he would expect to receive the bank transfer - for this deal. Note that the `edate` must be after the `refund_deadline`. + for this deal. Note that the `pay_deadline` must be after the `refund_deadline`. + The backend calculates the `pay_deadline` by adding the `wire_transfer_delay` + value found in the configuration to the current time. **Response:** -- cgit v1.2.3 From a42d85021d88d36a1bcea6ecb596ff392656836d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 26 May 2016 16:39:45 +0200 Subject: fix #4533 for exchange (breaks interaction with bank for /admin/add/incoming) --- api-exchange.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/api-exchange.rst b/api-exchange.rst index d9dc14aa..80ad0a76 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -343,8 +343,11 @@ exchange. // The amount that was withdrawn or deposited. amount: Amount; - // Wiring details, only present if type is "DEPOSIT". - wire?: any; + // Sender account details, only present if type is "DEPOSIT". + sender_account_details?: any; + + // Transfer details uniquely identifying the transfer, only present if type is "DEPOSIT". + transfer_details?: any; // binary encoding of the transaction data as a `TALER_WithdrawRequestPS` // struct described in :ref:`Signatures`, only present if the `type` was @@ -1261,17 +1264,22 @@ Administrative API: Bank transactions // When was the transaction executed execution_date: Timestamp; - // Client's wire details, so that the exchange knows from whom money comes from. - // In order to create a reserve on any exchange, an equivalent - // amount of money must be wire transferred from the client's to the exchange's - // bank account. - // The wire details given here should include some unique identifier + // Sender's wire account details, so that the exchange knows from whom the + // money comes from (and can possibly refund it). The details + // given here must be in a wire format supported by the exchange. + sender_account_details: any; + + // The wire details given here should include an unique identifier // for each transaction. The exchange will check that the details // given are unique, and if the wire details are identical to previous // wire details will treat the request as a duplicate and not actually // do any update. This is true even if the amount or execution date // differs. - wire: any; + // + // Note that the exchange does not interpret these details in any + // way, other than for "being unique". They are stored for diagnostics + // and auditing. + transfer_details: any; } **Response:** -- cgit v1.2.3 From 549e9260d76659194ab554435e46cd5b74488977 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 27 May 2016 15:45:34 +0200 Subject: add DB schema, fixing #4067 --- exchange-db.png | Bin 0 -> 202763 bytes impl-exchange.rst | 149 +----------------------------------------------------- 2 files changed, 2 insertions(+), 147 deletions(-) create mode 100644 exchange-db.png diff --git a/exchange-db.png b/exchange-db.png new file mode 100644 index 00000000..de4c6570 Binary files /dev/null and b/exchange-db.png differ diff --git a/impl-exchange.rst b/impl-exchange.rst index 680519cc..0460e106 100644 --- a/impl-exchange.rst +++ b/impl-exchange.rst @@ -33,7 +33,7 @@ SEPA accounts The command line tool `taler-exchange-sepa` is used to create a file with the JSON response to /wire/sepa requests using the exchange's offline -master key. This file needs to be created and added to the configuration under SEPA_RESPONSE_FILE in section [exchange-wire-sepa] when the +master key. This file needs to be created and added to the configuration under SEPA_RESPONSE_FILE in section [exchange-wire-sepa] when the `wireformat` option in the configuration file allows SEPA transactions. @@ -77,152 +77,7 @@ The command line tool `taler-exchange-reservemod` allows create and add money to Database Scheme ------------------- - .. note:: - - This documentation is outdated (no bug number yet either). - - -.. sourcecode:: postgres - - CREATE TABLE purses ( - -- The customer's withdraw public key for the purse. - withdraw_pub BYTEA PRIMARY KEY, - - -- Purse balance (value part). - balance_value INT4 NOT NULL, - - -- Purse balance (fractional part). - balance_fraction INT4 NOT NULL, - - -- Purse balance (fractional). - balance_currency VARCHAR(4), - - -- Expiration time stamp for the purse. - expiration INT8, - - -- The blinding key (public part) for the purse, can be NULL - -- if funds are insufficient or the exchange has not - -- generated it yet. - blinding_pub BYTEA, - - -- The blinding key (private part). - blinding_priv BYTEA, - - -- Key that was used to create the last signature on the - -- purse status - status_sign_pub BYTEA, - - -- Cached status signature - status_sig BYTEA - ); - - -.. sourcecode:: postgres - - CREATE TABLE collectable_blindcoins ( - -- The public part of the blinding key. - -- Note that this is not a foreign key, - -- as the blinding key is removed from the purse - -- table once a coin has been requested with it. - -- Furthermore, the private part is not required - -- anymore. - blind_pub bytea PRIMARY KEY, - - -- The coin blank provided by the customer. - blind_blank_coin BYTEA, - - -- Signature over the exchangeing request by the customer. - customer_sig BYTEA, - - -- The signed blind blank coin. - blind_signed_coin BYTEA, - - -- The denomination public key used to sign the - -- blind signed coin. - denom_pub BYTEA, - - -- The purse that requested the exchangeing of this - -- coin. - withdraw_pub BYTEA REFERENCES purses(withdraw_pub) - ); - - -The table `coins` stores information about coins known to the exchange. - -.. sourcecode:: postgres - - CREATE TABLE coins ( - denom_pub BYTEA NOT NULL, - denom_sig BYTEA NOT NULL, - coin_pub BYTEA NOT NULL, - - -- melting session, or NULL if not melted - melt_session BYTEA, - - -- remaining value of the coin - balance_currency int4, - balance_value int4, - balance_fraction int4, - - -- lock id, not NULL if not locked - lock int - ); - -The following tables are used for refreshing. - -.. sourcecode:: postgres - - CREATE TABLE refresh_sessions ( - session_pub BYTEA, - order_sig BYTEA, - index_reveal INT2, - ); - - CREATE TABLE refresh_melt ( - session_pub BYTEA REFERENCES refresh_sessions (session_pub), - session_sig BYTEA, - denom_pub BYTEA, - denom_sig BYTEA, - coin_pub BYTEA, - coin_sig BYTEA, - ); - - -- create links to old coins - CREATE TABLE refresh_link_commits ( - session_pub BYTEA, - session_sig BYTEA, - coin_pub BYTEA, - transfer_pub BYTEA, - link_secret_enc BYTEA, - link_secret_hash BYTEA, - idx INTEGER - ); - - CREATE TABLE refresh_order ( - -- EdDSA public key of the melting session - session_pub BYTEA REFERENCES refresh_sessions (session_pub), - -- denomination key for the newly ordered coin - denom_pub BYTEA, - -- signature from session key over coin order - session_sig BYTEA, - ); - - CREATE TABLE refresh_coin_commits ( - session_pub BYTEA, - idx INTEGER, - coin_link_enc BYTEA, - -- The blinding key (public part) for the purse, can be NULL - -- if funds are insufficient or the exchange has not - -- generated it yet. - blinding_pub BYTEA, - - -- The blinding key (private part). - blinding_priv BYTEA, - -- The coin blank provided by the customer. - blind_blank_coin BYTEA, - -- encrypted stuff - coin_link_enc BYTEA, - ); +.. image:: exchange-db.png ------------------ -- cgit v1.2.3 From 055e6e9c7872ccd03cc456d7ff2a41af37ba6ddd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 27 May 2016 15:47:17 +0200 Subject: script for regenerating the PNG in the future --- exchange-db-generate.sh | 3 +++ 1 file changed, 3 insertions(+) create mode 100755 exchange-db-generate.sh diff --git a/exchange-db-generate.sh b/exchange-db-generate.sh new file mode 100755 index 00000000..b296e0c9 --- /dev/null +++ b/exchange-db-generate.sh @@ -0,0 +1,3 @@ +#!/bin/sh +taler-exchange-dbinit -r +java -jar schemaSpy_5.0.0.jar -t pgsql -db taler -o taler -host localhost -dp /usr/share/java/postgresql-jdbc3-9.2.jar -u grothoff -p test -s public -hq -- cgit v1.2.3 From 1a71b7f45019c8d4c07dd87d08dc871c00b2edd6 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 31 May 2016 15:52:26 +0200 Subject: glossary --- glossary.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 5 deletions(-) diff --git a/glossary.rst b/glossary.rst index 6f1edc80..cf24d051 100644 --- a/glossary.rst +++ b/glossary.rst @@ -1,16 +1,20 @@ .. This file is part of GNU TALER. Copyright (C) 2014, 2015, 2016 INRIA + TALER is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2.1, or (at your option) any later version. + TALER is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + You should have received a copy of the GNU Lesser General Public License along with TALER; see the file COPYING. If not, see @author Florian Dold + @author Christian Grothoff ============== Taler Glossary @@ -18,12 +22,83 @@ Taler Glossary .. glossary:: - wallet - EXPLAIN + auditor + trusted third party that verifies that the exchange is operating correctly + + bank + traditional financial service provider who offers wire transfers between accounts + + coin + coins are individual token representing a certain amount of value, also known as the denomination of the coin + + contract + specification of the details of a transaction, specifies the payment obligations for the customer (i.e. the amount), the deliverables of the merchant and other related information, such as deadlines or locations + + denomination + unit of currency, specifies both the currency and the face value of a coin + + denomination key + RSA key used by the exchange to certify that a given coin is valid and of a particular denomination + + deposit + operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using a wire transfer + + dirty coin + a coin is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin's owner if the coin is not refreshed first + + extension + implementation of a wallet for browsers + + fresh coin + a coin is fresh if its public key is only known to the customer + + master key + offline key used by the exchange to certify denomination keys and message signing keys + + message signing key + key used by the exchange to sign online messages, other than coins + + owner + a coin is owned by the entity that knows the private key of the coin + + proof + message that cryptographically demonstrates that a particular claim is correct reserve - EXPLAIN + funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange's bank account to cover obligations from coins in circulation - bank - EXPLAIN + refreshing + operation by which a dirty coin is converted into one or more fresh coins + + refund + operation by which a merchant steps back from the right to funds that he obtained from a deposit operation, giving the right to the funds back to the customer + + sharing + users can share ownership of a coin by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. + + signing key + see message signing key. + + spending + operation by which a customer gives a merchant the right to deposit coins in return for merchandise + + transfer + method of sending funds between accounts in the banking system + + transaction + method by which ownership is exclusively transferred from one entity to another + + transaction id + unique number by which a merchant identifies a transaction + + wallet + software running on a customer's computer; withdraws, stores and spends coins + + wire transfer + see transfer + + wire transfer identifier + subject of a wire transfer; usually a random string to uniquely identify the transfer + withdrawal + operation by which a wallet can convert funds from a reserve to fresh coins -- cgit v1.2.3 From 272c03472a08ea30c788d3250a9df22ae33b09db Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 31 May 2016 15:55:45 +0200 Subject: glossary --- glossary.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/glossary.rst b/glossary.rst index cf24d051..023a0caa 100644 --- a/glossary.rst +++ b/glossary.rst @@ -22,33 +22,42 @@ Taler Glossary .. glossary:: +.. _auditor: auditor trusted third party that verifies that the exchange is operating correctly +.. _bank: bank traditional financial service provider who offers wire transfers between accounts +.. _coin: coin coins are individual token representing a certain amount of value, also known as the denomination of the coin +.. _contract: contract specification of the details of a transaction, specifies the payment obligations for the customer (i.e. the amount), the deliverables of the merchant and other related information, such as deadlines or locations +.. _denomination: denomination unit of currency, specifies both the currency and the face value of a coin denomination key RSA key used by the exchange to certify that a given coin is valid and of a particular denomination +.. _deposit: deposit operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using a wire transfer +.. _dirty: dirty coin a coin is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin's owner if the coin is not refreshed first +.. _extension: extension implementation of a wallet for browsers +.. _fresh: fresh coin a coin is fresh if its public key is only known to the customer @@ -58,47 +67,60 @@ Taler Glossary message signing key key used by the exchange to sign online messages, other than coins +.. _owner: owner a coin is owned by the entity that knows the private key of the coin +.. _proof: proof message that cryptographically demonstrates that a particular claim is correct +.. _reserve: reserve funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange's bank account to cover obligations from coins in circulation +.. _refresh: refreshing operation by which a dirty coin is converted into one or more fresh coins +.. _refund: refund operation by which a merchant steps back from the right to funds that he obtained from a deposit operation, giving the right to the funds back to the customer +.. _sharing: sharing users can share ownership of a coin by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. signing key see message signing key. +.. _spending: spending operation by which a customer gives a merchant the right to deposit coins in return for merchandise +.. _transfer: transfer method of sending funds between accounts in the banking system +.. _transaction: transaction method by which ownership is exclusively transferred from one entity to another transaction id unique number by which a merchant identifies a transaction +.. _wallet: wallet software running on a customer's computer; withdraws, stores and spends coins +.. _wire: wire transfer see transfer +.. _wtid: wire transfer identifier subject of a wire transfer; usually a random string to uniquely identify the transfer +.. _withdrawal: withdrawal operation by which a wallet can convert funds from a reserve to fresh coins -- cgit v1.2.3