Merge branch 'master' of git+ssh://taler.net/var/git/api

6 files changed, 135 insertions, 175 deletions

diff --git a/api-exchange.rst b/api-exchange.rst
index 07d681b0..86e33714 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
@@ -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
@@ -514,7 +517,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;
@@ -1026,7 +1029,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:**
 
@@ -1263,8 +1266,22 @@ Administrative API: Bank transactions
       // When was the transaction executed
       execution_date: Timestamp;
 
-      // Wire details
-      wire: any;
+      // 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.
+      //
+      // 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:**
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
diff --git a/exchange-db.png b/exchange-db.png
new file mode 100644
index 00000000..de4c6570
--- /dev/null
+++ b/exchange-db.png
diff --git a/glossary.rst b/glossary.rst
index 6f1edc80..023a0caa 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 <http://www.gnu.org/licenses/>
 
   @author Florian Dold
+  @author Christian Grothoff
 
 ==============
 Taler Glossary
@@ -18,12 +22,105 @@ Taler Glossary
 
 .. glossary::
 
-  wallet
-     EXPLAIN
+.. _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
+
+  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:
+  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
-     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
+.. _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
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
 
 
 ------------------
diff --git a/impl-merchant.rst b/impl-merchant.rst
index 330b6d1a..7ae4e3d1 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.
@@ -131,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 <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:**