update exchange API spec for #6175

1 files changed, 282 insertions, 3 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 29035eac..3a35637b 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:
 
 -----------------------------------