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-common.rst | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ core/api-exchange.rst | 101 ++++++++++++++++++++-------------- 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_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