[taler-docs] branch master updated: update exchange API spec for #6175

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new bca4ec6  update exchange API spec for #6175
bca4ec6 is described below

commit bca4ec6e3d2341763f3c59c05a76e677689ff402
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Nov 24 14:02:52 2020 +0100

    update exchange API spec for #6175
---
 core/api-exchange.rst     | 285 +++++++++++++++++++++++++++++++++++++++++++++-
 taler-exchange-manual.rst |   6 +-
 2 files changed, 285 insertions(+), 6 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 29035ea..3a35637 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -87,13 +87,13 @@ possibly by using HTTPS.
 
 .. http:get:: /keys
 
-  Get a list of all denomination keys offered by the bank,
-  as well as the bank's current online signing key.
+  Get a list of all denomination keys offered by the exchange,
+  as well as the exchange's current online signing key.
 
   **Request:**
 
   :query last_issue_date: optional argument specifying the maximum value of 
any of the "stamp_start" members of the denomination keys of a "/keys" response 
that is already known to the client. Allows the exchange to only return keys 
that have changed since that timestamp.  The given value must be an unsigned 
64-bit integer representing seconds after 1970.  If the timestamp does not 
exactly match the "stamp_start" of one of the denomination keys, all keys are 
returned.
-  :query now: request that the exchange answer the request as if the current 
time were the value given in "now".  The given value must be an unsigned 64-bit 
integer representing seconds after 1970.  This option is used for testing, and 
in production is likely not supported. 
+  :query now: request that the exchange answer the request as if the current 
time were the value given in "now".  The given value must be an unsigned 64-bit 
integer representing seconds after 1970.  This option is used for testing, and 
in production is likely not supported.
 
   **Response:**
 
@@ -276,6 +276,285 @@ possibly by using HTTPS.
     Both the individual denominations *and* the denomination list is signed,
     allowing customers to prove that they received an inconsistent list.
 
+------------------------------------
+Providing signatures for future keys
+------------------------------------
+
+.. http:get:: /keys/future
+
+  Get a list of future public keys to be used by the exchange.  Only to be
+  used by the exchange's offline key management team. Not useful for anyone
+  else (but also not secret, so access is public).
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The exchange responds with a `FutureKeysResponse` object. This request 
should
+    virtually always be successful.
+
+  **Details:**
+
+  .. ts:def:: FutureKeysResponse
+
+    interface FutureKeysResponse {
+
+      // Future denominations to be offered by this exchange
+      // (only those lacking a master signature).
+      future_denoms: FutureDenom[];
+
+      // The exchange's future signing keys (only those lacking a master 
signature).
+      future_signkeys: FutureSignKey[];
+
+    }
+
+  .. ts:def:: FutureDenom
+
+    interface FutureDenom {
+      // How much are coins of this denomination worth?
+      value: Amount;
+
+      // When does the denomination key become valid?
+      stamp_start: Timestamp;
+
+      // When is it no longer possible to deposit coins
+      // of this denomination?
+      stamp_expire_withdraw: Timestamp;
+
+      // Timestamp indicating by when legal disputes relating to these coins 
must
+      // be settled, as the exchange will afterwards destroy its evidence 
relating to
+      // transactions involving this coin.
+      stamp_expire_legal: Timestamp;
+
+      // Public (RSA) key for the denomination.
+      denom_pub: RsaPublicKey;
+
+      // Fee charged by the exchange for withdrawing a coin of this 
denomination
+      fee_withdraw: Amount;
+
+      // Fee charged by the exchange for depositing a coin of this denomination
+      fee_deposit: Amount;
+
+      // Fee charged by the exchange for refreshing a coin of this denomination
+      fee_refresh: Amount;
+
+      // Fee charged by the exchange for refunding a coin of this denomination
+      fee_refund: Amount;
+
+    }
+
+  .. ts:def:: FutureSignKey
+
+    interface SignKey {
+      // The actual exchange's EdDSA signing public key.
+      key: EddsaPublicKey;
+
+      // Initial validity date for the signing key.
+      stamp_start: Timestamp;
+
+      // Date when the exchange will stop using the signing key, allowed to 
overlap
+      // slightly with the next signing key's validity to allow for clock skew.
+      stamp_expire: Timestamp;
+
+      // Date when all signatures made by the signing key expire and should
+      // henceforth no longer be considered valid in legal disputes.
+      stamp_end: Timestamp;
+
+    }
+
+
+.. http:post:: /keys/future
+
+  Provide master signatures for future public keys to be used by the exchange.
+  Only to be used by the exchange's offline key management team. Not useful
+  for anyone else.
+
+  **Request:** The request body must be a `MasterSignatures` object.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The request was successfully processed.
+  :http:statuscode:`403 Forbidden`:
+    A provided signature is invalid.
+
+  **Details:**
+
+  .. ts:def:: MasterSignatures
+
+    interface MasterSignatures {
+
+      // Provided master signatures for future denomination keys.
+      denom_sigs: DenomSignature[];
+
+      // Provided master signatures for future online signing keys.
+      signkey_sigs: SignKeySignature[];
+
+    }
+
+  .. ts:def:: DenomSignature
+
+    interface DenomSignature {
+
+      // Hash of the pbulic (RSA) key of the denomination.
+      h_denom_pub: HashCode;
+
+      // Signature of `TALER_DenominationKeyValidityPS`
+      master_sig: EddsaSignature;
+
+    }
+
+  .. ts:def:: SignKeySignature
+
+    interface SignKeySignature {
+      // The actual exchange's EdDSA signing public key.
+      key: EddsaPublicKey;
+
+      // Signature by the exchange master key.
+      // Must have purpose TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY.
+      master_sig: EddsaSignature;
+
+    }
+
+-------------------
+Setting up auditors
+-------------------
+
+
+.. http:post:: /auditors
+
+  This request will be used to enable an auditor.
+
+  **Request:**
+
+  The request must be a `AuditorSetupMessage`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The auditor was successfully enabled.
+  :http:statuscode:`403 Forbidden`:
+    The master signature is invalid.
+  :http:statuscode:`409 Conflict`:
+    The exchange has a more recent request related to this auditor key (replay 
detected).
+
+  **Details:**
+
+  .. ts:def:: AuditorSetupMessage
+
+    interface AuditorSetupMessage {
+
+      // base URL of the auditor
+      auditor_url: string;
+
+      // The auditor's EdDSA signing public key.
+      auditor_pub: EddsaPublicKey;
+
+      // Signature by the exchange master key.
+      // Must have purpose TALER_SIGNATURE_MASTER_AUDITOR_ADD.
+      master_sig: EddsaSignature;
+
+      // When does the auditor become active?
+      // Should be the time when the signature was created,
+      // using the (monotonic!) local time of the system
+      // with the offline master public key. Note that
+      // even if the time is in the future, the auditor will
+      // become active immediately! Used ONLY to detect replay attacks.
+      validity_start: Timestamp;
+
+    }
+
+.. http:delete:: /auditors/$AUDITOR_PUB
+
+  This request will be used to disable
+  the use of the given auditor.
+
+  **Request:**
+
+  The request must be a `AuditorTeardownMessage`.
+
+  **Response**
+
+  :http:statuscode:`204 No content`:
+    The auditor has successfully disabled the auditor. The body is empty.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The auditor is unknown to the exchange.
+  :http:statuscode:`409 Conflict`:
+    The exchange has a more recent request related to this auditor key (replay 
detected).
+
+  **Details:**
+
+  .. ts:def:: AuditorTeardownMessage
+
+    interface AuditorTeardownMessage {
+
+      // The auditor's EdDSA signing public key.
+      auditor_pub: EddsaPublicKey;
+
+      // Signature by the exchange master key.
+      // Must have purpose TALER_SIGNATURE_MASTER_AUDITOR_DEL.
+      master_sig: EddsaSignature;
+
+      // When does the auditor become inactive?
+      // Should be the time when the signature was created,
+      // using the (monotonic!) local time of the system
+      // with the offline master public key.  Note that
+      // even if the time is in the future, the auditor will
+      // become inactive immediately! Used ONLY to detect replay attacks.
+      validity_end: Timestamp;
+
+    }
+
+
+---------------
+Auditor actions
+---------------
+
+.. _auditor_action:
+
+Auditor actions are used by auditors interacting with the exchange.
+
+
+.. http:post:: /keys
+
+  This is used to add an auditor signature to the ``/keys`` response.
+
+  **Request:**
+
+  The request must be a `AuditorSignatureAddMessage`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully stored the auditor signature.
+  :http:statuscode:`403 Forbidden`:
+    The auditor signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The denomination key for which the auditor is providing a signature is 
unknown.
+  :http:statuscode:`410 Gone`:
+    This auditor is no longer supported by the exchange.
+  :http:statuscode:`412 Precondition failed`:
+    This auditor is not yet known to the exchange.
+
+  .. ts:def:: AuditorSignatureAddMessage
+
+    interface AuditorSignatureAddMessage {
+
+      // The auditor's EdDSA signing public key.
+      auditor_pub: EddsaPublicKey;
+
+      // Signature by the auditor.
+      // Must have purpose TALER_SIGNATURE_AUDITOR_XXX.
+      auditor_sig: EddsaSignature;
+
+      // What denomination is the signature for?
+      h_denom_pub: HashCode;
+
+    }
+
+
+
 .. _wire-req:
 
 -----------------------------------
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 74118a7..0b03821 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -540,7 +540,7 @@ The generated file will be echoed by the exchange when 
serving
 .. _Wire-fee-structure:
 
 Wire fee structure
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 .. index:: wire fee
 .. index:: fee
@@ -705,7 +705,7 @@ exchange, and includes HTML, PDF and TXT files. If other 
files are
 present, the exchange may show a warning on startup.
 
 Example
-~~~~~~~
+^^^^^^^
 
 A sample file structure for a TERMS_ETAG of "v1" would be:
 
@@ -897,7 +897,7 @@ GNUNET_CRYPTO_rsa_private_key_decode().
 .. _Revocations:
 
 Revocations
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 When an exchange goes out of business or detects that the private key of
 a denomination key pair has been compromised, it may revoke some or all

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.