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

7 files changed, 215 insertions, 146 deletions

diff --git a/api-common.rst b/api-common.rst
index f41b9a46..3bbc8722 100644
--- a/api-common.rst
+++ b/api-common.rst
@@ -157,12 +157,15 @@ Keys
 ^^^^
 
 .. _`tsref-type-EddsaPublicKey`:
+.. _`tsref-type-EcdhePublicKey`:
+.. _`tsref-type-EcdhePrivateKey`:
 .. _`tsref-type-EddsaPrivateKey`:
 .. _`tsref-type-CoinPublicKey`:
 
 .. code-block:: tsref
 
-   // EdDSA public keys always point on Curve25519 (FIXME does that hold for private keys as well?) and represented
+   // EdDSA and ECDHE public keys always point on Curve25519 (FIXME does that hold for private
+   // keys as well?) and represented
    // using the standard 256 bits Ed25519 compact format, converted to Crockford
    // `Base32`_.
    type EddsaPublicKey = string;
@@ -643,6 +646,19 @@ within the :ref:`exchange's codebase <exchange-repo>`.
   };
 
 
+.. _TALER_PaymentResponsePS:
+.. sourcecode:: c
+
+  struct PaymentResponsePS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MERCHANT_PAYMENT_OK
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_HashCode h_contract;
+  };
+
+
+.. _TALER_ContractPS:
 .. sourcecode:: c
 
   struct TALER_ContractPS {
@@ -654,6 +670,7 @@ within the :ref:`exchange's codebase <exchange-repo>`.
       struct TALER_AmountNBO total_amount;
       struct TALER_AmountNBO max_fee;
       struct GNUNET_HashCode h_contract;
+      struct TALER_MerchantPublicKeyP merchant_pub;
   };
 
   struct TALER_ConfirmWirePS {
diff --git a/api-exchange.rst b/api-exchange.rst
index ac5ef0aa..9a8eb5ff 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -231,7 +231,7 @@ Obtaining wire-transfer information
       //
       // A single /wire response can contain an arbitrary number of these
       // string-object pairs.  However, the keys must be unique.
-      string : Object; // <- FIXME: is this key-value notation correct?
+      string: Object;
      }
 
   Possible encodings for the objects are right now the following:
@@ -357,7 +357,7 @@ exchange.
       // Transfer details uniquely identifying the transfer, only present if type is "DEPOSIT".
       transfer_details?: any;
 
-      // `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW".      
+      // `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW".
       details?: string;
 
       // Signature over the transaction `details`.
@@ -651,9 +651,11 @@ the API during normal operation.
       // Information about coin being melted.
       melt_coin: MeltCoin;
 
-      // For each of the `n` new coins, `kappa` transfer keys.
-      // coin_evs[j][k] is the k-th blank (of kappa) for the k-th new coin (of n).
-      coin_evs: CoinBlank[][]; // FIXME TBD
+      // The outer dimension of the 2d array has `kappa` entries
+      // for the cut-and-choose protocol.
+      // The inner array contains `n` entries with blinded coins,
+      // matching the respective entries in `new_denoms`.
+      coin_evs: CoinEnvelope[][];
 
       // `kappa` transfer public keys (ephemeral ECDHE keys)
       transfer_pubs: EddsaPublicKey[];
@@ -798,33 +800,31 @@ the API during normal operation.
       // Constant "commitment violation"
       error: string;
 
-      // offset of in the array of `kappa` commitments where the error
-      // was detected
-      offset: number;
+      // Signature of the coin over the melting operation.
+      coin_sig: EddsaSignature;
+
+      // Coin that we failed to successfully melt.
+      coin_pub: EddsaPublicKey;
+
+      // Amount of the value of the coin to be melted in the refresh session.
+      melt_amount_with_fee: Amount;
 
-      // index of in the with respect to the new coin where the error was
-      // detected, or 2^32-1 if the error is not dependnet on an offeset
-      // related to the new coins.
-      index: number;
+      // Fee that was due for the melting for the coin.
+      melt_fee: Amount;
 
-      // name of the entity that failed the check (i.e. "transfer key")
-      object: string;
+      // Denomination keys to be used for the coins to be withdrawn.
+      newcoin_infos: RsaPublicKey[];
 
-      // Information about each melted coin
-      refresh_melt_info: OldCoinInfo; // FIXME
+      // Array of blinded coins to be withdrawn.  Same length as
+      // `newcoin_infos`.
+      commit_infos: CoinEnvelope[];
 
-      // array with RSA denomination public keys of the coins the original
-      // refresh request asked to be exchangeed
-      newcoins_infos: RsaPublicKey[];
+      // Transfer public key at index `gamma`.
+      gamma_tp: EddsaPublicKey;
 
-      // array with `kappa` entries containing as elements
-      // objects with the linkage information
-      link_infos: LinkInfo[];
+      // Specific `gamma` value chosen by the exchange.
+      gamma: number;
 
-      // 2D array with `kappa` entries in the first dimension and the same
-      // length as `newcoin_infos` in the 2nd dimension containing as elements
-      // objects with the commitment information
-      commit_infos: CommitInfo[][];
     }
 
 
@@ -978,7 +978,7 @@ typically also view the balance.)
   .. _tsref-type-TrackTransferDetail:
   .. code-block:: tsref
 
-    interface WireDepositDetail {
+    interface TrackTransferDetail {
       // SHA-512 hash of the contact of the merchant with the customer.
       H_contract: HashCode;
 
@@ -1298,8 +1298,8 @@ Administrative API: Bank transactions
       // Transaction identifier in the wire details
       transaction: number;
 
-      // Wire transaction details, as originally specified by the merchant
-      wire: any;
+      // `Wire transaction details <wireformats>`_, as originally specified by the merchant
+      wire: Object;
     }
 
   **Response**
@@ -1507,8 +1507,8 @@ binary-compatible with the implementation of the exchange.
       // Private transfer key
       trans_priv: string;
 
-      // Coin public ket
-      coin_pub: string;
+      // `Coin public key <eddsa-coin-pub>`_
+      coin_pub: EddsaPublicKey;
     }
 
   **Response:**
diff --git a/api-merchant.rst b/api-merchant.rst
index f5a83985..8705069d 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -57,11 +57,13 @@ The Frontent HTTP API
   .. code-block:: tsref
 
     interface DepositPermission {
-      // the hashed :ref:`wire details <wireformats>` of this merchant. The wallet takes this value as-is from the contract
-      // `MyStruct`_
-      H_wire: MyStruct;
+      // the hashed `wire details <wireformats>`_ of this merchant.
+      // The wallet takes this value as-is from the contract 
+      H_wire: HashCode;
 
-      // the base32 encoding of the field `h_contract` of the contract `blob <contract-blob>`. The wallet can choose whether to take this value obtained from the field `h_contract`, or regenerating one starting from the values it gets within the contract
+      // `base32`_ encoded `TALER_ContractPS`_. The wallet can choose whether
+      // to take this value obtained from the field `h_contract`,
+      // or regenerating one starting from the values it gets within the contract
       H_contract: HashCode;
 
       // a 53-bit number corresponding to the contract being agreed on
@@ -73,10 +75,11 @@ The Frontent HTTP API
       // maximum fees merchant agreed to cover as per the contract
       max_fee: Amount;
 
-      // The merchant instance which is going to receive the final wire transfer. See :ref:`instances-lab`
+      // The merchant instance which is going to receive the final wire transfer.
+      // See `instances-lab`_
       receiver: string;
 
-      // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT
+      // Signature of `TALER_ContractPS`_
       merchant_sig: EddsaSignature;
 
       // a timestamp of this deposit permission. It equals just the contract's timestamp
@@ -107,10 +110,10 @@ The Frontent HTTP API
       // denomination key
       denom_pub: RsaPublicKey;
 
-      // exchange's signature over this coin's public key
+      // exchange's signature over this `coin's public key <eddsa-coin-pub>`_
       ub_sig: RsaSignature;
 
-      // the signature made by the coin's private key on a `struct TALER_DepositRequestPS`. See section `Signatures` on the exchange's API page.
+      // Signature of `TALER_DepositRequestPS`_
       coin_sig: EddsaSignature;
     }
 
@@ -204,7 +207,7 @@ The following API are made available by the merchant's `backend` to the merchant
   .. code-block:: tsref
 
     interface PaymentResponse {
-      // Signature of TALER_SIGNATURE_MERCHANT_PAYMENT_OK made by the merchant
+      // Signature of `TALER_PaymentResponsePS`_
       merchant_sig: EddsaSignature;
 
       // Contract's hash being signed over
@@ -387,12 +390,6 @@ The following API are made available by the merchant's `backend` to the merchant
       total_amount: Amount;
     }
 
----------
-Encodings
----------
-
-Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
-
 .. _contract:
 
 ------------------
@@ -410,22 +407,34 @@ that is legally non-binding:
       // The actual contract
       contract: Contract;
 
-      // The hash of the contract, encoded in base32, provided
-      // as a convenience.  All components that do not fully trust
-      // the merchant must verify this field.
+      // Contract's hash, provided as a convenience.  All components that do
+      // not fully trust the merchant must verify this field.
       H_contract: HashCode ;
 
-      // Signature over the contract made by the merchant.
-      // Must confirm to the `Signature specification`_ below.
+      // Signature over the hashcode of `contract` made by the merchant.
       merchant_sig: EddsaSignature;
     }
 
+.. note::
+  When the contract is signed by the merchant or the wallet, the
+  signature is made over the hash of the JSON text, as the contract may
+  be confidential between merchant and customer and should not be
+  exposed to the exchange.  The hashcode is generated by hashing the
+  encoding of the contract's JSON obtained by using the flags
+  ``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson
+  documentation
+  <https://jansson.readthedocs.org/en/2.7/apiref.html?highlight=json_dumps#c.json_dumps>`_.
+
 The `contract` must have the following structure:
 
   .. _tsref-type-Contract:
   .. code-block:: tsref
 
     interface Contract {
+      // Human-readable description of the whole purchase
+      // NOTE: still not implemented
+      summary: string;
+
       // Total price for the transaction.
       // The exchange will subtract deposit fees from that amount
       // before transfering it to the merchant.
@@ -484,9 +493,8 @@ The `contract` must have the following structure:
       // Exchanges that the merchant accepts even if it does not accept any auditors that audit them.
       exchanges: Exchange[];
 
-      // Map from label to a `Location`_.
-      // The label strings must not contain a colon (`:`).
-      locations: { [label: string]: Location>;
+      // Map from label to a location
+      locations: { [label: string]: Location }; // FIXME make 'Location' clickable
     }
 
   The wallet must select a exchange that either the mechant accepts directly by listing it in the exchanges arry, or for which the merchant accepts an auditor that audits that exchange by listing it in the auditors array.
@@ -553,19 +561,22 @@ The `contract` must have the following structure:
       street_number?: string;
     }
 
-  .. code-block:: ts
+  .. _tsref-type-Auditor:
+  .. code-block:: tsref
 
     interface Auditor {
       // official name
       name: string;
 
-      auditor_pub: EddsaPublicKey
+      // Auditor's public key
+      auditor_pub: EddsaPublicKey;
 
       // Base URL of the auditor
       url: string;
     }
 
-  .. code-block:: ts
+  .. _tsref-type-Exchange:
+  .. code-block:: tsref
 
     interface Exchange {
       // the exchange's base URL
@@ -574,45 +585,3 @@ The `contract` must have the following structure:
       // master public key of the exchange
       master_pub: EddsaPublicKey;
     }
-
-
-.. _`Signature specification`:
-
-When the contract is signed by the merchant or the wallet, the
-signature is made over the hash of the JSON text, as the contract may
-be confidential between merchant and customer and should not be
-exposed to the exchange.  The hashcode is generated by hashing the
-encoding of the contract's JSON obtained by using the flags
-``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson
-documentation
-<https://jansson.readthedocs.org/en/2.7/apiref.html?highlight=json_dumps#c.json_dumps>`_.
-The following structure is a container for the signature. The purpose
-should be set to ``TALER_SIGNATURE_MERCHANT_CONTRACT``.
-
-.. _contract-blob:
-.. code-block:: c
-
-   struct MERCHANT_Contract
-   {
-     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-     /**
-      * Transaction ID must match the one in the JSON contract, here given
-      * in big endian.
-      */
-     uint64_t transaction_id;
-
-     /**
-      * Total amount to be paid for the contract, must match JSON "amount".
-      */
-     struct TALER_AmountNBO total_amount;
-
-     /**
-      * Total amount to be paid for the contract, must match JSON "max_fee".
-      */
-     struct TALER_AmountNBO max_fee;
-
-     /**
-      * Hash of the overall JSON contract.
-      */
-     struct GNUNET_HashCode h_contract;
-   }
diff --git a/index.rst b/index.rst
index dae34d12..73d4d8c8 100644
--- a/index.rst
+++ b/index.rst
@@ -107,6 +107,7 @@ core components of the Taler reference implementation.
   dev-exchange
   dev-merchant
   deployment.rst
+  releases.rst
 
 ------------------
 Indices and tables
diff --git a/integration-merchant.rst b/integration-merchant.rst
index 9ac4ece3..b07f1339 100644
--- a/integration-merchant.rst
+++ b/integration-merchant.rst
@@ -47,38 +47,23 @@ By design, the Taler payment process ensures the following three properties:
    typically allow the other user to perform the same purchase (assuming the item
    is still available).
 
-We call an *offer URL* the user-visible URL of the merchant's Web site
-that triggers the generation of a contract, and the display of the
-contract to the user via the wallet.  The offer URL may include support
-for payment systems other than Taler, for example by including a credit
-card form in the body.  The interaction with the wallet can be started
-over JavaScript or by returning a "402 Payment Required" status code
-with Taler-specific headers. Detailed documentation about involved headers
-is found in a dedicated article, hosted in the wallet git repository, at
-the path `articles/ui/ui.pdf`. It is merchant's choice to initiate the
-communication via JavaScript or "402 Payment Required", but they need to
-take into account that the user may have JavaScript disabled. As for the
-JavaScript tecnique of initiating a communication, please refer to the
-page :ref:`integration-general`.
-
-The merchant may have a *contract URL* which generates the contract
-in JSON format for Taler.  Alternatively, the contract may be embedded
+We call an *offer URL* any URL at the merchant's Web site that notifies the
+wallet that the user needs to pay for something. The offer URL must take into
+account that the user has no wallet installed, and manage the situation accordingly
+(for example, by showing a credit card paywall).
+
+The merchant needs to have a *contract URL* which generates the JSON
+contract for Taler.  Alternatively, the contract may be embedded
 within the page returned by the offer URL and given to the wallet
 via JavaScript or via an HTTP header.
 
 The merchant must also provide a *pay URL* to which the wallet can
-transmit the payment, which is HTTP POSTing coins. Again, how this
-URL is make known from the merchant to the wallet, it is managed by
-the HTTP headers- or JavaScript-based protocol.
-
-The merchant must have a *fulfillment URL* which checks whether the
-customer has paid.  When the fulfillment URL is triggered the first
-time (which happens when the user accepts the contract), this will not
-(yet) be the case.  In this case, the merchant generates another "402
-Payment Required" status code which will trigger the actual payment from
-the wallet to the *pay URL*.  The wallet will then reload the fulfillment
-URL, and this time the merchant should return the online resource the customer
-paid for (or the shipping status for physical goods).
+transmit the payment. Again, how this URL is made known from the merchant
+to the wallet, it is managed by the HTTP headers- or JavaScript-based protocol.
+
+The merchant must have a *fulfillment URL* which is in charge of doing
+two thigs: give to the user what he paid for, or redirect the user
+to the offer URL in case he did not pay.
 
 -------
 Example
@@ -87,8 +72,9 @@ Example
 For example, suppose Alice wants to pay for a movie.  She will first
 select the movie from the catalog, which directs her to the offer URL
 *https://merchant/offer?x=8ru42*.  This URL generates a "402 Payment
-Required" response, with a contract stating that Alice is about to buy
-some movie.  The contract includes a fresh transaction ID, say 62.
+Required" response, and will instruct the wallet about the contract's
+URL. Then the wallet downloads the contract that states that Alice is
+about to buy a movie.  The contract includes a fresh transaction ID, say 62.
 Alice's browser detects the response code and displays the contract
 for Alice.
 
@@ -111,7 +97,7 @@ successful, and then reload the fulfillment URL.
 This time (and every time in the future where Alice visits the
 fulfillment URL), she receives the movie.  If the browser has lost the
 session state, the merchant will again ask her to pay (as it happened the
-very first time she visited the fulfillment URK), and she will authenticate
+very first time she visited the fulfillment URL), and she will authenticate
 by replaying the payment.
 
 If Alice decides to share the fulfillment URL with Bob and he visits
@@ -124,17 +110,12 @@ purchase the movie himself.
 Making an offer
 ---------------
 
-The offer URL is a location where the user must pass by in order to get a contract.
-Note that this URL is not strictly asked to initiate the interaction with the
-wallet. For example, if a Website lets first pick the item to buy and *then* the
-payment method in a second page, then we call offer URL only the first page,
-although the communication with the wallet will be initialized by the second page.
-Note that, whenever a user accepts a contract, the wallet will automatically store
-that contract's hash in an internal database. That happens for three reasons:
-
-* to have a cryptographic proof of the user's (and merchant's) activity
-* to not show again the same contract to the user when visiting the fulfillment page
-* to associate the same set of coins with this contract, in order to replay payments
+When a user visits a offer URL, the merchant returns a page that can interact
+with the wallet either via JavaScript or by returning a "402 Payment Required".
+This page's main objective is to inform the wallet on where it should get the
+contract. In case of JavaScript interaction, this is done by FIXME, whereas
+in case of "402 Payment Required", a `X-Taler-contract-url` HTTP header will
+be set to the contract's location. (FIXME: is that right?).
 
 -------------------------------
 Fulfillment interaction details
@@ -169,4 +150,4 @@ By looking at `X-taler-contract-hash`, the wallet can face two situations:
 1. This hashcode is already present in the wallet's database, so the wallet can send the payment to `X-taler-pay-URL`.  During this operation, the wallet associates the data it sent to `X-taler-pay-URL` with the received hashcode, so that it can replay payments whenever it gets this hashcode again.
 2. This hashcode is unknown to the wallet, so the wallet can point the browser to `X-taler-offer-URL`, so the user will get the contract and decide to accept it or not.  This happens when the user gets the fulfillment URL from someone else.
 
-FIXME: explain the JavaScript way ..
+FIXME: explain the JavaScript way
diff --git a/releases.rst b/releases.rst
new file mode 100644
index 00000000..d0191ba0
--- /dev/null
+++ b/releases.rst
@@ -0,0 +1,103 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 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
+
+
+==============================
+Release Process and Checklists
+==============================
+
+This document describes the process for releasing a new version of the various
+Taler components to the official GNU mirrors.
+
+The following components are published on the GNU mirrors
+
+* taler-exchange (exchange.git)
+* taler-merchant (merchant.git)
+* talerfrontends (merchant-frontends.git)
+* taler-bank (bank.git)
+* taler-wallet-webex (wallet-webex.git)
+
+
+-------
+Tagging
+-------
+
+Tag releases with an *annotated* commit, like
+
+::
+
+  git tag -a v0.1.0 -m "Official release v0.1.0"
+  git push origin v0.1.0
+
+------------------
+Database for tests
+------------------
+
+For tests in the exchange and merchant to run, make sure that
+a database `talertest` is accessible by `$USER`.  Otherwise tests
+involving the database logic are skipped.
+
+------------------
+Exchange, merchant
+------------------
+
+Set the version in `configure.ac`.  The commit being tagged
+should be the change of the version.
+
+For the exchange test cases to pass, `make install` must be run first.
+Without it, test cases will fail because plugins can't be located.
+
+::
+
+  ./bootstrap
+  ./configure # add required options for your system
+  make dist
+  tar -xf taler-$COMPONENT-$VERSION.tar.gz
+  cd taler-$COMPONENT-$VERSION
+  make install check
+
+--------------------
+Wallet WebExtension
+--------------------
+
+The version of the wallet is in `manifest.json`.  The `version_name` should be
+adjusted, and `version` should be increased independently on every upload to
+the WebStore.
+
+::
+
+  ./configure
+  make dist
+
+
+
+FIXME: selenium test cases
+
+
+----------------------
+Upload to GNU mirrors
+----------------------
+
+See https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
+
+Directive file: 
+
+::
+
+  version: 1.2
+  directory: taler
+  filename: taler-exchange-0.1.0.tar.gz
+
+
+Upload the files in *binary mode* to the ftp servers.
diff --git a/versioning.rst b/versioning.rst
index 957d900c..14336da0 100644
--- a/versioning.rst
+++ b/versioning.rst
@@ -49,9 +49,7 @@ Alpha and Beta releases
 Before Taler is considered reasonably stable for actual use, we will
 prefix the number "0." to the release version.  Thus, all alpha and
 beta releases will have a three-digit release number of the form
-"0.MAJOR.MINOR"; here, the "0."  indicates that the software may not
-yet be stable enough for real world applications.
-
+"0.MAJOR.MINOR".
 
 -----------------------
 Roadmap