diff options
Diffstat (limited to 'core/api-auditor.rst')
-rw-r--r-- | core/api-auditor.rst | 269 |
1 files changed, 236 insertions, 33 deletions
diff --git a/core/api-auditor.rst b/core/api-auditor.rst index 11294d0a..61e448b8 100644 --- a/core/api-auditor.rst +++ b/core/api-auditor.rst @@ -3,14 +3,14 @@ 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 + terms of the GNU Affero 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. + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with + You should have received a copy of the GNU Affero General Public License along with TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @author Christian Grothoff @@ -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 @@ -162,6 +195,9 @@ paid out first. // Hash over the contract for which this deposit is made. h_contract_terms: HashCode; + // Hash over the extensions. + h_extensions: HashCode; + // Hash over the wiring information of the merchant. h_wire: HashCode; @@ -172,14 +208,19 @@ paid out first. // 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; - // 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. @@ -194,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? @@ -215,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 |