From bca4ec6e3d2341763f3c59c05a76e677689ff402 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 24 Nov 2020 14:02:52 +0100 Subject: update exchange API spec for #6175 --- core/api-exchange.rst | 285 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 282 insertions(+), 3 deletions(-) (limited to 'core') 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: ----------------------------------- -- cgit v1.2.3