From b944ce40628194e9f77d769fab8c6004446c9e21 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 15 May 2021 13:29:53 +0200 Subject: misc spec fixes --- core/api-exchange.rst | 101 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 41 deletions(-) (limited to 'core/api-exchange.rst') 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_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: -- cgit v1.2.3