diff options
| -rw-r--r-- | anastasis.rst | 29 | ||||
| -rw-r--r-- | core/api-common.rst | 8 | ||||
| -rw-r--r-- | core/api-exchange.rst | 3 | ||||
| -rw-r--r-- | core/api-merchant.rst | 37 | ||||
| -rw-r--r-- | core/api-sync.rst | 4 | ||||
| -rw-r--r-- | developers-manual.rst | 31 | ||||
| -rw-r--r-- | taler-auditor-manual.rst | 22 | ||||
| -rw-r--r-- | taler-merchant-manual.rst | 6 | ||||
| -rw-r--r-- | taler-nfc-guide.rst | 13 |
9 files changed, 81 insertions, 72 deletions
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 <AbortResponse>`, 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 <exchange_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 <RefundSuccess> if the `exchange_status` is 200, otherwise + // a <RefundSuccess> 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 <error-codes>`: - 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 <error-codes>` - 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/<reponame>```. 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/<reponame>``` Check with ``git remote -v``. -* **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` 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/<reponame>```. 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/<reponame>``` Check with ``git remote -v``. + + * **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` 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 <https://curl.haxx.se/docs/manpage.html>`_ 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 <https://curl.haxx.se/docs/manpage.html>`_ 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 <https://curl.haxx.se/docs/manpage.html>`_ 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 <https://curl.haxx.se/docs/manpage.html>`_ 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; } - |