diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 305 |
1 files changed, 199 insertions, 106 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 3a35637b..55909161 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -26,19 +26,12 @@ defines all specific terms used in this section. .. _keys: ------------------------ -Obtaining Exchange Keys ------------------------ +-------------------- +Terms of service API +-------------------- -This API is used by wallets and merchants to obtain global information about -the exchange, such as online signing keys, available denominations and the fee -structure. This is typically the first call any exchange client makes, as it -returns information required to process all of the other interactions with the -exchange. The returned information is secured by (1) signature(s) from the exchange, -especially the long-term offline signing key of the exchange, which clients should -cache; (2) signature(s) from auditors, and the auditor keys should be -hard-coded into the wallet as they are the trust anchors for Taler; (3) -possibly by using HTTPS. +These APIs allow merchants and wallets to obtian the terms of service +and the privacy policy of an exchange. .. http:get:: /terms @@ -76,15 +69,31 @@ possibly by using HTTPS. If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the privacy policy was not configured correctly. +--------------------------- +Exchange status information +--------------------------- + +This API is used by wallets and merchants to obtain global information about +the exchange, such as online signing keys, available denominations and the fee +structure. This is typically the first call any exchange client makes, as it +returns information required to process all of the other interactions with the +exchange. The returned information is secured by (1) signature(s) from the exchange, +especially the long-term offline signing key of the exchange, which clients should +cache; (2) signature(s) from auditors, and the auditor keys should be +hard-coded into the wallet as they are the trust anchors for Taler; (3) +possibly by using HTTPS. + + .. http:get:: /seed Return an entropy seed. The exchange will return a high-entropy value that will differ for every call. The response is NOT in JSON, but simply high-entropy binary data in the HTTP body. - This API can be used by wallets to guard themselves against + This API should be used by wallets to guard themselves against running on low-entropy (bad PRNG) hardware. Naturally, the entropy returned MUST be mixed with locally generated entropy. + .. http:get:: /keys Get a list of all denomination keys offered by the exchange, @@ -276,11 +285,85 @@ 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 ------------------------------------- +.. _wire-req: + +.. http:get:: /wire + + Returns a list of payment methods supported by the exchange. The idea is that wallets may use this information to instruct users on how to perform wire transfers to top up their wallets. + + **Response:** + + :http:statuscode:`200 Ok`: + The exchange responds with a `WireResponse` object. This request should virtually always be successful. + + **Details:** + + .. ts:def:: WireResponse + + interface WireResponse { + + // Master public key of the exchange, must match the key returned in /keys. + master_public_key: EddsaPublicKey; + + // Array of wire accounts operated by the exchange for + // incoming wire transfers. + accounts: WireAccount[]; + + // Object mapping names of wire methods (i.e. "sepa" or "x-taler-bank") + // to wire fees. + fees: { method : AggregateTransferFee }; + } + + The specification for the account object is: + + .. ts:def:: WireAccount + + interface WireAccount { + // payto:// URL identifying the account and wire method + url: string; + + // Salt value (used when hashing 'url' to verify signature) + salt: string; + + // Signature using the exchange's offline key + // with purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS. + master_sig: EddsaSignature; + } + + Aggregate wire transfer fees representing the fees the exchange + charges per wire transfer to a merchant must be specified as an + array in all wire transfer response objects under ``fees``. The + respective array contains objects with the following members: + + .. ts:def:: AggregateTransferFee + + interface AggregateTransferFee { + // Per transfer wire transfer fee. + wire_fee: Amount; + + // Per transfer closing fee. + closing_fee: Amount; + + // What date (inclusive) does this fee go into effect? + // The different fees must cover the full time period in which + // any of the denomination keys are valid without overlap. + start_date: Timestamp; + + // What date (exclusive) does this fee stop going into effect? + // The different fees must cover the full time period in which + // any of the denomination keys are valid without overlap. + end_date: Timestamp; -.. http:get:: /keys/future + // Signature of `TALER_MasterWireFeePS` with purpose TALER_SIGNATURE_MASTER_WIRE_FEES + sig: EddsaSignature; + } + + +---------------------------------------------- +Management operations authorized by master key +---------------------------------------------- + +.. http:get:: /management/keys 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 @@ -362,7 +445,7 @@ Providing signatures for future keys } -.. http:post:: /keys/future +.. http:post:: /management/keys 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 @@ -415,12 +498,8 @@ Providing signatures for future keys } -------------------- -Setting up auditors -------------------- - -.. http:post:: /auditors +.. http:post:: /management/auditors This request will be used to enable an auditor. @@ -463,10 +542,14 @@ Setting up auditors } -.. http:delete:: /auditors/$AUDITOR_PUB +.. http:post:: /management/auditors/disable - This request will be used to disable - the use of the given auditor. + This request will be used to disable the use of the given auditor. + We use POST instead of DELETE because the exchange will retain state + about the auditor (specifically the end date) to prevent replay + attacks abusing the `AuditorSetupMessage`. Also, DELETE would not + support a body, which is needed to provide the signature authorizing + the operation. **Request:** @@ -507,131 +590,141 @@ Setting up auditors } ---------------- -Auditor actions ---------------- +.. http:post:: /management/wire-methods -.. _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. + This request will be used to enable a wire method (exchange bank account). **Request:** - The request must be a `AuditorSignatureAddMessage`. + The request must be a `WireSetupMessage`. **Response:** :http:statuscode:`204 No content`: - The backend has successfully stored the auditor signature. + The wire method was successfully enabled. :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. + The master signature is invalid. + :http:statuscode:`409 Conflict`: + The exchange has a more recent request related to this wire method (replay detected). - .. ts:def:: AuditorSignatureAddMessage + **Details:** - interface AuditorSignatureAddMessage { + .. ts:def:: WireSetupMessage - // The auditor's EdDSA signing public key. - auditor_pub: EddsaPublicKey; + interface WireSetupMessage { - // Signature by the auditor. - // Must have purpose TALER_SIGNATURE_AUDITOR_XXX. - auditor_sig: EddsaSignature; + // payto:// URL identifying the account and wire method + url: string; - // What denomination is the signature for? - h_denom_pub: HashCode; + // Salt value (used when hashing 'url' to verify signature) + salt: string; - } + // Signature using the exchange's offline key + // with purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS. + master_sig: EddsaSignature; + // When does the wire method 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 wire method will + // become active immediately! Used ONLY to detect replay attacks. + validity_start: Timestamp; + } -.. _wire-req: +.. http:post:: /management/wire-methods/disable ------------------------------------ -Obtaining wire-transfer information ------------------------------------ + This request will be used to disable the use of the given wire method. + We use POST instead of DELETE because the exchange will retain state + about the wire method (specifically the end date) to prevent replay + attacks abusing the `WireSetupMessage`. Also, DELETE would not + support a body, which is needed to provide the signature authorizing + the operation. -.. http:get:: /wire + **Request:** - Returns a list of payment methods supported by the exchange. The idea is that wallets may use this information to instruct users on how to perform wire transfers to top up their wallets. + The request must be a `WireTeardownMessage`. - **Response:** + **Response** - :http:statuscode:`200 Ok`: - The exchange responds with a `WireResponse` object. This request should virtually always be successful. + :http:statuscode:`204 No content`: + The auditor has successfully disabled the wire method. The body is empty. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`404 Not found`: + The wire method is unknown to the exchange. + :http:statuscode:`409 Conflict`: + The exchange has a more recent request related to this wire method (replay detected). **Details:** - .. ts:def:: WireResponse + .. ts:def:: WireTeardownMessage - interface WireResponse { + interface WireTeardownMessage { - // Master public key of the exchange, must match the key returned in /keys. - master_public_key: EddsaPublicKey; + // payto:// URL identifying the account and wire method + url: string; - // Array of wire accounts operated by the exchange for - // incoming wire transfers. - accounts: WireAccount[]; + // Signature using the exchange's offline key + // with purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS. + master_sig: EddsaSignature; + + // 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 wire method will + // become inactive immediately! Used ONLY to detect replay attacks. + validity_end: Timestamp; - // Object mapping names of wire methods (i.e. "sepa" or "x-taler-bank") - // to wire fees. - fees: { method : AggregateTransferFee }; } - The specification for the account object is: - .. ts:def:: WireAccount +--------------- +Auditor actions +--------------- - interface WireAccount { - // payto:// URL identifying the account and wire method - url: string; +.. _auditor_action: - // Salt value (used when hashing 'url' to verify signature) - salt: string; +This part of the API is for the use by auditors interacting with the exchange. - // Signature using the exchange's offline key - // with purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS. - master_sig: EddsaSignature; - } - Aggregate wire transfer fees representing the fees the exchange - charges per wire transfer to a merchant must be specified as an - array in all wire transfer response objects under ``fees``. The - respective array contains objects with the following members: +.. http:post:: /auditors/$AUDITOR_PUB/$H_DENOM_PUB - .. ts:def:: AggregateTransferFee + This is used to add an auditor signature to the ``/keys`` response. It + affirms to wallets and merchants that this auditor is indeed auditing + the coins issued by the respective denomination. There is no "delete" + operation for this, as auditors can only stop auditing a denomination + when it expires. - interface AggregateTransferFee { - // Per transfer wire transfer fee. - wire_fee: Amount; + **Request:** - // Per transfer closing fee. - closing_fee: Amount; + The request must be a `AuditorSignatureAddMessage`. - // What date (inclusive) does this fee go into effect? - // The different fees must cover the full time period in which - // any of the denomination keys are valid without overlap. - start_date: Timestamp; + **Response:** - // What date (exclusive) does this fee stop going into effect? - // The different fees must cover the full time period in which - // any of the denomination keys are valid without overlap. - end_date: Timestamp; + :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 { + + // Signature by the auditor. + // Must have purpose TALER_SIGNATURE_AUDITOR_XXX. + auditor_sig: EddsaSignature; - // Signature of `TALER_MasterWireFeePS` with purpose TALER_SIGNATURE_MASTER_WIRE_FEES - sig: EddsaSignature; } + ---------- Withdrawal ---------- |