[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: update exchange API spec for #6175
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: update exchange API spec for #6175 |
Date: |
Tue, 24 Nov 2020 14:02:55 +0100 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new bca4ec6 update exchange API spec for #6175
bca4ec6 is described below
commit bca4ec6e3d2341763f3c59c05a76e677689ff402
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Nov 24 14:02:52 2020 +0100
update exchange API spec for #6175
---
core/api-exchange.rst | 285 +++++++++++++++++++++++++++++++++++++++++++++-
taler-exchange-manual.rst | 6 +-
2 files changed, 285 insertions(+), 6 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:
-----------------------------------
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 74118a7..0b03821 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -540,7 +540,7 @@ The generated file will be echoed by the exchange when
serving
.. _Wire-fee-structure:
Wire fee structure
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
.. index:: wire fee
.. index:: fee
@@ -705,7 +705,7 @@ exchange, and includes HTML, PDF and TXT files. If other
files are
present, the exchange may show a warning on startup.
Example
-~~~~~~~
+^^^^^^^
A sample file structure for a TERMS_ETAG of "v1" would be:
@@ -897,7 +897,7 @@ GNUNET_CRYPTO_rsa_private_key_decode().
.. _Revocations:
Revocations
-~~~~~~~~~~~
+^^^^^^^^^^^
When an exchange goes out of business or detects that the private key of
a denomination key pair has been compromised, it may revoke some or all
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: update exchange API spec for #6175,
gnunet <=