writing API specification for #3887

2 files changed, 137 insertions, 9 deletions

diff --git a/api/api-common.rst b/api/api-common.rst
index 0d4cf50f..3725e1c2 100644
--- a/api/api-common.rst
+++ b/api/api-common.rst
@@ -502,7 +502,7 @@ within the
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct GNUNET_HashCode h_proposal_data;
     struct GNUNET_HashCode h_wire;
-    uint64_t transaction_id GNUNET_PACKED;
+    uint64_t transaction_id;
     struct GNUNET_TIME_AbsoluteNBO timestamp;
     struct GNUNET_TIME_AbsoluteNBO refund_deadline;
     struct TALER_AmountNBO amount_without_fee;
@@ -627,7 +627,7 @@ within the
   struct TALER_WireDepositDetailP {
     struct GNUNET_HashCode h_proposal_data;
     struct GNUNET_TIME_AbsoluteNBO execution_time;
-    uint64_t transaction_id GNUNET_PACKED;
+    uint64_t transaction_id;
     struct TALER_CoinSpendPublicKeyP coin_pub;
     struct TALER_AmountNBO deposit_value;
     struct TALER_AmountNBO deposit_fee;
@@ -718,14 +718,43 @@ within the
 
   struct TALER_RefundRequestPS {
     /**
-      *  purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND
-      */
+     *  purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND
+     */
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_proposal_data GNUNET_PACKED;
-    uint64_t transaction_id GNUNET_PACKED;
+    struct GNUNET_HashCode h_proposal_data;
+    uint64_t transaction_id;
     struct TALER_CoinSpendPublicKeyP coin_pub;
     struct TALER_MerchantPublicKeyP merchant;
-    uint64_t rtransaction_id GNUNET_PACKED;
+    uint64_t rtransaction_id;
     struct TALER_AmountNBO refund_amount;
     struct TALER_AmountNBO refund_fee;
   };
+
+
+.. _TALER_PaybackRequestPS:
+.. sourcecode:: c
+
+  struct TALER_PaybackRequestPS {
+    /**
+     *  purpose.purpose = TALER_SIGNATURE_WALLET_COIN_PAYBACK
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct TALER_CoinSpendPublicKeyP coin_pub;
+    struct GNUNET_HashCode h_denom_pub;
+    struct TALER_DenominationBlindingKeyP coin_blind;
+  };
+
+
+.. _TALER_PaybackConfirmationPS:
+.. sourcecode:: c
+
+  struct TALER_PaybackConfirmationPS {
+    /**
+     *  purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_TIME_AbsoluteNBO payback_deadline;
+    struct TALER_AmountNBO payback_amount;
+    struct TALER_CoinSpendPublicKeyP coin_pub;
+    struct GNUNET_HashCode h_wire_subject;
+  };
diff --git a/api/api-exchange.rst b/api/api-exchange.rst
index d3014cb8..b21fd8bd 100644
--- a/api/api-exchange.rst
+++ b/api/api-exchange.rst
@@ -61,9 +61,12 @@ possibly by using HTTPS.
       // EdDSA master public key of the exchange, used to sign entries in `denoms` and `signkeys`
       master_public_key: EddsaPublicKey;
 
-      // Denomination offered by this exchange.
+      // Denominations offered by this exchange.
       denoms: Denom[];
 
+      // Denominations for which the exchange currently offers/requests payback.
+      payback: Payback[];
+
       // The date when the denomination keys were last updated.
       list_issue_date: Timestamp;
 
@@ -135,6 +138,21 @@ possibly by using HTTPS.
   different currency, but this is not currently supported by the
   implementation.
 
+  .. _tsref-type-Payback:
+  .. code-block:: tsref
+
+    interface Payback {
+      // hash of the public key of the denomination that is being revoked under
+      // emergency protocol (see /payback).
+      h_denom_pub: HashCode;
+
+      // We do not include any signature here, as the primary use-case for
+      // this emergency involves the exchange having lost its signing keys,
+      // so such a signature here would be pretty worthless.  However, the
+      // exchange will not honor /payback requests unless they are for
+      // denomination keys listed here.
+    }
+
   A signing key in the `signkeys` list is a JSON object with the following fields:
 
   .. _tsref-type-SignKey:
@@ -515,7 +533,7 @@ denomination.
     The deposit operation has failed because the coin has insufficient
     residual value; the request should not be repeated again with this coin.
     In this case, the response is a `DepositDoubleSpendError`_.
-  :status 404:
+  :status 404 Not Found:
     Either the denomination key is not recognized (expired or invalid) or
     the wire type is not recognized.
 
@@ -933,6 +951,87 @@ the API during normal operation.
     }
 
 
+-------------------
+Emergency Cash-Back
+-------------------
+
+This API is only used if the exchange is either about to go out of
+business or has had its private signing keys compromised (so in
+either case, the protocol is only used in **abnormal**
+situations).  In the above cases, the exchange signals to the
+wallets that the emergency cash back protocol has been activated
+by putting the affected denomination keys into the cash-back
+part of the /keys response.  If and only if this has happened,
+coins that were signed with those denomination keys can be cashed
+in using this API.
+
+   .. note::
+
+      This is a proposed API, we are implementing it as bug #3887.
+
+.. http:post:: /payback
+
+  Demand that a coin be refunded via wire transfer to the original owner.
+
+  **Request:** The request body must be a `PaybackRequest`_ object.
+
+  **Response:**
+  :status 200 OK:
+    The request was succesful, and the response is a `PaybackConfirmation`.
+    Note that repeating exactly the same request
+    will again yield the same response, so if the network goes down during the
+    transaction or before the client can commit the coin signature to disk, the
+    coin is not lost.
+  :status 401 Unauthorized: The coin's signature is invalid.
+  :status 403 Forbidden: The coin was already used for payment.
+    The response is a `DepositDoubleSpendError`_.
+  :status 404 Not Found:
+    The denomination key is not in the set of denomination
+    keys where emergency pay back is enabled.
+
+  **Details:**
+
+  .. _PaybackRequest:
+  .. code-block:: tsref
+
+    interface PaybackRequest {
+      // Denomination public key (RSA), specifying the type of coin the client
+      // would like the exchange to pay back.
+      denom_pub: RsaPublicKey;
+
+      // coin's public key
+      coin_pub: CoinPublicKey;
+
+      // coin's blinding factor
+      coin_blind_key_secret: RsaBlindingKeySecret;
+
+      // Signature of `TALER_PaybackRequestPS`_ created with the `coin's private key <coin-priv>`_
+      coin_sig: EddsaSignature;
+    }
+
+
+  .. _PaybackConfirmation:
+  .. code-block:: tsref
+
+    interface PaybackConfirmation {
+      // wire subject the exchange promises to use for the
+      // wire transfer of the funds;
+      wire_subject: String;
+
+      // How much will the exchange pay back (needed by wallet in
+      // case coin was partially spent and wallet got restored from backup)
+      amount: Amount;
+
+      // Time by which the exchange promises to wire the funds back.
+      payback_deadline: Timestamp;
+
+      // the EdDSA signature of `TALER_PaybackConfirmationPS`_ using a current
+      // `signing key of the exchange <sign-key-priv>`_ affirming the successful
+      // payback request, and that the exchange promises to transfer the funds
+      // by the date specified (this allows the exchange delaying the transfer
+      // a bit to aggregate additional payback requests into a larger one).
+      sig: EddsaSignature;
+    }
 
 
 -----------------------