spec message for denomination expired/revoked/too-early signature (#6889)

2 files changed, 77 insertions, 6 deletions

diff --git a/core/api-common.rst b/core/api-common.rst
index 97ce02d1..9c23b905 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -1038,6 +1038,20 @@ within the
   };
 
 
+.. _TALER_DenominationExpiredAffirmationPS:
+.. sourcecode:: c
+
+  struct TALER_DenominationExpiredAffirmationPS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_GENERIC_DENOMINATIN_EXPIRED
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_TIME_AbsoluteNBO timestamp;
+    char operation[8];
+    struct GNUNET_HashCode h_denom_pub;
+  };
+
+
 .. _TALER_ReserveCloseConfirmationPS:
 .. sourcecode:: c
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 8e41447a..ce482837 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1401,12 +1401,45 @@ exchange.
     The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
     The response is `WithdrawError` object.
   :http:statuscode:`410 Gone`:
-    The requested denomination key is no longer valid. It either expired or was revoked.
-  :http:statuscode:`412 Precondition failed`:
-    The requested denomination key is not yet valid. It is too early to withdraw.
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
 
   **Details:**
 
+  .. ts:def:: DenominationExpiredMessage
+
+    interface DenominationExpiredMessage {
+
+      // Taler error code.  Note that beyond
+      // expiration this message format is also
+      // used if the key is not yet valid, or
+      // has been revoked.
+      code: number;
+
+      // Signature by the exchange over a
+      // `TALER_DenominationExpiredAffirmationPS`.
+      // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
+      exchange_sig: EddsaSignature;
+
+      // Public key of the exchange used to create
+      // the 'exchange_sig.
+      exchange_pub: EddsaPublicKey;
+
+      // Hash of the denomination public key that is unknown.
+      h_denom_pub: HashCode;
+
+      // When was the signature created.
+      timestamp: Timestamp;
+
+      // What kind of operation was requested that now
+      // failed?
+      oper: String;
+    }
+
+
   .. ts:def:: WithdrawRequest
 
     interface WithdrawRequest {
@@ -1559,6 +1592,12 @@ denomination.
     The fields of the response are the same in both cases.
     The request should not be repeated again with this coin.
     In this case, the response is a `DepositDoubleSpendError`.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
 
   **Details:**
 
@@ -1993,6 +2032,12 @@ the API during normal operation.
     can be decided by looking at the error code
     (``TALER_EC_EXCHANGE_MELT_INSUFFICIENT_FUNDS`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
     The response is `MeltForbiddenResponse` in both cases.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
 
   **Details:**
 
@@ -2119,6 +2164,12 @@ the API during normal operation.
     rather verbose, as it includes most of the original /refresh/melt request,
     but of course expected to be primarily used for diagnostics.
     The response body is a `RevealConflictResponse`.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key (for the fresh coins) is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
 
   **Details:**
 
@@ -2263,8 +2314,7 @@ in using this API.
   :http:statuscode:`401 Unauthorized`:
     The coin's signature is invalid.
   :http:statuscode:`404 Not found`:
-    The denomination key is not in the set of denomination
-    keys where emergency pay back is enabled, or the blinded
+    The denomination key is unknown, or the blinded
     coin is not known to have been withdrawn.
     If the denomination key is unknown, the response will be
     a `DenominationUnkownMessage`.
@@ -2273,8 +2323,15 @@ in using this API.
     residual value, or because the same public key of the coin has been
     previously used with a different denomination.  Which case it is
     can be decided by looking at the error code
-    (``TALER_EC_EXCHANGE_RECOUP_COIN_BALANCE_ZERO`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    (``TALER_EC_EXCHANGE_RECOUP_COIN_BALANCE_ZERO`` or
+     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
     The response is a `DepositDoubleSpendError`.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was not yet revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
 
   **Details:**