summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-05-15 13:29:53 +0200
committerChristian Grothoff <christian@grothoff.org>2021-05-15 13:29:53 +0200
commitb944ce40628194e9f77d769fab8c6004446c9e21 (patch)
treee19c58aa9a110e697756738d425af6fb6df4addb /core
parent9e4bbd6735d350f7b55bb30ee418309db01c8fa9 (diff)
downloaddocs-b944ce40628194e9f77d769fab8c6004446c9e21.tar.gz
docs-b944ce40628194e9f77d769fab8c6004446c9e21.tar.bz2
docs-b944ce40628194e9f77d769fab8c6004446c9e21.zip
misc spec fixes
Diffstat (limited to 'core')
-rw-r--r--core/api-common.rst148
-rw-r--r--core/api-exchange.rst101
2 files changed, 208 insertions, 41 deletions
diff --git a/core/api-common.rst b/core/api-common.rst
index bcb0570f..81b85ab9 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -500,6 +500,13 @@ uses 512-bit hash codes (64 bytes).
uint8_t hash[64]; // usually SHA-512
};
+.. _TALER_EcdhEphemeralPublicKeyP:
+.. sourcecode:: c
+
+ struct TALER_EcdhEphemeralPublicKeyP {
+ uint8_t ecdh_pub[32];
+ };
+
.. _reserve-pub:
.. sourcecode:: c
@@ -760,6 +767,9 @@ within the
struct TALER_ExchangePublicKeyP signkey_pub;
};
+.. _TALER_ExchangeKeySetPS:
+.. sourcecode:: c
+
struct TALER_ExchangeKeySetPS {
/**
* purpose.purpose = TALER_SIGNATURE_EXCHANGE_KEY_SET
@@ -1219,3 +1229,141 @@ within the
struct GNUNET_HashCode h_items;
struct TALER_WadId wad_id;
};
+
+.. _TALER_WadPartnerSignaturePS:
+.. sourcecode:: c
+
+ struct TALER_WadPartnerSignaturePS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_PARTNER_DETAILS
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_HashCode h_partner_base_url;
+ struct TALER_MasterPublicKeyP master_public_key;
+ struct GNUNET_TIME_AbsoluteNBO start_date;
+ struct GNUNET_TIME_AbsoluteNBO end_date;
+ struct TALER_AmountNBO wad_fee;
+ struct GNUNET_TIME_RelativeNBO wad_frequency;
+ };
+
+
+.. _TALER_P2PFeesPS:
+.. sourcecode:: c
+
+ struct TALER_P2PFeesPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_P2P_FEES
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO start_date;
+ struct GNUNET_TIME_AbsoluteNBO end_date;
+ struct TALER_AmountNBO kyc_fee;
+ struct TALER_AmountNBO purse_fee;
+ struct TALER_AmountNBO account_history_fee;
+ struct TALER_AmountNBO account_annual_fee;
+ struct GNUNET_TIME_RelativeNBO account_kyc_timeout;
+ struct GNUNET_TIME_RelativeNBO purse_timeout;
+ uint32_t purse_account_limit;
+ };
+
+
+.. _TALER_DenominationKeyAnnouncementPS:
+.. sourcecode:: c
+
+ struct TALER_DenominationKeyAnnouncementPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_SM_DENOMINATION_KEY
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_HashCode h_denom_pub;
+ struct GNUNET_HashCode h_section_name;
+ struct GNUNET_TIME_AbsoluteNBO anchor_time;
+ struct GNUNET_TIME_RelativeNBO duration_withdraw;
+ };
+
+
+.. _TALER_SigningKeyAnnouncementPS:
+.. sourcecode:: c
+
+ struct TALER_SigningKeyAnnouncementPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_SM_SIGNING_KEY .
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ struct GNUNET_TIME_AbsoluteNBO anchor_time;
+ struct GNUNET_TIME_RelativeNBO duration;
+ };
+
+.. _TALER_MasterDenominationKeyRevocationPS:
+.. sourcecode:: c
+
+ struct TALER_MasterDenominationKeyRevocationPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_HashCode h_denom_pub;
+ };
+
+
+.. _TALER_MasterSigningKeyRevocationPS:
+.. sourcecode:: c
+
+ struct TALER_MasterSigningKeyRevocationPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_REVOKED.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct TALER_ExchangePublicKeyP exchange_pub;
+ };
+
+
+.. _TALER_MasterAddAuditorPS:
+.. sourcecode:: c
+
+ struct TALER_MasterAddAuditorPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_AUDITOR
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO start_date;
+ struct TALER_AuditorPublicKeyP auditor_pub;
+ struct GNUNET_HashCode h_auditor_url;
+ };
+
+.. _TALER_MasterDelAuditorPS:
+.. sourcecode:: c
+
+ struct TALER_MasterDelAuditorPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_AUDITOR
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO end_date;
+ struct TALER_AuditorPublicKeyP auditor_pub;
+ };
+
+.. _TALER_MasterAddWirePS:
+.. sourcecode:: c
+
+ struct TALER_MasterAddWirePS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_WIRE.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO start_date;
+ struct GNUNET_HashCode h_wire GNUNET_PACKED;
+ };
+
+.. _TALER_MasterDelWirePS:
+.. sourcecode:: c
+
+ struct TALER_MasterDelWirePS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_WIRE.
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ struct GNUNET_TIME_AbsoluteNBO end_date;
+ struct GNUNET_HashCode h_wire GNUNET_PACKED;
+ };
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3f80d4d7..44dfd2a5 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -140,7 +140,7 @@ possibly by using HTTPS.
// Fees relevant for wallet-to-wallet (or peer-to-peer) payments.
// If no fees are provided for a given time range, then the
// exchange simply does not support purses/p2p-payments at that time.
- p2p_fees: P2Pfees[];
+ p2p_fees: P2PFees[];
// The date when the denomination keys were last updated.
list_issue_date: Timestamp;
@@ -160,6 +160,7 @@ possibly by using HTTPS.
// is sabotaging end-user anonymity by giving disjoint denomination keys to
// different users. If an exchange were to do this, this signature allows the
// clients to demonstrate to the public that the exchange is dishonest.
+ // Signature of `TALER_ExchangeKeySetPS`
eddsa_sig: EddsaSignature;
// Public EdDSA key of the exchange that was used to generate the signature.
@@ -197,10 +198,9 @@ possibly by using HTTPS.
// regulatory reasons.)
account_annual_fee: Amount;
- // How long will the exchange preserve the account
- // history? After an account was deleted/closed, the
- // exchange will retain the account history for
- // legal reasons until this time.
+ // How long will the exchange preserve the account history?
+ // After an account was deleted/closed, the exchange will
+ // retain the account history for legal reasons until this time.
legal_history_retention: RelativeTime;
// How long does the exchange promise to keep funds
@@ -217,13 +217,12 @@ possibly by using HTTPS.
// Non-negative number of concurrent purses that any
// account holder is allowed to create without having
// to pay the purse_fee.
- purse_account_limit: integer;
+ purse_account_limit: Integer;
- // How long does an exchange keep a purse around
- // after a purse has expired (or been successfully
- // merged)? A 'GET' request for a purse will
- // succeed until the purse expiration time plus this
- // value.
+ // How long does an exchange keep a purse around after a purse
+ // has expired (or been successfully merged)? A 'GET' request
+ // for a purse will succeed until the purse expiration time
+ // plus this value.
purse_timeout: RelativeTime;
// Signature of `TALER_P2PFeesPS`.
@@ -308,6 +307,7 @@ possibly by using HTTPS.
stamp_end: Timestamp;
// Signature over ``key`` and ``stamp_expire`` by the exchange master key.
+ // Signature of `TALER_ExchangeSigningKeyValidityPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
master_sig: EddsaSignature;
}
@@ -453,7 +453,8 @@ possibly by using HTTPS.
// How long is this partnership expected to last?
end_date: Timestamp;
- // Signature using the exchange's offline key
+ // Signature using the exchange's offline key over
+ // `TALER_WadPartnerSignaturePS`
// with purpose ``TALER_SIGNATURE_MASTER_PARTNER_DETAILS``.
master_sig: EddsaSignature;
}
@@ -542,7 +543,10 @@ Management operations authorized by master key
// Fee charged by the exchange for refunding a coin of this denomination.
fee_refund: Amount;
- // Signature over this denomination by the denomination security module.
+ // Signature by the denomination security module
+ // over `TALER_DenominationKeyAnnouncementPS`
+ // for this denomination with purpose
+ // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
denom_secmod_sig: EddsaSignature;
}
@@ -564,7 +568,9 @@ Management operations authorized by master key
// henceforth no longer be considered valid in legal disputes.
stamp_end: Timestamp;
- // Signature over this signing key by the signkey security module.
+ // Signature over `TALER_SigningKeyAnnouncementPS`
+ // for this signing key by the signkey security
+ // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
signkey_secmod_sig: EddsaSignature;
}
@@ -607,7 +613,8 @@ Management operations authorized by master key
// Hash of the public (RSA) key of the denomination.
h_denom_pub: HashCode;
- // Signature of `TALER_DenominationKeyValidityPS`.
+ // Signature over `TALER_DenominationKeyValidityPS`.
+ // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY``
master_sig: EddsaSignature;
}
@@ -618,7 +625,8 @@ Management operations authorized by master key
// The actual exchange's EdDSA signing public key.
key: EddsaPublicKey;
- // Signature by the exchange master key.
+ // Signature by the exchange master key over
+ // `TALER_ExchangeSigningKeyValidityPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
master_sig: EddsaSignature;
@@ -646,7 +654,8 @@ Management operations authorized by master key
interface DenomRevocationSignature {
- // Signature by the exchange master key.
+ // Signature by the exchange master key over a
+ // `TALER_MasterDenominationKeyRevocationPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``.
master_sig: EddsaSignature;
@@ -673,7 +682,8 @@ Management operations authorized by master key
interface SignkeyRevocationSignature {
- // Signature by the exchange master key.
+ // Signature by the exchange master key over a
+ // `TALER_MasterSigningKeyRevocationPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_SIGN_KEY_REVOKED``.
master_sig: EddsaSignature;
@@ -712,8 +722,9 @@ Management operations authorized by master key
// The auditor's EdDSA signing public key.
auditor_pub: EddsaPublicKey;
- // Signature by the exchange master key.
- // Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_ADD``.
+ // Signature by the exchange master ke yover a
+ // `TALER_MasterAddAuditorPS`.
+ // Must have purpose ``TALER_SIGNATURE_MASTER_ADD_AUDITOR``.
master_sig: EddsaSignature;
// When does the auditor become active?
@@ -756,7 +767,8 @@ Management operations authorized by master key
interface AuditorTeardownMessage {
- // Signature by the exchange master key.
+ // Signature by the exchange master key over a
+ // `TALER_MasterDelAuditorPS`.
// Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_DEL``.
master_sig: EddsaSignature;
@@ -849,7 +861,8 @@ Management operations authorized by master key
// with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``.
master_sig_wire: EddsaSignature;
- // Signature using the exchange's offline key
+ // Signature using the exchange's offline key over a
+ // `TALER_MasterAddWirePS`
// with purpose ``TALER_SIGNATURE_MASTER_WIRE_ADD``.
master_sig_add: EddsaSignature;
@@ -896,7 +909,8 @@ Management operations authorized by master key
// ``payto://`` URL identifying the account and wire method
payto_uri: string;
- // Signature using the exchange's offline key
+ // Signature using the exchange's offline key over a
+ // `TALER_MasterDelWirePS`.
// with purpose ``TALER_SIGNATURE_MASTER_WIRE_DEL``.
master_sig_del: EddsaSignature;
@@ -1063,7 +1077,7 @@ exchange.
}
- .. ts:def:: AccountSetupTransaction
+ .. ts:def:: AccountSetupTransaction
interface AccountSetupTransaction {
type: "SETUP";
@@ -1374,7 +1388,7 @@ exchange.
The account is unknown to the exchange.
:http:statuscode:`409 Conflict`:
The account is still has digital cash in it, the associated
- wire method is ``void'' and the *force* option was not provided.
+ wire method is ``void`` and the *force* option was not provided.
This response comes with a standard `ErrorDetail` response.
**Details:**
@@ -2477,7 +2491,7 @@ Wallet-to-wallet transfers
purse_expiration: Timestamp;
// Indicative time at which the exchange is answering the
- // status request. Used as part of `exchange_sig`.
+ // status request. Used as part of 'exchange_sig'.
status_timestamp: Timestamp;
// Maximum deposit fees that can be charged under the contract.
@@ -2489,13 +2503,13 @@ Wallet-to-wallet transfers
// EdDSA signature of the exchange affirming the purse status.
exchange_sig: EddsaSignature;
- // EdDSA public key exchange used for exchange_sig.
+ // EdDSA public key exchange used for 'exchange_sig'.
exchange_pub: EddsaPublicKey;
// AES-GCM Encrypted contract terms using encryption
// key derived from DH of 'contract_pub' and the 'purse_pub'.
// Optional, may be omitted if not desired by the client.
- e_contract_terms?: byte[];
+ e_contract_terms?: string;
// If a merge request was received, information about the
// merge request. Omitted if the purse has not yet received
@@ -2583,23 +2597,27 @@ Wallet-to-wallet transfers
deposits: PurseDeposit[];
}
- .. ts:def:: EncryptedContract {
+ .. ts:def:: EncryptedContract
+
+ interface EncryptedContract {
// ECDH contract_public key used to encrypt the contract.
// Optional as the contract terms may already be known
// to the exchange or the other wallet from a different
// interaction.
- contract_pub: EcdhPublicKey;
+ contract_pub: TALER_EcdhEphemeralPublicKeyP;
// AES-GCM Encrypted contract terms using encryption
- // key derived from DH of 'contract_pub' and the 'purse_pub'.
+ // key derived from DH of ``contract_pub`` and the ``purse_pub``.
// Optional as the contract terms may already be known
// to the exchange or the other wallet from a different
// interaction.
- e_contract_terms: byte[];
- }
+ e_contract_terms: string;
+ }
- .. ts:def:: PurseDeposit {
+ .. ts:def:: PurseDeposit
+
+ interface PurseDeposit {
// Public key of the coin being deposited into the purse.
coin_pub: EddsaPublicKey;
@@ -2614,7 +2632,8 @@ Wallet-to-wallet transfers
// Exchange's unblinded RSA signature of the coin.
ub_sig: RsaSignature;
- // Signature of `TALER_PurseDepositRequestPS`,
+ // Signature over `TALER_PurseDepositSignaturePS`
+ // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``
// made by the customer with the
// `coin's private key <coin-priv>`.
coin_sig: EddsaSignature;
@@ -2810,7 +2829,7 @@ Wallet-to-wallet transfers
// The number of remaining purses that can still be opened
// under the given account.
- remaining_purses: integer;
+ remaining_purses: Integer;
}
@@ -2835,7 +2854,7 @@ Wallet-to-wallet transfers
:http:statuscode:`200 Ok`:
The operation succeeded, the exchange confirms that the account
can now be used.
- The response will be an `AccountStatus` object.
+ The response will be an `AccountKycStatus` object.
:http:statuscode:`202 Accepted`:
The user should be redirected to the provided location to perform
the required KYC checks to open the account. Afterwards, the
@@ -2890,7 +2909,7 @@ Wallet-to-wallet transfers
exchange_pub: EddsaPublicKey;
}
- .. ts:def:: AccountKycRedirect
+ .. ts:def:: AccountKycRedirect
interface AccountKycRedirect {
@@ -2946,13 +2965,13 @@ wallet-to-wallet payments. Only another exchange should access this endpoint.
items: WadItem[];
// EdDSA signature of the exchange affirming the wad
- // data is correct, must be of purpose
- // TALER_SIGNATURE_WAD_DATA.
+ // data is correct, must be over `TALER_WadDataSignaturePS`
+ // and of purpose ``TALER_SIGNATURE_WAD_DATA``.
exchange_sig: EddsaSignature;
// public key used to create the signature.
exchange_pub: EddsaPublicKey;
- }
+ }
Objects in the wad item list have the following format: