summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-06-23 23:12:59 +0200
committerChristian Grothoff <christian@grothoff.org>2020-06-23 23:12:59 +0200
commit5d3aef5d035c1a78c930b44d19485396d190e09e (patch)
treecfd30015d26c596bd786d4d6facc179073c4c0d3
parentccf586100520ea3c56651403d005c78115f42497 (diff)
downloaddocs-5d3aef5d035c1a78c930b44d19485396d190e09e.tar.gz
docs-5d3aef5d035c1a78c930b44d19485396d190e09e.tar.bz2
docs-5d3aef5d035c1a78c930b44d19485396d190e09e.zip
fix RST warnings
-rw-r--r--anastasis.rst29
-rw-r--r--core/api-common.rst8
-rw-r--r--core/api-exchange.rst3
-rw-r--r--core/api-merchant.rst37
-rw-r--r--core/api-sync.rst4
-rw-r--r--developers-manual.rst31
-rw-r--r--taler-auditor-manual.rst22
-rw-r--r--taler-merchant-manual.rst6
-rw-r--r--taler-nfc-guide.rst13
9 files changed, 81 insertions, 72 deletions
diff --git a/anastasis.rst b/anastasis.rst
index c27b66d..d0012c7 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 93d6d09..272dfd6 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 979eca8..9b18a18 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 1c99a79..5c50709 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 2add73e..67d1e21 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 8c3a350..6e0bc30 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 f5cca27..97ba2a5 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 245e29b..dfa6492 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 2023935..88fa13d 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;
}
-