summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-11-24 14:02:52 +0100
committerChristian Grothoff <christian@grothoff.org>2020-11-24 14:02:52 +0100
commitbca4ec6e3d2341763f3c59c05a76e677689ff402 (patch)
tree432ae4666b31491cdf2ba4d972f1d0dd3f637efc /core
parent540d059dba8b9ad6fb92c00c95e95c37d970ae40 (diff)
downloaddocs-bca4ec6e3d2341763f3c59c05a76e677689ff402.tar.gz
docs-bca4ec6e3d2341763f3c59c05a76e677689ff402.tar.bz2
docs-bca4ec6e3d2341763f3c59c05a76e677689ff402.zip
update exchange API spec for #6175
Diffstat (limited to 'core')
-rw-r--r--core/api-exchange.rst285
1 files changed, 282 insertions, 3 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:
-----------------------------------