[GNUnet-SVN] [taler-api] branch master updated: add first design of auditor HTTP API

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository api.

The following commit(s) were added to refs/heads/master by this push:
     new e3b947c  add first design of auditor HTTP API
e3b947c is described below

commit e3b947cdaa944b0f2e1ac0c33f60616aecbaa76c
Author: Christian Grothoff <address@hidden>
AuthorDate: Sat Oct 20 19:17:02 2018 +0200

    add first design of auditor HTTP API
---
 api-auditor.rst | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 index.rst       |   4 +-
 2 files changed, 220 insertions(+), 1 deletion(-)

diff --git a/api-auditor.rst b/api-auditor.rst
new file mode 100644
index 0000000..72c2ac3
--- /dev/null
+++ b/api-auditor.rst
@@ -0,0 +1,217 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2018 Taler Systems SA
+
+  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 Christian Grothoff
+
+============================
+The Auditor RESTful JSON API
+============================
+
+The API specified here follows the :ref:`general conventions <http-common>`
+for all details not specified in the individual requests.
+The `glossary <https://docs.taler.net/glossary.html#glossary>`
+defines all specific terms used in this section.
+
+.. _auditor-version:
+
+-------------------------
+Obtaining Auditor Version
+-------------------------
+
+This API is used by merchants to obtain a list of all exchanges audited by
+this auditor.  This may be required for the merchant to perform the required
+know-your-customer (KYC) registration before issuing contracts.
+
+.. http:get:: /version
+
+  Get the protocol version and some meta data about the auditor.
+
+  **Response:**
+
+  :status 200 OK:
+    The auditor responds with a `AuditorVersion`_ object. This request should
+    virtually always be successful.
+
+  **Details:**
+
+  .. _ExchangeList:
+  .. code-block:: tsref
+
+    interface AuditorVersion {
+      // libtool-style representation of the Taler protocol version, see
+      // 
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".  Note that the auditor
+      // protocol is versioned independently of the exchange's protocol.
+      version: String;
+
+      // Return which currency this auditor is auditing for.
+      currency: String;
+
+      // EdDSA master public key of the auditor
+      auditor_public_key: EddsaPublicKey;
+    }
+
+.. _exchange-list:
+
+-----------------------
+Obtaining Exchange List
+-----------------------
+
+This API is used by merchants to obtain a list of all exchanges audited by
+this auditor.  This may be required for the merchant to perform the required
+know-your-customer (KYC) registration before issuing contracts.
+
+.. http:get:: /exchanges
+
+  Get a list of all exchanges audited by the auditor.
+
+  **Response:**
+
+  :status 200 OK:
+    The auditor responds with a `ExchangeList`_ object. This request should
+    virtually always be successful.
+
+  **Details:**
+
+  .. _ExchangeList:
+  .. code-block:: tsref
+
+    interface ExchangeList {
+      // Exchanges audited by this auditor
+      exchanges: ExchangeEntry[];
+    }
+
+  .. _tsref-type-Denom:
+  .. code-block:: tsref
+
+    interface ExchangeEntry {
+
+      // Public key of the exchange
+      exchange_pub: EddsaPublicKey;
+
+      // Base URL of the exchange
+      exchange_url: string;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing). A key open question is whether the auditor
+    should sign the information. We might also want to support more
+    delta downloads in the future.
+
+.. _deposit-confirmation:
+
+--------------------------------
+Submitting deposit confirmations
+--------------------------------
+
+Merchants should probabilistically submit some of the deposit
+confirmations they receive from the exchange to auditors to ensure
+that the exchange does not lie about recording deposit confirmations
+with the exchange. Participating in this scheme ensures that in case
+an exchange runs into financial trouble to pay its obligations, the
+merchants that did participate in detecting the bad behavior can be
+paid out first.
+
+.. http:put:: /deposit-confirmation
+
+   Submits a `DepositConfirmation`_ to the exchange. Should succeed
+   unless the signature provided is invalid or the exchange is not
+   audited by this auditor.
+
+  **Response:**
+
+  :status 200: The auditor responds with a `DepositAudited`_ object.
+               This request should virtually always be successful.
+
+  **Details:**
+
+  .. _DepositAudited:
+  .. _tsref-type-DepositAudited:
+  .. code-block:: tsref
+
+    interface DepositAudited {
+        // TODO: do we care for the auditor to sign this?
+    }
+
+  .. _DepositConfirmation:
+  .. _tsref-type-DepositConfirmation:
+  .. code-block:: tsref
+
+    interface DepositConfirmation {
+
+      // Hash over the contract for which this deposit is made.
+      h_contract_terms: HashCode;
+
+      // Hash over the wiring information of the merchant.
+      h_wire: HashCode;
+
+      // Time when the deposit confirmation confirmation was generated.
+      timestamp: Timestamp;
+
+      // How much time does the merchant have to issue a refund
+      // request?  Zero if refunds are not allowed.
+      refund_deadline : Timestamp;
+
+      // Amount to be deposited, excluding fee.  Calculated from the
+      // amount with fee and the fee from the deposit request.
+      amount_without_fee: Amount;
+
+      // The coin's public key.  This is the value that must have been
+      // signed (blindly) by the Exchange.  The deposit request is to be
+      // signed by the corresponding private key (using EdDSA).
+      coin_pub: CoinPublicKey;
+
+      // The Merchant's public key.  Allows the merchant to later refund
+      // the transaction or to inquire about the wire transfer identifier.
+      merchant_pub: EddsaPublicKey;
+
+      // Signature from the exchange of type
+      // TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT.
+      exchange_sig: EddsaSignature;
+
+      // Public signing key from the exchange matching @e exchange_sig.
+      exchange_pub: EddsaPublicKey;
+
+      // Exchange master signature over @e exchange_sig.
+      master_sig: EddsaSignature;
+
+      // Master public key of the exchange corresponding to @e master_sig.
+      // Identifies the exchange this is about.
+      master_public_key: EddsaPublicKey;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing). A key open question is whether the auditor
+    should sign the response information.
+
+
+----------
+Complaints
+----------
+
+This API is used by the wallet or merchants to submit proof of
+misbehavior of an exchange to the auditor.
+
+  .. note::
+
+     To be designed and implemented.
+
+  .. http:put:: /complain
+
+  Complain about missbehavior to the auditor.
diff --git a/index.rst b/index.rst
index d96cd38..e883b58 100644
--- a/index.rst
+++ b/index.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014, 2015, 2016, 2017 GNUnet e.V.
+  Copyright (C) 2014-2018 GNUnet e.V.
 
   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
@@ -17,6 +17,7 @@
   @author Benedikt Muller
   @author Sree Harsha Totakura
   @author Marcello Stanisci
+  @author Christian Grothoff
 
 GNU Taler Documentation
 =======================
@@ -56,6 +57,7 @@ interfaces between the core components of Taler.
   api-error
   api-exchange
   api-merchant
+  api-auditor
   api-bank
   wireformats
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden