From 293b3d55d8cd6cf946bb4e86bfe8ef743156838b Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 30 Mar 2020 15:05:45 +0530 Subject: document protocol version ranges --- core/api-common.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) (limited to 'core/api-common.rst') diff --git a/core/api-common.rst b/core/api-common.rst index 44d4eb00..5fafacb9 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -121,6 +121,59 @@ handle the error as if an internal error (500) had been returned. type_actual?: string; } +----------------------- +Protocol Version Ranges +----------------------- + +Some of the Taler services (e.g. exchange, merchant, bank integration API) +expose the range of API versions they support. Clients in turn have an API +version range they support. These version ranges are written down in the +`libtool version format `__. + +A protocol version is a positive, non-zero integer. A protocol version range consists of three components: + +1. The ``current`` version. This is the latest version of the protocol supported by the client or service. +2. The ``revision`` number. This value is not to be interpreted by the client/server, but serves + purely as a comment. Each time a service/client for a protocol is updated while supporting the same + set of protocol versions, the revision should be increased. +3. The ``age`` number. This non-zero integer identifies with how many previous protocol versions this + implementation is compatible. An ``age`` of 0 implies that the implementation only supports + the ``current`` protocol version. The ``age`` must be less or equal than the ``current`` protocol version. + +To avoid confusion with semantic versions, the protocol version range is written down in the following format: + +.. code:: none + + current[:revision[:age]] + +The angle brackets mark optional components. If either ``revision`` or ``age`` are omitted, they default to 0. + +Examples: + +* "1" and "1" are compatible +* "1" and "2" are **incompatible** +* "2:0:1" and "1:0:0" are compatible +* "2:5:1" and "1:10:0" are compatible +* "4:0:1" and "2:0:0" are **incompatible** +* "4:0:1" and "3:0:0" are compatible + +.. note:: + + `Semantic versions `__ are not a good tool for this job, as we concisely want to express + that the client/server supports the last ``n`` versions of the protocol. + Semantic versions don't support this, and semantic version ranges are too complex for this. + +.. warning:: + + A client doesn't have one single protocol version range. Instead, it has + a protocol version range for each type of service it talks to. + +.. warning:: + + For privacy reasons, the protocol version range of a client should not be + sent to the service. Instead, the client should just use the two version ranges + to decide whether it will talk to the service. + .. _encodings-ref: -- cgit v1.2.3 From ba934cc1ef9158bf0178f6d722bab2eb911583a5 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 30 Mar 2020 15:58:52 +0530 Subject: integrate Christian's idea about 'revision' field --- core/api-common.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'core/api-common.rst') diff --git a/core/api-common.rst b/core/api-common.rst index 5fafacb9..1721c42f 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -133,9 +133,11 @@ version range they support. These version ranges are written down in the A protocol version is a positive, non-zero integer. A protocol version range consists of three components: 1. The ``current`` version. This is the latest version of the protocol supported by the client or service. -2. The ``revision`` number. This value is not to be interpreted by the client/server, but serves +2. The ``revision`` number. This value should usually not be interpreted by the client/server, but serves purely as a comment. Each time a service/client for a protocol is updated while supporting the same set of protocol versions, the revision should be increased. + In rare cases, the revision number can be used to work around unintended breakage in deployed + versions of a service. This is discouraged and should only be used in exceptional situations. 3. The ``age`` number. This non-zero integer identifies with how many previous protocol versions this implementation is compatible. An ``age`` of 0 implies that the implementation only supports the ``current`` protocol version. The ``age`` must be less or equal than the ``current`` protocol version. -- cgit v1.2.3 From 7b96e3e9b0334c1e6d143bf92697bd0c0ea1a6b2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 20 Apr 2020 21:34:17 +0200 Subject: fix rst --- core/api-common.rst | 14 ++++- core/api-merchant.rst | 145 ++++++++++++++++++++++++++------------------------ 2 files changed, 89 insertions(+), 70 deletions(-) (limited to 'core/api-common.rst') diff --git a/core/api-common.rst b/core/api-common.rst index 1721c42f..294e33d5 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -549,10 +549,22 @@ uses 512-bit hash codes (64 bytes). uint8_t eddsa_priv[32]; }; - struct TALER_MasterSignatureP { + struct TALER_MasterSignatureP { uint8_t eddsa_signature[64]; }; +.. _WireTransferIdentifierRawP: + + struct WireTransferIdentifierRawP { + uint8_t raw[32]; + }; + +.. _UUID: + + struct UUID { + uint32_t value[4]; + }; + .. _eddsa-coin-pub: .. sourcecode:: c diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 3583e209..002dc976 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -29,8 +29,9 @@ API, which is NOT yet implemented at all! TODO: https://bugs.gnunet.org/view.php?id=5987#c15127 is not yet addressed by this specification! -The ``*/public/*`` endpoints are publicly exposed on the Internet and accessed -both by the user's browser and their wallet. +The ``*/private/*`` endpoints are only supposed to be exposed +to the merchant internally, and must not be exposed on the +Internet. Most endpoints given here can be prefixed by a base URL that includes the specific instance selected (BASE_URL/instances/$INSTANCE/). If @@ -43,7 +44,7 @@ specific instance selected (BASE_URL/instances/$INSTANCE/). If Getting the configuration ------------------------- -.. http:get:: /public/config +.. http:get:: /config Return the protocol version and currency supported by this merchant backend. @@ -71,7 +72,7 @@ Dynamic Merchant Instances -------------------------- .. _instances: -.. http:get:: /instances +.. http:get:: /private/instances This is used to return the list of all the merchant instances @@ -112,7 +113,7 @@ Dynamic Merchant Instances } -.. http:post:: /instances +.. http:post:: /private/instances This request will be used to create a new merchant instance in the backend. @@ -155,7 +156,7 @@ Dynamic Merchant Instances // Default factor for wire fee amortization calculations. // Can be overriden by the frontend on a per-order basis. - default_wire_fee_amortization: integer; + default_wire_fee_amortization: Integer; // Maximum deposit fee (sum over all coins) this instance is willing to pay. // Can be overridden by the frontend on a per-order basis. @@ -174,7 +175,7 @@ Dynamic Merchant Instances } -.. http:patch:: /instances/$INSTANCE +.. http:patch:: /private/instances/$INSTANCE Update the configuration of a merchant instance. @@ -215,7 +216,7 @@ Dynamic Merchant Instances // Default factor for wire fee amortization calculations. // Can be overriden by the frontend on a per-order basis. - default_wire_fee_amortization: integer; + default_wire_fee_amortization: Integer; // Maximum deposit fee (sum over all coins) this instance is willing to pay. // Can be overridden by the frontend on a per-order basis. @@ -234,7 +235,7 @@ Dynamic Merchant Instances } -.. http:get:: /instances/$INSTANCE +.. http:get:: /private/instances/$INSTANCE This is used to query a specific merchant instance. @@ -270,7 +271,7 @@ Dynamic Merchant Instances // Default factor for wire fee amortization calculations. // Can be overriden by the frontend on a per-order basis. - default_wire_fee_amortization: integer; + default_wire_fee_amortization: Integer; // Maximum deposit fee (sum over all coins) this instance is willing to pay. // Can be overridden by the frontend on a per-order basis. @@ -308,7 +309,7 @@ Dynamic Merchant Instances -.. http:delete:: /instances/$INSTANCE +.. http:delete:: /private/instances/$INSTANCE This request will be used to delete (permanently disable) or purge merchant instance in the backend. Purging will @@ -323,7 +324,7 @@ Dynamic Merchant Instances **Response** - :status 204 NoContent: + :status 204 No content: The backend has successfully removed the instance. The response is a `PostInstanceRemoveResponse`. :status 404 Not found: @@ -348,7 +349,7 @@ Taler merchant backend to process payments *without* using its inventory management. -.. http:get:: /products +.. http:get:: /private/products This is used to return the list of all items in the inventory. @@ -373,16 +374,10 @@ management. // Product identifier, as found in the product. product_id: string; - // Amount of the product in stock. Given in product-specific units. - // Set to -1 for "infinite" (i.e. for "electronic" books). - stock: integer; - - // unit in which the product is metered (liters, kilograms, packages, etc.) - unit: string; } -.. http:get:: /products/$PRODUCT_ID +.. http:get:: /private/products/$PRODUCT_ID This is used to obtain detailed information about a product in the inventory. @@ -422,24 +417,24 @@ management. // including all existing sales ever. Given in product-specific // units. // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stocked: integer; + total_stocked: Integer; // Number of units of the product that have already been sold. - total_sold: integer; + total_sold: Integer; // Number of units of the product that were lost (spoiled, stolen, etc.) - total_lost: integer; + total_lost: Integer; // Identifies where the product is in stock. address: Location; // Identifies when we expect the next restocking to happen. - next_restock?: timestamp; + next_restock?: Timestamp; } -.. http:post:: /products +.. http:post:: /private/products This is used to add a product to the inventory. @@ -488,19 +483,19 @@ management. // including all existing sales ever. Given in product-specific // units. // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stocked: integer; + total_stocked: Integer; // Identifies where the product is in stock. address: Location; // Identifies when we expect the next restocking to happen. - next_restock?: timestamp; + next_restock?: Timestamp; } -.. http:patch:: /products/$PRODUCT_ID +.. http:patch:: /private/products/$PRODUCT_ID This is used to update product details in the inventory. Note that the ``total_stocked`` and ``total_lost`` numbers MUST be greater or equal than @@ -522,6 +517,7 @@ management. :status 204 No content: The backend has successfully expanded the inventory. + .. ts:def:: ProductPatchDetail interface ProductPatchDetail { @@ -552,22 +548,22 @@ management. // including all existing sales ever. Given in product-specific // units. // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stocked: integer; + total_stocked: Integer; // Number of units of the product that were lost (spoiled, stolen, etc.) - total_lost: integer; + total_lost: Integer; // Identifies where the product is in stock. address: Location; // Identifies when we expect the next restocking to happen. - next_restock?: timestamp; + next_restock?: Timestamp; } -.. http:post:: /products/$PRODUCT_ID/lock +.. http:post:: /private/products/$PRODUCT_ID/lock This is used to lock a certain quantity of the product for a limited duration while the customer assembles a complete order. Note that @@ -606,15 +602,15 @@ management. lock_uuid: UUID; // How long does the frontend intend to hold the lock - duration: time; + duration: RelativeTime; // How many units should be locked? - quantity: integer; + quantity: Integer; } -.. http:delete:: /products/$PRODUCT_ID +.. http:delete:: /private/products/$PRODUCT_ID Delete information about a product. Fails if the product is locked by anyone. @@ -635,7 +631,7 @@ Receiving Payments .. _post-order: -.. http:post:: /orders +.. http:post:: /private/orders Create a new order that a customer can pay for. @@ -646,7 +642,7 @@ Receiving Payments .. note:: This endpoint does not return a URL to redirect your user to confirm the - payment. In order to get this URL use :http:get:`/orders/$ORDER_ID`. The + payment. In order to get this URL use :http:get:/orders/$ORDER_ID. The API is structured this way since the payment redirect URL is not unique for every order, there might be varying parameters such as the session id. @@ -698,6 +694,8 @@ Receiving Payments } + .. ts:def:: Order + type Order : MinimalOrderDetail | ContractTerms; The following fields must be specified in the ``order`` field of the request. Other fields from @@ -739,7 +737,7 @@ Receiving Payments product_id: string; // How many units of the product are requested - quantity: integer; + quantity: Integer; } @@ -758,24 +756,26 @@ Receiving Payments missing_products: OutOfStockEntry; } + .. ts:def:: OutOfStockEntry + interface OutOfStockEntry { // Product ID of an out-of-stock item product_id: string; // Requested quantity - requested_quantity: integer; + requested_quantity: Integer; // Available quantity (must be below ``requested_quanitity``) - available_quantity: integer; + available_quantity: Integer; // When do we expect the product to be again in stock? // Optional, not given if unknown. - restock_expected?: timestamp; + restock_expected?: Timestamp; } -.. http:get:: /orders +.. http:get:: /private/orders Returns known orders up to some point in the past. @@ -833,7 +833,7 @@ Receiving Payments -.. http:post:: /public/orders/$ORDER_ID/claim +.. http:post:: /orders/$ORDER_ID/claim Wallet claims ownership (via nonce) over an order. By claiming an order, the wallet obtains the full contract terms, and thereby @@ -856,14 +856,14 @@ Receiving Payments :status 200 OK: The client has successfully claimed the order. - The response contains the :ref:`contract terms `. + The response contains the :ref:`contract terms `. :status 404 Not found: The backend is unaware of the instance or order. :status 409 Conflict: The someone else claimed the same order ID with different nonce before. -.. http:post:: /public/orders/$ORDER_ID/pay +.. http:post:: /orders/$ORDER_ID/pay Pay for an order by giving a deposit permission for coins. Typically used by the customer's wallet. Note that this request does not include the @@ -947,7 +947,7 @@ Receiving Payments } -.. http:post:: /public/orders/$ORDER_ID/abort +.. http:post:: /orders/$ORDER_ID/abort Abort paying for an order and obtain a refund for coins that were already deposited as part of a failed payment. @@ -995,6 +995,8 @@ Receiving Payments coins: AbortedCoin[]; } + .. ts:def:: AbortedCoin + interface AbortedCoin { // Public key of a coin for which the wallet is requesting an abort-related refund. coin_pub: EddsaPublicKey; @@ -1002,7 +1004,7 @@ Receiving Payments -.. http:get:: /orders/$ORDER_ID/ +.. http:get:: /private/orders/$ORDER_ID/ Merchant checks the payment status of an order. If the order exists but is not payed yet, the response provides a redirect URL. When the user goes to this URL, @@ -1115,7 +1117,7 @@ Receiving Payments } -.. http:get:: /public/orders/$ORDER_ID/ +.. http:get:: /orders/$ORDER_ID/ Query the payment status of an order. This endpoint is for the wallet. When the wallet goes to this URL and it is unpaid, @@ -1165,7 +1167,7 @@ Receiving Payments } -.. http:delete:: /orders/$ORDER_ID +.. http:delete:: /private/orders/$ORDER_ID Delete information about an order. Fails if the order was paid in the last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was @@ -1181,12 +1183,13 @@ Receiving Payments The backend refuses to delete the order. +.. _refund: + -------------- Giving Refunds -------------- -.. _refund: -.. http:post:: /orders/$ORDER_ID/refund +.. http:post:: /private/orders/$ORDER_ID/refund Increase the refund amount associated with a given order. The user should be redirected to the ``taler_refund_url`` to trigger refund processing in the wallet. @@ -1230,7 +1233,7 @@ Giving Refunds Tracking Wire Transfers ------------------------ -.. http:post:: /transfers +.. http:post:: /private/transfers Inform the backend over an incoming wire transfer. The backend should inquire about the details with the exchange and mark the respective orders as wired. Note that the request will fail if the WTID is not unique (which should be guaranteed by a correct exchange). This request is idempotent and should also be used to merely re-fetch the @@ -1361,7 +1364,7 @@ Tracking Wire Transfers } - .. ts:def:: TrackTransferProof + .. ts:def:: TrackTransferProof interface TrackTransferProof { // signature from the exchange made with purpose @@ -1381,7 +1384,7 @@ Tracking Wire Transfers -.. http:get:: /transfers +.. http:get:: /private/transfers Obtain a list of all wire transfers the backend has checked. @@ -1406,6 +1409,8 @@ Tracking Wire Transfers transfers : TransferDetails[]; } + .. ts:def:: TransferDetails + interface TransferDetails { // how much was wired to the merchant (minus fees) credit_amount: Amount; @@ -1441,7 +1446,7 @@ Giving Customer Tips -------------------- .. _tips: -.. http:post:: /reserves +.. http:post:: /private/reserves Create a reserve for tipping. @@ -1460,7 +1465,7 @@ Giving Customer Tips :status 200 OK: The backend is waiting for the reserve to be established. The merchant must now perform the wire transfer indicated in the `ReserveCreateConfirmation`. - :status 424 Failed Depencency: + :status 424 Failed Dependency: We could not obtain /wire details from the specified exchange base URL. .. ts:def:: ReserveCreateRequest @@ -1485,7 +1490,7 @@ Giving Customer Tips } -.. http:get:: /reserves +.. http:get:: /private/reserves Obtain list of reserves that have been created for tipping. @@ -1541,7 +1546,7 @@ Giving Customer Tips } -.. http:get:: /reserves/$RESERVE_PUB +.. http:get:: /private/reserves/$RESERVE_PUB Obtain information about a specific reserve that have been created for tipping. @@ -1604,12 +1609,12 @@ Giving Customer Tips total_amount: Amount; // Human-readable reason for why the tip was granted. - reason: String; + reason: string; } -.. http:post:: /reserves/$RESERVE_PUB/authorize-tip +.. http:post:: /private/reserves/$RESERVE_PUB/authorize-tip Authorize creation of a tip from the given reserve. @@ -1658,7 +1663,7 @@ Giving Customer Tips } -.. http:post:: /tips +.. http:post:: /private/tips Authorize creation of a tip from the given reserve, except with automatic selection of a working reserve of the instance by the @@ -1680,7 +1685,7 @@ Giving Customer Tips in all of the reserves of the instance. -.. http:delete:: /reserves/$RESERVE_PUB +.. http:delete:: /private/reserves/$RESERVE_PUB Delete information about a reserve. Fails if the reserve still has committed to tips that were not yet picked up and that have not yet @@ -1703,7 +1708,7 @@ Giving Customer Tips -.. http:get:: /tips/$TIP_ID +.. http:get:: /private/tips/$TIP_ID Obtain information about a particular tip. @@ -1729,7 +1734,7 @@ Giving Customer Tips total_picked_up: Amount; // Human-readable reason given when authorizing the tip. - reason: String; + reason: string; // Timestamp indicating when the tip is set to expire (may be in the past). expiration: Timestamp; @@ -1750,7 +1755,7 @@ Giving Customer Tips pickup_id: HashCode; // Number of planchets involved. - num_planchets: integer; + num_planchets: Integer; // Total amount requested for this pickup_id. requested_amount: Amount; @@ -1761,7 +1766,7 @@ Giving Customer Tips } -.. http:post:: /public/tips/$TIP_ID/pickup +.. http:post:: /tips/$TIP_ID/pickup Handle request from wallet to pick up a tip. @@ -1812,10 +1817,12 @@ Giving Customer Tips blind_sigs: BlindSignature[]; } + .. ts:def:: BlindSignature + interface BlindSignature { // The (blind) RSA signature. Still needs to be unblinded. - blind_sig: RsaSignature; + blind_sig: BlindedRsaSignature; } @@ -1826,7 +1833,7 @@ Giving Customer Tips The Contract Terms ------------------ -.. _contract_terms:: +.. _contract-terms: The contract terms must have the following structure: @@ -1968,7 +1975,7 @@ The contract terms must have the following structure: description_i18n?: { [lang_tag: string]: string }; // The number of units of the product to deliver to the customer. - quantity: integer; + quantity: Integer; // The unit in which the product is measured (liters, kilograms, packages, etc.) unit: string; -- cgit v1.2.3 From 6a9c36ad28f4316d3acea7b9fd3044b0e707461a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 23 Apr 2020 16:34:27 +0530 Subject: syntax fix --- core/api-common.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'core/api-common.rst') diff --git a/core/api-common.rst b/core/api-common.rst index 294e33d5..93d6d09e 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -554,12 +554,14 @@ uses 512-bit hash codes (64 bytes). }; .. _WireTransferIdentifierRawP: +.. sourcecode:: c struct WireTransferIdentifierRawP { uint8_t raw[32]; }; .. _UUID: +.. sourcecode:: c struct UUID { uint32_t value[4]; -- cgit v1.2.3 From 5d3aef5d035c1a78c930b44d19485396d190e09e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 23 Jun 2020 23:12:59 +0200 Subject: fix RST warnings --- anastasis.rst | 29 ++++++++++++++--------------- core/api-common.rst | 8 ++++++++ core/api-exchange.rst | 3 ++- core/api-merchant.rst | 37 ++++++++++++++++++------------------- core/api-sync.rst | 4 +++- developers-manual.rst | 31 ++++++++++++++++++------------- taler-auditor-manual.rst | 22 +++++++++++----------- taler-merchant-manual.rst | 6 +----- taler-nfc-guide.rst | 13 ++++++------- 9 files changed, 81 insertions(+), 72 deletions(-) (limited to 'core/api-common.rst') diff --git a/anastasis.rst b/anastasis.rst index c27b66df..d0012c7a 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -255,16 +255,16 @@ individual **key share**, we use different salts ("erd" and "eks" respectively). (iv_i, key_i) = HKDF(key_id, nonce_i, "eks", [optional data], keysize + ivsize) (encrypted_key_share_i, aes_gcm_tag_i) = AES256_GCM(key_share_i, key_i, iv_i) -**encrypted_recovery_document**: The encrypted **recovery document** which contains the escrow methods, policies +**encrypted_recovery_document**: The encrypted **recovery document** which contains the escrow methods, policies and the encrypted **core secret**. -**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used for the encryption of the *recovery document*. +**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used for the encryption of the *recovery document*. Nonce must contain the string "ERD". **optional data**: Key material that optionally is contributed from the authentication method to further obfuscate the key share from the escrow provider. -**encrypted_key_share_i**: The encrypted **key_share** which the escrow provider must release upon successful authentication. -Here, **i** must be a positive number used to iterate over the various **key shares** used for the various **escrow methods** +**encrypted_key_share_i**: The encrypted **key_share** which the escrow provider must release upon successful authentication. +Here, **i** must be a positive number used to iterate over the various **key shares** used for the various **escrow methods** at the various providers. **nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used for the encryption of the *key share*. **i** must be @@ -356,7 +356,7 @@ Obtain salt **Response:** Returns a `SaltResponse`_. - + .. _SaltResponse: .. ts:def:: SaltResponse @@ -509,7 +509,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. Upload a new version of the customer's encrypted recovery document. While the document's structure is described in JSON below, the upload should just be the bytestream of the raw data (i.e. 32 bytes nonce followed - by 16 bytes tag followed by the encrypted document). + by 16 bytes tag followed by the encrypted document). If request has been seen before, the server should do nothing, and otherwise store the new version. The body must begin with a nonce, an AES-GCM tag and continue with the ciphertext. The format is the same as specified for the response of the GET method. The @@ -644,8 +644,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. } -.. _manage-truth: - +.. _Truth: Managing truth ^^^^^^^^^^^^^^ @@ -692,7 +691,7 @@ charge per truth operation using GNU Taler. // Contains the information of an interface `EncryptedKeyShare`, but simply // as one binary block (in Crockford Base32 encoding for JSON). key_share_data: []; //bytearray - + // Key share method, i.e. "security question", "SMS", "e-mail", ... method: string; @@ -720,7 +719,7 @@ charge per truth operation using GNU Taler. .. http:get:: /truth/$UUID[?response=$RESPONSE] Get the stored encrypted key share. If $RESPONSE is specified by the client, the server checks - if $RESPONSE matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth). + if $RESPONSE matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth). Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). When $RESPONSE is correct, the server responses with the encrypted key share. The encrypted key share is returned simply as a byte array and not in JSON format. @@ -768,7 +767,7 @@ charge per truth operation using GNU Taler. // // HKDF for the key generation must include the // string "eks" as salt. - // Depending on the method, + // Depending on the method, // the HKDF may additionally include // bits from the response (i.e. some hash over the // answer to the security question) @@ -811,10 +810,10 @@ FIXME: details! Video identification (vid) ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Requires the user to identify via video-call. The user is expected to delete all metadata revealing -information about him/her from the images before uploading them. Since the respective images must -be passed on to the video identification service in the event of password recovery, it must be -ensured that no further information about the user can be derived from them. +Requires the user to identify via video-call. The user is expected to delete all metadata revealing +information about him/her from the images before uploading them. Since the respective images must +be passed on to the video identification service in the event of password recovery, it must be +ensured that no further information about the user can be derived from them. FIXME: details! diff --git a/core/api-common.rst b/core/api-common.rst index 93d6d09e..272dfd6c 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -267,6 +267,14 @@ Integers // JavaScript numbers restricted to integers type Integer = number; +Objects +^^^^^^^ + +.. ts:def:: Object + + // JavaScript objects, no further restrictions + type Object = object; + Keys ^^^^ diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 979eca86..9b18a18d 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1330,11 +1330,12 @@ typically also view the balance.) } +.. _exchange_refund: + ------- Refunds ------- -.. _refund: .. http:POST:: /coins/$COIN_PUB/refund Undo deposit of the given coin, restoring its value. diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 1c99a79e..5c50709a 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -325,8 +325,7 @@ Dynamic Merchant Instances **Response** :status 204 No content: - The backend has successfully removed the instance. The response is a - `PostInstanceRemoveResponse`. + The backend has successfully removed the instance. The body is empty. :status 404 Not found: The instance is unknown to the backend. :status 409 Conflict: @@ -991,7 +990,7 @@ Payment processing The backend will return an `abort response `, which includes verbatim the error codes received from the exchange's - :ref:`refund <_refund>` API. The frontend should pass the replies verbatim to + :ref:`refund ` API. The frontend should pass the replies verbatim to the browser/wallet. .. ts:def:: AbortRequest @@ -1038,12 +1037,12 @@ Payment processing // can generate a substantially shorter response. interface RefundResult { // HTTP status of the request to the exchange. - exchange_http_status: integer; + exchange_http_status: Integer; // The full reply from the exchange. Note only actually - // a if the `exchange_status` is 200, otherwise + // a if the \exchange_http_status\ is 200, otherwise // the error message as defined by the refund API. For - // aborts, the `rtransaction_id` is always 0. + // aborts, the \rtransaction_id\ is always 0. exchange_reply: RefundSuccess; } @@ -1278,7 +1277,7 @@ Payment processing exchange_code?: Integer; // If available, HTTP reply from the exchange. - exchange_reply?: json; + exchange_reply?: Object; // Refund transaction ID. rtransaction_id: Integer; @@ -1299,8 +1298,8 @@ Payment processing // to the wallet and thus not included. interface RefundConfirmation { - // HTTP status of the exchange request, 200 required for refund confirmations. - exchange_status: 200; + // HTTP status of the exchange request, 200 (integer) required for refund confirmations. + exchange_status: "200"; // the EdDSA :ref:`signature` (binary-only) with purpose // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the @@ -1342,7 +1341,7 @@ Payment processing The backend refuses to delete the order. -.. _refund: +.. _merchant_refund: -------------- Giving Refunds @@ -1502,7 +1501,7 @@ Tracking Wire Transfers // and should probably return it here as well. interface WireFeeConflictDetails { // Numerical `error code `: - code: TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE; + code: "TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE"; // Text describing the issue for humans. hint: string; @@ -1540,7 +1539,7 @@ Tracking Wire Transfers interface TrackTransferConflictDetails { // Numerical `error code ` - code: TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS; + code: "TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS"; // Text describing the issue for humans. hint: string; @@ -1558,15 +1557,15 @@ Tracking Wire Transfers // hardly needed _here_. Once we add automated reports for // the Taler auditor, we need to generate this data anyway // and should probably return it here as well. - exchange_transfer: TrackTransferResponse?; + exchange_transfer?: TrackTransferResponse; // Public key of the exchange used to sign the response to // our deposit request. - deposit_exchange_pub: EdDSAPublicKey; + deposit_exchange_pub: EddsaPublicKey; // Signature of the exchange signing the (conflicting) response. - // Signs over a `struct TALER_DepositConfirmationPS`. - deposit_exchange_sig: EdDSASignature; + // Signs over a \struct TALER_DepositConfirmationPS\. + deposit_exchange_sig: EddsaSignature; // Hash of the merchant's bank account the wire transfer went to h_wire: HashCode; @@ -1575,10 +1574,10 @@ Tracking Wire Transfers h_contract_terms: HashCode; // At what time the exchange received the deposit. Needed - // to verify the `exchange_sig`. + // to verify the \exchange_sig\. deposit_timestamp: Timestamp; - // At what time the refund possibility expired (needed to verify ``exchange_sig``). + // At what time the refund possibility expired (needed to verify \exchange_sig\). refund_deadline: Timestamp; // Public key of the coin for which we have conflicting information. @@ -1717,7 +1716,7 @@ Giving Customer Tips :status 200 OK: The backend is waiting for the reserve to be established. The merchant must now perform the wire transfer indicated in the `ReserveCreateConfirmation`. - :status 408 Timeout: + :status 408 Request Timeout: The exchange did not respond on time. :status 409 Conflict: The exchange does not support the requested wire method. diff --git a/core/api-sync.rst b/core/api-sync.rst index 2add73ef..67d1e214 100644 --- a/core/api-sync.rst +++ b/core/api-sync.rst @@ -411,4 +411,6 @@ Web Security Considerations To ensure that the Taler Web extension (and others) can access the service despite Web "security", all service endpoints must set the -"Access-Control-Allow-Origin: *". +header:: + + Access-Control-Allow-Origin: * diff --git a/developers-manual.rst b/developers-manual.rst index 8c3a3501..6e0bc309 100644 --- a/developers-manual.rst +++ b/developers-manual.rst @@ -28,7 +28,7 @@ Developer's Manual .. note:: - This manual contains information for developers working on GNU Taler + This manual contains information for developers working on GNU Taler and related components. It is not intended for a general audience. .. contents:: Table of Contents @@ -636,13 +636,13 @@ About Privilege Levels This is the breakdown of privilege levels in Weblate: -* **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) + * **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) -* **Reviewers** = Can contribute Translations to existing *Components* + * **Reviewers** = Can contribute Translations to existing *Components* -* **Managers** = Can create new *Components* of existing *Projects* + * **Managers** = Can create new *Components* of existing *Projects* -* **Superusers** = Can create new *Projects* + * **Superusers** = Can create new *Projects* Upgrading Privileges -------------------- @@ -661,20 +661,25 @@ Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#compone In Weblate, a *Component* is a subset of a *Project* and each Component contains N translations. A Component is generally associated with a Git repo. -To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add* from the upper-right corner. +To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add** from the upper-right corner. What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository: Under *https://weblate.taler.net/create/component/vcs/*: -* **Source code repository** - Generally ``git+ssh://git@git.taler.net/```. Check with ``git remote -v``. -* **Repository branch** - Choose the correct branch to draw from and commit to. -* **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/``` Check with ``git remote -v``. -* **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ```` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. -* **Merge style** - *Rebase*, in line with GNU Taler development procedures + * **Source code repository** - Generally ``git+ssh://git@git.taler.net/```. Check with ``git remote -v``. -* **Translation license** - *GNU General Public License v3.0 or Later* -* **Adding new translation** - Decide how to handle adding new translations + * **Repository branch** - Choose the correct branch to draw from and commit to. + + * **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/``` Check with ``git remote -v``. + + * **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ```` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. + + * **Merge style** - *Rebase*, in line with GNU Taler development procedures + + * **Translation license** - *GNU General Public License v3.0 or Later* + + * **Adding new translation** - Decide how to handle adding new translations How to Create a Translation --------------------------- diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index f5cca273..97ba2a5d 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -263,7 +263,7 @@ Taler components. See for example the exchange manual for details on the configuration and the ``taler-config`` configuration tool. This section discusses configuration options related to the auditor. -.. _Keys: +.. _AuditorKeys: Keys ---- @@ -275,7 +275,7 @@ The following values are to be configured in the section [auditor]: - AUDITOR_PRIV_FILE: Path to the auditor’s private key file. -.. _Serving: +.. _AuditorServing: Serving ------- @@ -296,7 +296,7 @@ The following values are to be configured in the section [auditor]: for the unixpath (i.e. 660 = rw-rw—-). -.. _Bank-account: +.. _AuditorBank-account: Bank account ------------ @@ -305,7 +305,7 @@ Bank accounts for the auditor are configured in exactly the same way as bank accounts for the exchange. See the exchange documentation for details. -.. _Database: +.. _AuditorDatabaseConfiguration: Database -------- @@ -338,7 +338,7 @@ tables. After running this tool, the rights to CREATE or DROP tables are no longer required and should be removed. -.. _Deployment: +.. _AuditorDeployment: Deployment ========== @@ -356,7 +356,7 @@ Web page offering the respective pairing. FIXME: explain how that Web page works! -.. _Exchange: +.. _AuditorExchange: Exchange -------- @@ -375,7 +375,7 @@ master public key. taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL -.. _Denominations: +.. _AuditorDenominations: Denominations ------------- @@ -417,7 +417,7 @@ response will contain an entry in the ``auditors`` array mentioning the auditor’s URL. -.. _Database: +.. _AuditorDatabaseInitialization: Database -------- @@ -464,7 +464,7 @@ Audit Performing an audit is done by invoking the ``taler-auditor`` and ``taler-wire-auditor`` tools respectively. Both tools generate JSON -files, which can then be combined using the ``contrib/render.py'' +files, which can then be combined using the ``contrib/render.py`` script into the TeX report. :: @@ -487,7 +487,7 @@ anymore), this is not recommended in a production setup. -.. _Database-upgrades: +.. _AuditorDatabaseUpgrades: Database upgrades ----------------- @@ -510,7 +510,7 @@ historic transactions. Hence this should not be done in a production system. -.. _Revocations: +.. _AuditorRevocations: Revocations ----------- diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 245e29b9..dfa6492e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1119,10 +1119,6 @@ options: .. [1] https://docs.docker.com/ -.. [2] - Supporting SEPA is still work in progress; the backend will accept - this configuration, but the exchange will not work with SEPA today. - Diagnostics @@ -1133,7 +1129,7 @@ topics that might be helpful to understand how the exchange operates, which files should be backed up. The information may also be helpful for diagnostics. -.. _Database-Scheme: +.. _MerchantDatabaseScheme: Database Scheme --------------- diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst index 20239352..88fa13d5 100644 --- a/taler-nfc-guide.rst +++ b/taler-nfc-guide.rst @@ -45,7 +45,7 @@ using `curl `_ to make HTTP(S) requests. can be opened, and give a warning if it is detected that the devices does not have Internet connectivity. - The following :http:post:`/order` request to the merchant backend creates a + The following :http:post:`/private/orders` request to the merchant backend creates a simple order: .. code-block:: sh @@ -63,20 +63,20 @@ using `curl `_ to make HTTP(S) requests. } EOF ) - $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/order + $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/private/orders { "order_id": "2019.255-02YDHMXCBQP6J" } 2. The merchant checks the payment status of the order using - :http:get:`/check-payment`: + :http:get:`/private/orders/$ORDER_ID`: .. code-block:: sh $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' $ curl -XGET -H"$auth_header" \ - "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J" + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" # Response: { "taler_pay_uri": "taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J", @@ -121,7 +121,7 @@ using `curl `_ to make HTTP(S) requests. $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' $ curl -XGET -H"$auth_header" \ - "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J" + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" # Response: { "paid": true, @@ -135,7 +135,7 @@ using `curl `_ to make HTTP(S) requests. before responding with the fulfillment page. For in-store payments, the merchant must periodically check the payment status. - Instead of polling in a busy loop, the ``long_poll_ms`` parameter of :http:get:`/check-payment` + Instead of polling in a busy loop, the ``timeout_ms`` parameter of :http:get:`/private/orders/$ORDER_ID` should be used. @@ -281,4 +281,3 @@ The request tunneling request/response JSON messages have the following schema: // May contain error details if 'status==0' body?: object; } - -- cgit v1.2.3 From 3dd24bd40d15bdd10e1fd183995935d4e7786e31 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 8 Jul 2020 15:29:45 +0200 Subject: update specification for #6416 --- core/api-common.rst | 14 +++++++++++++- core/api-exchange.rst | 5 +++++ 2 files changed, 18 insertions(+), 1 deletion(-) (limited to 'core/api-common.rst') diff --git a/core/api-common.rst b/core/api-common.rst index 272dfd6c..987ba664 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -672,6 +672,7 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct GNUNET_HashCode h_contract_terms; struct GNUNET_HashCode h_wire; + struct GNUNET_HashCode h_denom_pub; struct GNUNET_TIME_AbsoluteNBO timestamp; struct GNUNET_TIME_AbsoluteNBO refund_deadline; struct TALER_AmountNBO amount_with_fee; @@ -711,6 +712,7 @@ within the */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct GNUNET_HashCode session_hash; + struct GNUNET_HashCode h_denom_pub; struct TALER_AmountNBO amount_with_fee; struct TALER_AmountNBO melt_fee; union TALER_CoinSpendPublicKeyP coin_pub; @@ -958,7 +960,17 @@ within the .. _TALER_RecoupRefreshConfirmationPS: .. sourcecode:: c - // FIXME: put definition here + struct TALER_RecoupRefreshConfirmationPS { + + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_AbsoluteNBO timestamp; + struct TALER_AmountNBO recoup_amount; + struct TALER_CoinSpendPublicKeyP coin_pub; + struct TALER_CoinSpendPublicKeyP old_coin_pub; + }; .. _TALER_RecoupConfirmationPS: .. sourcecode:: c diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 9b18a18d..b461733e 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -770,6 +770,11 @@ denomination. // only present if ``type`` is "DEPOSIT" h_wire?: HashCode; + // Hash of the public denomination key used to sign the coin. + // only present if ``type`` is "DEPOSIT", "RECOUP", + // "RECOUP-REFRESH", "OLD-COIN-RECOUP" or "MELT". + h_denom_pub?: HashCode; + // Deposit fee in case of type "REFUND". refund_fee?: Amount; -- cgit v1.2.3