From d267f23fc695a99d95cbcffc4d35602ccef5c563 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 15 May 2021 16:05:52 +0200 Subject: more work on DD13 spec --- core/api-exchange.rst | 256 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 183 insertions(+), 73 deletions(-) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 44dfd2a5..089890af 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -398,7 +398,8 @@ possibly by using HTTPS. // ``payto://`` URI 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_MasterWireDetailsPS` // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. master_sig: EddsaSignature; } @@ -858,6 +859,7 @@ Management operations authorized by master key payto_uri: string; // Signature using the exchange's offline key + // over a `TALER_MasterWireDetailsPS` // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. master_sig_wire: EddsaSignature; @@ -964,8 +966,9 @@ This part of the API is for the use by auditors interacting with the exchange. interface AuditorSignatureAddMessage { - // Signature by the auditor. - // Must have purpose ``TALER_SIGNATURE_AUDITOR_XXX``. + // Signature by the auditor over a + // `TALER_ExchangeKeyValidityPS`. + // Must have purpose ``TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS``. auditor_sig: EddsaSignature; } @@ -1022,8 +1025,9 @@ exchange. .. ts:def:: ReserveStatusRequest interface ReserveStatusRequest { - // Signature of type - // TALER_SIGNATURE_RESERVE_STATUS_REQUEST + // Signature of purpose + // ``TALER_SIGNATURE_RESERVE_STATUS_REQUEST`` over + // a `TALER_ReserveStatusRequestSignaturePS`. reserve_sig: EddsaSignature; } @@ -1072,7 +1076,8 @@ exchange. request_timestamp: Timestamp; // Signature created with the reserve's private key. - // Must be of purpose TALER_SIGNATURE_RESERVE_HISTORY_REQUEST. + // Must be of purpose ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` over + // a `TALER_ReserveHistoryRequestSignaturePS`. reserve_sig: EddsaSignature; } @@ -1096,7 +1101,8 @@ exchange. h_wire: HashCode; // Signature created with the reserve's private key. - // Must be of purpose TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST. + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over + // a `TALER_AccountSetupRequestSignaturePS`. reserve_sig: EddsaSignature; } @@ -1125,12 +1131,17 @@ exchange. // Hash of the contract. h_contract: HashCode; + // Hash of the wire details of the reserve. + h_wire: HashCode; + // Signature created with the reserve's private key. - // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE. + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` over + // a `TALER_AccountMergeSignaturePS`. reserve_sig: EddsaSignature; // Signature created with the purse's private key. - // Must be of purpose TALER_SIGNATURE_PURSE_MERGE. + // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE`` + // over a `TALER_PurseMergeSignaturePS`. purse_sig: EddsaSignature; // Deposit fees that were charged to the purse. @@ -1151,8 +1162,9 @@ exchange. // Hash of the blinded coin to be signed. h_coin_envelope: HashCode; - // Signature of ``TALER_WithdrawRequestPS`` created with the reserve's - // private key. + // Signature over a `TALER_WithdrawRequestPS` + // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW`` + // created with the reserve's private key. reserve_sig: EddsaSignature; // Fee that is charged for withdraw. @@ -1198,11 +1210,11 @@ exchange. receiver_account_details: string; // This is a signature over a - // struct ``TALER_ReserveCloseConfirmationPS`` with purpose + // struct `TALER_ReserveCloseConfirmationPS` with purpose // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. exchange_sig: EddsaSignature; - // Public key used to create ``exchange_sig``. + // Public key used to create 'exchange_sig'. exchange_pub: EddsaPublicKey; // Time when the reserve was closed. @@ -1219,11 +1231,11 @@ exchange. amount: Amount; // This is a signature over - // a struct ``TALER_PaybackConfirmationPS`` with purpose - // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK``. + // a struct `TALER_RecoupConfirmationPS` with purpose + // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``. exchange_sig: EddsaSignature; - // Public key used to create ``exchange_sig``. + // Public key used to create 'exchange_sig'. exchange_pub: EddsaPublicKey; // Time when the funds were paid back into the reserve. @@ -1262,7 +1274,8 @@ exchange. interface ReserveHistoryRequest { // Signature of type - // TALER_SIGNATURE_RESERVE_HISTORY_REQUEST + // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` + // over a `TALER_ReserveHistoryRequestSignaturePS`. reserve_sig: EddsaSignature; // Time when the client made the request. @@ -1332,7 +1345,8 @@ exchange. coin_ev: CoinEnvelope; // Signature of `TALER_WithdrawRequestPS` created with - // the `reserves's private key `. + // the `reserves's private key ` + // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW``. reserve_sig: EddsaSignature; } @@ -1340,7 +1354,7 @@ exchange. .. ts:def:: WithdrawResponse interface WithdrawResponse { - // The blinded RSA signature over the ``coin_ev``, affirms the coin's + // The blinded RSA signature over the 'coin_ev', affirms the coin's // validity after unblinding. ev_sig: BlindedRsaSignature; @@ -1363,6 +1377,8 @@ exchange. history: TransactionHistoryItem[] } +.. _delete-reserve: + .. http:DELETE:: /reserves/$RESERVE_PUB Forcefully closes a reserve. @@ -1432,7 +1448,6 @@ credited an amount specified in the deposit permission, possibly a fraction of the total coin's value, minus the deposit fee as specified by the coin's denomination. - .. _deposit: .. http:POST:: /coins/$COIN_PUB/deposit @@ -1445,10 +1460,9 @@ denomination. exchange. The exchange MUST return a 307 or 308 redirection to the correct base URL if this is the case. - The request should contain a JSON object with the - following fields: + **Request:** - **Request:** The request body must be a `DepositRequest` object. + The request body must be a `DepositRequest` object. **Response:** @@ -1516,7 +1530,7 @@ denomination. // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; - // Signature of `TALER_DepositRequestPS`, made by the customer with the + // Signature over `TALER_DepositRequestPS`, made by the customer with the // `coin's private key `. coin_sig: EddsaSignature; } @@ -1604,14 +1618,16 @@ denomination. // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; - // Signature by the coin. + // Signature over `TALER_DepositRequestPS`, made by the customer with the + // `coin's private key `. coin_sig: EddsaSignature; // Hash of the bank account from where we received the funds. h_wire: HashCode; // Hash of the public denomination key used to sign the coin. - // FIXME: why do we care to have this? + // Needed because 'coin_sig' signs over this, and + // that is important to fix the coin's denomination. h_denom_pub: HashCode; // Hash over the proposal data of the contract that @@ -1631,7 +1647,9 @@ denomination. // subtracting the amounts. amount: Amount; - // Signature by the coin. + // Signature by the coin over a + // `TALER_RefreshMeltCoinAffirmationPS` of + // purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``. coin_sig: EddsaSignature; // Melt fee. @@ -1641,7 +1659,8 @@ denomination. rc: TALER_RefreshCommitmentP; // Hash of the public denomination key used to sign the coin. - // FIXME: why do we care to have this? + // Needed because 'coin_sig' signs over this, and + // that is important to fix the coin's denomination. h_denom_pub: HashCode; } @@ -1658,7 +1677,7 @@ denomination. // adding the amounts to the coin's denomination value. amount: Amount; - // Refund fee in case of type "REFUND". + // Refund fee. refund_fee: Amount; // Hash over the proposal data of the contract that @@ -1668,7 +1687,9 @@ denomination. // Refund transaction ID. rtransaction_id: Integer; - // `EdDSA Signature ` authorizing the REFUND. Made with + // `EdDSA Signature ` authorizing the REFUND over a + // `TALER_MerchantRefundConfirmationPS` with + // purpose ``TALER_SIGNATURE_MERCHANT_REFUND_OK``. Made with // the `public key of the merchant `. merchant_sig: EddsaSignature; @@ -1689,11 +1710,14 @@ denomination. // Date when the operation was made. timestamp: Timestamp; - // Signature by the coin. + // Signature by the coin over a + // `TALER_RecoupRequestPS` with purpose + // ``TALER_SIGNATURE_WALLET_COIN_RECOUP``. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. - // FIXME: why do we care to have this? + // Needed because 'coin_sig' signs over this, and + // that is important to fix the coin's denomination. h_denom_pub: HashCode; // Coin blinding key. @@ -1702,11 +1726,12 @@ denomination. // Reserve receiving the recoup. reserve_pub: EddsaPublicKey; - // Signature by the exchange, must be - // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP. + // Signature by the exchange over a + // `TALER_RecoupConfirmationPS`, must be + // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``. exchange_sig: EddsaSignature; - // Public key used to sign ``exchange_sig`` + // Public key of the private key used to create 'exchange_sig'. exchange_pub: EddsaPublicKey; } @@ -1725,11 +1750,12 @@ denomination. // Date when the operation was made. timestamp: Timestamp; - // Signature by the exchange - // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH. + // Signature by the exchange over a + // `TALER_RecoupRefreshConfirmationPS` + // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``. exchange_sig: EddsaSignature; - // Public key used to sign ``exchange_sig``, + // Public key of the private key used to create 'exchange_sig'. exchange_pub: EddsaPublicKey; } @@ -1749,21 +1775,24 @@ denomination. // Date when the operation was made. timestamp: Timestamp; - // Signature by the coin. + // Signature by the coin over a `TALER_RecoupRequestPS` + // with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP``. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. - // FIXME: why do we care to have this? + // Needed because 'coin_sig' signs over this, and + // that is important to fix the coin's denomination. h_denom_pub: HashCode; // Coin blinding key. coin_blind: DenominationBlindingKeyP; - // Signature by the exchange - // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH. + // Signature by the exchange over a + // `TALER_RecoupRefreshConfirmationPS` + // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``. exchange_sig: EddsaSignature; - // Public key used to sign ``exchange_sig``, + // Public key used to sign 'exchange_sig'. exchange_pub: EddsaPublicKey; // Blinding factor of the revoked new coin. @@ -1795,11 +1824,14 @@ denomination. // Date when the purse was set to expire. purse_expiration: Timestamp; - // Signature by the coin. + // Signature by the coin over a + // `TALER_PurseDepositSignaturePS` of + // purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. - // FIXME: why do we care to have this? + // Needed because 'coin_sig' signs over this, and + // that is important to fix the coin's denomination. h_denom_pub: HashCode; } @@ -2167,6 +2199,7 @@ in using this API. interface RecoupWithdrawalConfirmation { // Tag to distinguish the `RecoupConfirmation` response type. refreshed: false; + // Public key of the reserve that will receive the recoup. reserve_pub: EddsaPublicKey; } @@ -2176,6 +2209,7 @@ in using this API. interface RecoupRefreshConfirmation { // Tag to distinguish the `RecoupConfirmation` response type. refreshed: true; + // Public key of the old coin that will receive the recoup. old_coin_pub: EddsaPublicKey; } @@ -2250,7 +2284,8 @@ typically also view the balance.) deposits: TrackTransferDetail[]; // Signature from the exchange made with purpose - // `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT`. + // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT`` + // over a `TALER_WireDepositDataPS`. exchange_sig: EddsaSignature; // Public EdDSA key of the exchange that was used to generate the signature. @@ -2286,7 +2321,7 @@ typically also view the balance.) **Request:** - :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION``, affirming that it is really the merchant who requires obtaining the wire transfer identifier. + :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a `TALER_DepositTrackPS`, affirming that it is really the merchant who requires obtaining the wire transfer identifier. **Response:** @@ -2320,7 +2355,8 @@ typically also view the balance.) // Total amount transferred. total_amount: Amount; - // Binary-only Signature_ for purpose `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE` + // Binary-only Signature_ with purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE`` + // over a `TALER_ConfirmWirePS` // whereby the exchange affirms the successful wire transfer. exchange_sig: EddsaSignature; @@ -2392,7 +2428,10 @@ Refunds // EdDSA public key of the merchant. merchant_pub: EddsaPublicKey; - // EdDSA signature of the merchant affirming the refund. + // EdDSA signature of the merchant over a + // `TALER_RefundRequestPS` with purpose + // ``TALER_SIGNATURE_MERCHANT_REFUND`` + // affirming the refund. merchant_sig: EddsaPublicKey; } @@ -2402,7 +2441,9 @@ Refunds interface RefundSuccess { // The EdDSA :ref:`signature` (binary-only) with purpose - // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the + // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over + // a `TALER_RecoupRefreshConfirmationPS` + // using a current signing key of the // exchange affirming the successful refund. exchange_sig: EddsaSignature; @@ -2500,7 +2541,10 @@ Wallet-to-wallet transfers // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; - // EdDSA signature of the exchange affirming the purse status. + // EdDSA signature of the exchange over a + // `TALER_PurseStatusResponseSignaturePS` + // with purpose ``TALER_SIGNATURE_PURSE_STATUS_RESPONSE`` + // affirming the purse status. exchange_sig: EddsaSignature; // EdDSA public key exchange used for 'exchange_sig'. @@ -2523,7 +2567,9 @@ Wallet-to-wallet transfers Deposit money into a purse. Endpoint used by the buyer. - **Request:** The request body must be a `PurseRequest` object. + **Request:** + + The request body must be a `PurseRequest` object. **Response:** @@ -2557,6 +2603,11 @@ Wallet-to-wallet transfers In this case, the response is a `PurseDepositDoubleSpendError`. If the value of all successful coins is below the purse fee, the exchange may not setup the purse at all. + :http:statuscode:`425 Too Early`: + This response type is used if the given purse expiration time + is too far in the future (at least from the perspective + of the exchange). Thus, retrying at a later time may + succeed. The client should look at the ``Date:`` header of the response to see if a minor time difference is to blame and possibly adjust the request accordingly. **Details:** @@ -2565,7 +2616,10 @@ Wallet-to-wallet transfers interface PurseRequest { - // EdDSA signature of the purse confirming the key + // EdDSA signature of the purse over a + // `TALER_PurseRequestSignaturePS` + // of purpose ``TALER_SIGNATURE_PURSE_REQUEST`` + // confirming the key // invariants associated with the purse. // (amount, h_contract_terms, expiration). purse_sig: EddsaSignature; @@ -2651,7 +2705,8 @@ Wallet-to-wallet transfers total_deposit_fees: Amount; // EdDSA signature of the exchange affirming the payment, - // of purpose TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED + // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED`` + // over a `TALER_PurseDepositConfirmedSignaturePS`. // Signs over the above and the purse public key and // the hash of the contract terms. exchange_sig: EddsaSignature; @@ -2676,22 +2731,68 @@ Wallet-to-wallet transfers .. ts:def:: PurseConflict - interface PurseConflict { + // Union discriminated by the "type" field. + type PurseConflict = + | PurseMergeConflict + | PurseRequestConflict; - // Total amount to be paid into the purse as per - // the previous request. - total_purse_amount: Amount; + .. ts:def:: PurseMergeConflict + + interface PurseMergeConflict { + type: "MERGE"; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; + // Hash of the wire details of the reserve. + h_wire: HashCode; + + // Reserve merging the purse. + reserve_pub: EddsaPublicKey; + // Indicative time by which the purse should expire // if it has not been merged into an account. At this // point, all of the deposits made should be // auto-refunded. purse_expiration: Timestamp; - // EdDSA signature of the purse confirming that the + // When was the merge request generated. + merge_timestamp: Timestamp; + + // Total amount to be merged into the reserve. + // (excludes fees). + purse_value_after_fees: Amount; + + // EdDSA signature of the purse over + // `TALER_PurseMergeSignaturePS` of + // purpose ``TALER_SIGNATURE_PURSE_MERGE`` + // confirming that the + // above details hold for this purse. + purse_sig: EddsaSignature; + } + + .. ts:def:: PurseRequestConflict + + interface PurseRequestConflict { + type: "REQUEST"; + + // SHA-512 hash of the contact of the purse. + h_contract_terms: HashCode; + + // Indicative time by which the purse should expire + // if it has not been merged into an account. At this + // point, all of the deposits made should be + // auto-refunded. + purse_expiration: Timestamp; + + // Total amount to be paid into the purse as per + // the previous request. + total_purse_amount: Amount; + + // EdDSA signature of the purse over + // `TALER_PurseRequestSignaturePS` of + // purpose ``TALER_SIGNATURE_PURSE_REQUEST`` + // confirming that the // above details hold for this purse. purse_sig: EddsaSignature; @@ -2723,7 +2824,9 @@ Wallet-to-wallet transfers Merge purse with account, adding the value of the purse into the account. Endpoint to be used by the seller. - **Request:** The request body must be a `MergeRequest` object. + **Request:** + + The request body must be a `MergeRequest` object. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds to receive payment before @@ -2764,15 +2867,17 @@ Wallet-to-wallet transfers interface MergeRequest { // payto://-URI of the account the purse is to be merged into. - // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB". + // Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'. payto_uri: string; - // EdDSA signature of the account/reserve affirming the merge. - // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE + // EdDSA signature of the account/reserve affirming the merge + // over a `TALER_AccountMergeSignaturePS`. + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` reserve_sig: EddsaSignature; - // EdDSA signature of the purse private key affirming the merge. - // Must be of purpose TALER_SIGNATURE_PURSE_MERGE. + // EdDSA signature of the purse private key affirming the merge + // over a `TALER_PurseMergeSignaturePS`. + // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. purse_sig: EddsaSignature; // Minimum amount that must be credited to the reserve, that is @@ -2814,7 +2919,8 @@ Wallet-to-wallet transfers contract_time: Timestamp; // EdDSA signature of the exchange affirming the merge of - // purpose TALER_SIGNATURE_PURSE_MERGE_SUCCESS. + // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS`` + // over `TALER_PurseMergeSuccessSignaturePS`. // Signs over the above and the account public key. exchange_sig: EddsaSignature; @@ -2877,17 +2983,18 @@ Wallet-to-wallet transfers kyc_timestamp: Timestamp; // Bank account to be associated with the account. - // Can be ``payto://void/`` to not associate the + // Can be 'payto://void/' to not associate the // account with any bank account. In this case, // closing the account will result in the balance // being forfeit. If the provided wire method is - // not supported by the exchange *and* not ``void``, + // not supported by the exchange *and* not 'void', // this is a ``Bad Request`` (HTTP status 400). payto_uri: string; // EdDSA signature of the reserve affirming the request // to create the account, must be of purpose - // TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST + // ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` + // and over `TALER_AccountSetupRequestSignaturePS`. reserve_sig: EddsaPublicKey; } @@ -2902,7 +3009,8 @@ Wallet-to-wallet transfers // EdDSA signature of the exchange affirming the account // is KYC'ed, must be of purpose - // TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS. + // ``TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS`` + // and over `TALER_AccountSetupRequestSignaturePS`. exchange_sig: EddsaSignature; // public key used to create the signature. @@ -2983,7 +3091,7 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. amount: Amount; // payto://-URI of the account the purse is to be merged into. - // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB". + // Must be of the form: 'payto://taler/EXCHANGE_URL/RESERVE_PUB'. payto_uri: string; // Purse public key. @@ -3000,11 +3108,13 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. merge_timestamp: Timestamp; // Signature created with the reserve's private key. - // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` + // and over `TALER_AccountMergeSignaturePS`. reserve_sig: EddsaSignature; // Signature created with the purse's private key. - // Must be of purpose TALER_SIGNATURE_PURSE_MERGE + // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE`` + // and over `TALER_PurseMergeSignaturePS`. purse_sig: EddsaSignature; // Deposit fees that were charged to the purse. -- cgit v1.2.3