initial rough import of other docs

1 files changed, 232 insertions, 0 deletions

diff --git a/core/api-auditor.rst b/core/api-auditor.rst
new file mode 100644
index 00000000..957b1c01
--- /dev/null
+++ b/core/api-auditor.rst
@@ -0,0 +1,232 @@
+..
+  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:**
+
+  .. _AuditorVersion:
+  .. 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;
+    }
+
+  .. note::
+
+    This API is still experimental (and is not yet implemented at the
+    time of this writing).
+
+
+.. _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 {
+
+      // Master public key of the exchange
+      master_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;
+
+      // Master public key of the exchange corresponding to @e master_sig.
+      // Identifies the exchange this is about.
+      master_pub: EddsaPublicKey;
+
+      // When does the validity of the exchange_pub end?
+      ep_start: Timestamp;
+
+      // When will the exchange stop using the signing key?
+      ep_expire: Timestamp;
+
+      // When does the validity of the exchange_pub end?
+      ep_end: Timestamp;
+
+      // Exchange master signature over @e exchange_sig.
+      master_sig: EddsaSignature;
+    }
+
+  .. 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.