summaryrefslogtreecommitdiff
path: root/core/api-auditor.rst
diff options
context:
space:
mode:
Diffstat (limited to 'core/api-auditor.rst')
-rw-r--r--core/api-auditor.rst257
1 files changed, 227 insertions, 30 deletions
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index 321d203e..61e448b8 100644
--- a/core/api-auditor.rst
+++ b/core/api-auditor.rst
@@ -24,6 +24,25 @@ 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.
+.. contents:: Table of Contents
+ :local:
+
+.. _authentication:
+
+--------------
+Authentication
+--------------
+
+Each auditor instance has separate authentication settings for the private API resources
+of that instance.
+
+Currently, the API supports two main authentication methods:
+
+* ``external``: With this method, no checks are done by the auditor backend.
+ Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
+* ``token``: With this method, the client must provide a ``Authorization: Bearer $TOKEN``
+ header, where ``$TOKEN`` is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix.
+
.. _auditor-version:
-------------------------
@@ -34,9 +53,10 @@ 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
+.. http:get:: /config
Get the protocol version and some meta data about the auditor.
+ This specification corresponds to ``current`` protocol being version **1**.
**Response:**
@@ -56,11 +76,19 @@ know-your-customer (KYC) registration before issuing contracts.
// protocol is versioned independently of the exchange's protocol.
version: string;
+ // URN of the implementation (needed to interpret 'revision' in version).
+ // @since v0, may become mandatory in the future.
+ implementation?: string;
+
// Return which currency this auditor is auditing for.
currency: string;
// EdDSA master public key of the auditor.
auditor_public_key: EddsaPublicKey;
+
+ // EdDSA master public key of the exchange.
+ // Added in protocol v1.
+ exchange_master_public_key: EddsaPublicKey;
}
.. note::
@@ -69,58 +97,63 @@ know-your-customer (KYC) registration before issuing contracts.
time of this writing).
-.. _exchange-list:
+.. _exchange_signkeys-list:
------------------------
-Obtaining Exchange List
------------------------
+------------------------------------
+Obtaining Exchange Signing Keys 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.
+This API is used by auditor to obtain a list of all exchanges signing keys to be audited.
-.. http:get:: /exchanges
+.. http:get:: /exchange-sign-keys
- Get a list of all exchanges audited by the auditor.
+ Get a list of all exchange signing keys to be audited by the auditor.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a :ts:type:`ExchangeList` object. This request should
+ The auditor responds with a :ts:type:`ExchangeSignKeysList` object. This request should
virtually always be successful.
**Details:**
- .. ts:def:: ExchangeList
+ .. ts:def:: ExchangeSignKeysList
- interface ExchangeList {
- // Exchanges audited by this auditor.
- exchanges: ExchangeEntry[];
+ interface ExchangeSignKeysList {
+ // Exchange signing keys to be audited by the auditor.
+ exchange-sign-key: ExchangeSignKeyEntry[];
}
- .. ts:def:: ExchangeEntry
+ .. ts:def:: ExchangeSignKeyEntry
- interface ExchangeEntry {
+ interface ExchangeSignKeyEntry {
- // Master public key of the exchange.
- master_pub: EddsaPublicKey;
+ // Public online signing key of the exchange.
+ exchange_pub: EddsaPublicKey;
// Base URL of the exchange.
- exchange_url: string;
+ master_sig: EddsaSignature;
+
+ // Time when online signing key will first be use.
+ ep_valid_from: Timestamp;
+
+ // Time when this online signing key will no longer be used.
+ ep_expire_sign: Timestamp;
+
+ // Time when this online signing key legally expires.
+ ep_expire_legal: Timestamp;
}
.. 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.
+ time of this writing).
.. _deposit-confirmation:
---------------------------------
-Submitting deposit confirmations
---------------------------------
+---------------------
+Deposit Confirmations
+---------------------
Merchants should probabilistically submit some of the deposit
confirmations they receive from the exchange to auditors to ensure
@@ -182,10 +215,12 @@ paid out first.
// 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;
+ // Array of public keys of the deposited coins.
+ coin_pubs: EddsaPublicKey[];
+
+ // Array of deposit signatures of the deposited coins.
+ // Must have the same length as ``coin_pubs``.
+ coin_sigs: EddsaSignature[];
// The Merchant's public key. Allows the merchant to later refund
// the transaction or to inquire about the wire transfer identifier.
@@ -200,6 +235,7 @@ paid out first.
// Master public key of the exchange corresponding to ``master_sig``.
// Identifies the exchange this is about.
+ // @deprecated since v1 (now ignored, global per auditor)
master_pub: EddsaPublicKey;
// When does the validity of the exchange_pub end?
@@ -221,6 +257,167 @@ paid out first.
time of this writing). A key open question is whether the auditor
should sign the response information.
+This API is used by the auditor to obtain a list of all deposit confirmations that the auditor
+did not receive by the exchange, only by the merchant.
+
+.. http:get:: /deposit-confirmation
+
+ Get a list of all deposit confirmations that were not received by the auditor from the exchange to be manually audited.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The auditor responds with a :ts:type:`DepositConfirmationList` object.
+ :http:statuscode:`204 No Content`:
+ No missing deposit confirmations found.
+
+ **Details:**
+
+ .. ts:def:: DepositConfirmationList
+
+ interface DepositConfirmationList {
+ // Deposit confirmations to be audited.
+ deposit-confirmations: DepositConfirmation[];
+ }
+
+ .. ts:def:: DepositConfirmation
+
+ interface DepositConfirmation {
+
+ // Database row id of entry
+ row_id: Integer;
+
+ // 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;
+
+ // By what time does the exchange have to wire the funds?
+ wire_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;
+ }
+
+ .. note::
+
+ This API is still experimental (and is not yet implemented at the
+ time of this writing).
+
+This API is used by the auditor to delete an audited deposit confirmation.
+
+.. http:delete:: /deposit-confirmation/$SERIAL_ID
+
+ Delete deposit confirmation entry with given serial_id.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The deposit confirmation was deleted.
+
+ :http:statuscode:`401 Unauthorized`:
+ Unauthorized request.
+
+ :http:statuscode:`404 Not found`:
+ The deposit confirmation was unknown.
+
+ .. note::
+
+ This API is still experimental (and is not yet implemented at the
+ time of this writing).
+
+.. balances-list:
+
+----------------------------------
+Obtaining list of auditor balances
+----------------------------------
+
+This API is used to obtain a list of all the balances that are stored by the auditor.
+
+.. http:get:: /balances
+
+ Get a list of all balances stored by the auditor.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The auditor responds with a :ts:type:`BalanceList` object.
+
+ :http:statuscode:`409 Conflict`:
+ Balance missing or other error occured.
+
+ **Details:**
+
+ .. ts:def:: BalanceList
+
+ interface BalanceList {
+ // Total amount reported
+ auditor_total_reported_balance: Amount;
+
+ // Amount potentially missing
+ auditor_missing_balance: Amount;
+
+ //...
+ }
+
+ .. note::
+
+ This API is still experimental (and is not yet implemented at the
+ time of this writing). The API will be further developed as needed.
+
+.. denominations-pending-list:
+
+---------------------------------------
+Obtaining list of pending denominations
+---------------------------------------
+
+This API is used by the auditor to obtain a list of pending denominations
+
+.. http:get:: /pending-denominations
+
+ Get a list of all pending denominations.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The auditor responds with a :ts:type:`PendingDenominationList` object.
+
+ :http:statuscode:`204 No content`:
+ No pending demoninations found.
+
+ **Details:**
+
+ .. ts:def:: PendingDenominationList
+
+ interface PendingDenominationList {
+ // PendingDenominationList of the auditor.
+ pending_denomination: PendingDenomination[];
+ }
+
+ .. ts:def:: PendingDenomination
+
+ interface PendingDenomination {
+
+ // Balance of denomination.
+ denom_balance: Amount;
+
+ // Amount that was lost due to failures by the exchange.
+ denom_loss: Amount;
+
+ // Amount at risk of loss due to recoup operations.
+ denom_risk: Amount;
+
+ // Amount actually lost due to recoup operations after a revocation.
+ recoup_loss: Amount;
+ }
+
+ .. note::
+
+ This API is still experimental (and is not yet implemented at the
+ time of this writing).
----------
Complaints