diff options
-rw-r--r-- | anastasis.rst | 89 | ||||
-rw-r--r-- | checklist-demo-upgrade.rst | 11 | ||||
-rw-r--r-- | core/wireformats.rst | 4 | ||||
-rw-r--r-- | design-documents/007-payment.rst | 12 | ||||
-rw-r--r-- | developers-manual.rst | 134 | ||||
-rw-r--r-- | libeufin/api-nexus.rst | 92 | ||||
-rw-r--r-- | libeufin/api-sandbox.rst | 59 | ||||
-rw-r--r-- | libeufin/nexus-tutorial.rst | 166 | ||||
-rw-r--r-- | taler-auditor-manual.rst | 32 | ||||
-rw-r--r-- | taler-backoffice-manual.rst | 8 | ||||
-rw-r--r-- | taler-exchange-manual.rst | 48 | ||||
-rw-r--r-- | taler-merchant-api-tutorial.rst | 12 | ||||
-rw-r--r-- | taler-merchant-manual.rst | 251 | ||||
-rw-r--r-- | taler-merchant-pos-terminal.rst | 2 | ||||
-rw-r--r-- | taler-nfc-guide.rst | 8 | ||||
-rw-r--r-- | taler-wallet.rst | 18 |
16 files changed, 540 insertions, 406 deletions
diff --git a/anastasis.rst b/anastasis.rst index 78a7b166..9773e959 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -145,7 +145,7 @@ determined by an adversary performing a targeted attack, as a user's likely also be available to other actors. -:: +.. code-block:: none kdf_id := Argon2( identifier, server_salt, keysize ) @@ -173,7 +173,7 @@ generate the corresponding public key. Here, "ver" is used as a salt for the HKDF to ensure that the result differs from other cases where we hash **kdf_id**. -:: +.. code-block:: none ver_secret := HKDF(kdf_id, "ver", keysize) eddsa_priv := eddsa_d_to_a(ver_secret) @@ -190,7 +190,7 @@ HKDF to ensure that the result differs from other cases where we hash **eddsa_d_to_a()**: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value eddsa_priv is in a 32-byte array "digest", the function clears and sets certain bits as follows: -:: +.. code-block:: none digest[0] = (digest[0] & 0x7f) | 0x40; digest[31] &= 0xf8; @@ -208,7 +208,7 @@ symmetric key and an initialization vector (IV). To ensure that the symmetric key changes for each encryption operation, we compute the key material using an HKDF over a nonce and the kdf_id. -:: +.. code-block:: none (iv,key) := HKDF(kdf_id, nonce, keysize + ivsize) @@ -248,7 +248,7 @@ the **key_share**. To ensure that the key derivation for the encryption of the **recovery document** differs fundamentally from that of an individual **key share**, we use different salts ("erd" and "eks" respectively). -:: +.. code-block:: none (iv0, key0) = HKDF(key_id, nonce0, "erd", keysize + ivsize) (encrypted_recovery_document, aes_gcm_tag) = AES256_GCM(recovery_document, key0, iv0) @@ -277,7 +277,7 @@ The EdDSA keys are used to sign the data sent from the client to the server. Everything the client sends to server is signed. The following algorithm is equivalent for **Anastasis-Policy-Signature**. -:: +.. code-block:: none (anastasis-account-signature) = eddsa_sign(h_body, eddsa_priv) ver_res = eddsa_verifiy(h_body, anastasis-account-signature, eddsa_pub) @@ -291,7 +291,7 @@ algorithm is equivalent for **Anastasis-Policy-Signature**. When requesting policy downloads, the client must also provide a signature: -:: +.. code-block:: none (anastasis-account-signature) = eddsa_sign(version, eddsa_priv) ver_res = eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) @@ -818,7 +818,8 @@ to store or load the different states the client application can have. The reducer takes a state_ in JSON syntax and returns the new state in JSON syntax. For example a **state** may take the following structure: -:: + +.. code-block:: json { "backup_state": "CONTINENT_SELECTING", @@ -830,7 +831,8 @@ For example a **state** may take the following structure: The new state depends on the previous one and on the transition action_ with its arguments given to the reducer. A **transition argument** also is a statement in JSON syntax: -:: + +.. code-block:: json { "continent": "Europe" @@ -838,7 +840,8 @@ arguments given to the reducer. A **transition argument** also is a statement in The new state returned by the reducer with the state and transition argument defined above would look like following for the transition action_ "select_continent": -:: + +.. code-block:: json { "backup_state": "COUNTRY_SELECTING", @@ -927,7 +930,8 @@ Initial state The initial states for backup and recovery processes are looking like following: **Initial backup state:** -:: + +.. code-block:: json { "backup_state": "CONTINENT_SELECTING", @@ -939,7 +943,8 @@ The initial states for backup and recovery processes are looking like following: **Initial backup state:** -:: + +.. code-block:: json { "recovery_state": "CONTINENT_SELECTING", @@ -956,14 +961,16 @@ Common transitions **select_continent:** Arguments (example): -:: + +.. code-block:: json { "continent": "Europe" } Expected new state: -:: + +.. code-block:: json { "backup_state": "COUNTRY_SELECTING", @@ -1006,7 +1013,8 @@ Expected new state: **select_country:** Arguments (example): -:: + +.. code-block:: json { "country": "Germany", @@ -1015,7 +1023,8 @@ Arguments (example): } Expected new state: -:: + +.. code-block:: json { "backup_state": "USER_ATTRIBUTES_COLLECTING", @@ -1143,7 +1152,8 @@ Expected new state: **enter_user_attributes:** Arguments (example): -:: + +.. code-block:: json { "identity_attributes": { @@ -1156,7 +1166,8 @@ Arguments (example): } Expected new state (backup process): -:: + +.. code-block:: json { "backup_state": "AUTHENTICATIONS_EDITING", @@ -1294,7 +1305,8 @@ No Arguments needed, but the **pay** transition may have optional arguments: **pay:** Optional arguments to try uploading just specific truths (example): -:: + +.. code-block:: json { "truth_index": [ @@ -1304,7 +1316,8 @@ Optional arguments to try uploading just specific truths (example): } Optional arguments to try uploading recovery document to specific providers (example): -:: + +.. code-block:: json { "provider_id": [ @@ -1320,7 +1333,8 @@ Backup transitions **add_authentication:** Arguments (example): -:: + +.. code-block:: json { "authentication_method": @@ -1334,7 +1348,8 @@ Arguments (example): } Expected new state: -:: + +.. code-block:: json { "backup_state": "AUTHENTICATIONS_EDITING", @@ -1541,14 +1556,16 @@ Expected new state: **del_authentication:** Arguments (example): -:: + +.. code-block:: json { "auth_method_index": 1 } Expected new state: -:: + +.. code-block:: json { "backup_state": "AUTHENTICATIONS_EDITING", @@ -1749,7 +1766,8 @@ Expected new state: **add_policy:** Arguments (example): -:: + +.. code-block:: json { "policy": [ @@ -1765,7 +1783,8 @@ Arguments (example): } Expected new state: -:: + +.. code-block:: json { "backup_state": "POLICIES_REVIEWING", @@ -2021,14 +2040,16 @@ Expected new state: **del_policy:** Arguments (example): -:: + +.. code-block:: json { "policy_index": 3 } Expected new state: -:: + +.. code-block:: json { "backup_state": "POLICIES_REVIEWING", @@ -2270,7 +2291,8 @@ Expected new state: **enter_secret:** Arguments (example): -:: + +.. code-block:: json { "secret": "someverysecretsecret", @@ -2281,7 +2303,8 @@ Arguments (example): - type: *data* (secret must be a Crockford-Base32 encoded string of some data, e.g. a private key) Expected new state: -:: + +.. code-block:: json { "backup_state": "POLICIES_REVIEWING", @@ -2584,7 +2607,8 @@ Recovery transitions **select_challenge:** Arguments (example): -:: + +.. code-block:: json { "challenge_index": 1 @@ -2594,7 +2618,8 @@ Arguments (example): **solve_challenge:** Arguments (example): -:: + +.. code-block:: json { "challenge_index": 1, diff --git a/checklist-demo-upgrade.rst b/checklist-demo-upgrade.rst index 87d35b6a..5eb00513 100644 --- a/checklist-demo-upgrade.rst +++ b/checklist-demo-upgrade.rst @@ -11,9 +11,14 @@ Post-upgrade checks: - |check| Run ``taler-deployment-arm -I`` to verify that all services are running. - |check| Run the headless wallet to check that services are actually working: - .. code-block:: sh - - taler-wallet-cli integrationtest -e https://exchange.demo.taler.net/ -m https://backend.demo.taler.net/ -b https://bank.demo.taler.net -w "KUDOS:10" -s "KUDOS:5" + .. code-block:: console + + $ taler-wallet-cli integrationtest \ + -e https://exchange.demo.taler.net/ \ + -m https://backend.demo.taler.net/ \ + -b https://bank.demo.taler.net \ + -w "KUDOS:10" \ + -s "KUDOS:5" Basics: diff --git a/core/wireformats.rst b/core/wireformats.rst index 33cda9cf..2f1c9647 100644 --- a/core/wireformats.rst +++ b/core/wireformats.rst @@ -23,7 +23,7 @@ fully test the Taler system without using "real" currencies. The URL format for ``x-taler-bank`` is simple, in that it only specifies an account number and the origin (domain and optionally a port) of the bank: -:: +.. code-block:: none payto://x-taler-bank/BANK_URI/ACCOUNT_IDENTIFIER @@ -54,7 +54,7 @@ levied by the receiving bank. For the merchant to receive deposits through SEPA, the deposit request must follow the payto:// specification for SEPA: -:: +.. code-block:: none payto://sepa/IBAN diff --git a/design-documents/007-payment.rst b/design-documents/007-payment.rst index 9a16776d..432816a0 100644 --- a/design-documents/007-payment.rst +++ b/design-documents/007-payment.rst @@ -75,7 +75,7 @@ The merchant backend runs the following steps to generate the 2. If *order-ID* does not identify an existing order, return a 404 Not Found response. **Terminate**. 3. If *order-ID* identifies an order that is *unclaimed* and has claim token *claim-token*, return the URL - :: + .. code-block:: none {backendBaseUrl}/orders/{order-ID}?token={claim-token}&session_id={session-ID} @@ -85,7 +85,7 @@ The merchant backend runs the following steps to generate the 5. If the order remains unpaid or was paid for a different *session-ID*, obtain the contract terms hash *contract-hash* and return the URL - :: + .. code-block:: none {backendBaseUrl}/orders/{order-ID}?h_contract={contract-hash}&session_id={session-ID} @@ -94,7 +94,7 @@ The merchant backend runs the following steps to generate the 6. Here *order-ID* must now identify an order that is *paid* or *refunded*. Obtain the contract terms hash *contract-hash* and return the URL - :: + .. code-block:: none {backendBaseUrl}/orders/{order-ID}?h_contract={contract-hash}&session_id={session-ID} @@ -117,7 +117,7 @@ The merchant backend runs the following steps to generate the HTML page for 2. If the order has granted refunds that have not been obtained by the wallet yet, prompt the URI - :: + .. code-block:: none taler{proto_suffix}://refund/{/merchant_prefix*}/{order-id}/{session-id} @@ -138,7 +138,7 @@ The merchant backend runs the following steps to generate the HTML page for 2. Prompt the URI - :: + .. code-block:: none taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-ID}?c={claim-token} @@ -163,7 +163,7 @@ The merchant backend runs the following steps to generate the HTML page for 4. Prompt the URI - :: + .. code-block:: none taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-ID} diff --git a/developers-manual.rst b/developers-manual.rst index 3b71d9ea..2910c9fb 100644 --- a/developers-manual.rst +++ b/developers-manual.rst @@ -51,7 +51,7 @@ Code Repositories Taler code is versioned with Git. For those users without write access, all the codebases are found at the following URL: -:: +.. code-block:: none git://git.taler.net/<repository> @@ -78,7 +78,7 @@ in the `Git book <https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Yo If you have been granted write access, you first of all must change the URL of the respective repository to: -:: +.. code-block:: none ssh://git@git.taler.net/<repository> @@ -94,7 +94,7 @@ such that others can verify your commits later. To sign all commits, you should run -:: +.. code-block:: console $ git config --global commit.gpgsign true @@ -102,7 +102,7 @@ You can also sign individual commits only by adding the ``-S`` option to the ``git commit`` command. If you accidentally already made commits but forgot to sign them, you can retroactively add signatures using: -:: +.. code-block:: console $ git rebase -S @@ -121,7 +121,7 @@ the master branch. If you commit and later find out that new commits were pushed, the following command will pull the new commits and rebase yours on top of them. -:: +.. code-block:: console # -S instructs Git to (re)sign your commits $ git pull --rebase -S @@ -218,7 +218,7 @@ Tagging components All Taler components must be tagged with git before they are deployed on the ``demo`` environment, using a tag of the following form: -:: +.. code-block:: none demo-YYYY-MM-DD-SS YYYY = year @@ -232,7 +232,7 @@ Environment Layout Environments have the following layout: -:: +.. code-block:: none $HOME/ deployment (deployment.git checkout) @@ -282,7 +282,7 @@ When deploying to ``demo``, the ``envcfg.py`` should be committed to ``deploymen Bootstrapping an Environment ---------------------------- -.. code-block:: sh +.. code-block:: console $ git clone https://git.taler.net/deployment.git ~/deployment $ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py @@ -299,7 +299,7 @@ Bootstrapping an Environment Upgrading an Existing Environment --------------------------------- -.. code-block:: sh +.. code-block:: console $ rm -rf ~/sources ~/local $ git -C ~/deployment pull @@ -316,7 +316,7 @@ Switching Demo Colors As the ``demo`` user, to switch to color ``${COLOR}``, run the following script from ``deployment/bin``: -.. code-block:: sh +.. code-block:: console $ taler-deployment switch-demo @@ -359,7 +359,7 @@ All the Taler documentation is built by the user ``docbuilder`` that runs a Buildbot worker. The following commands set the ``docbuilder`` up, starting with a empty home directory. -.. code-block:: sh +.. code-block:: console # Log-in as the 'docbuilder' user. @@ -381,7 +381,7 @@ Taler Websites, ``www.taler.net`` and ``stage.taler.net``, are built by the user ``taler-websites`` by the means of a Buildbot worker. The following commands set the ``taler-websites`` up, starting with a empty home directory. -.. code-block:: sh +.. code-block:: console # Log-in as the 'taler-websites' user. @@ -401,7 +401,7 @@ Code coverage Code coverage tests are run by the ``lcovworker`` user, and are also driven by Buildbot. -.. code-block:: sh +.. code-block:: console # Log-in as the 'lcovworker' user. @@ -423,7 +423,7 @@ The user ``demo-checker`` runs periodic checks to see if all the ``*.demo.taler.net`` services are up and running. It is driven by Buildbot, and can be bootstrapped as follows. -.. code-block:: sh +.. code-block:: console # Log-in as the 'demo-checker' user @@ -444,7 +444,7 @@ Both 'test' and 'demo' setups get their tip reserve topped up by a Buildbot worker. The following steps get the reserve topper prepared. -.. code-block:: sh +.. code-block:: console # Log-in as <env>-topper, with <env> being either 'test' or 'demo' @@ -464,7 +464,7 @@ Both 'test' and 'demo' setups get their auditor reports compiled by a Buildbot worker. The following steps get the reports compiler prepared. -.. code-block:: sh +.. code-block:: console # Log-in as <env>-auditor, with <env> being either 'test' or 'demo' @@ -518,10 +518,10 @@ Tagging Tag releases with an **annotated** commit, like -.. code-block:: sh +.. code-block:: console - git tag -a v0.1.0 -m "Official release v0.1.0" - git push origin v0.1.0 + $ git tag -a v0.1.0 -m "Official release v0.1.0" + $ git push origin v0.1.0 Database for tests @@ -539,32 +539,32 @@ the change of the version. Update the Texinfo documentation using the files from docs.git: -.. code-block:: +.. code-block:: console # Get the latest documentation repository - cd $GIT/docs - git pull - make texinfo + $ cd $GIT/docs + $ git pull + $ make texinfo # The *.texi files are now in _build/texinfo # # This checks out the prebuilt branch in the prebuilt directory - git worktree add prebuilt prebuilt - cd prebuilt + $ git worktree add prebuilt prebuilt + $ cd prebuilt # Copy the pre-built documentation into the prebuilt directory - cp -r ../_build/texinfo . + $ cp -r ../_build/texinfo . # Push and commit to branch - git commit -a -S -m "updating texinfo" - git status + $ git commit -a -S -m "updating texinfo" + $ git status # Verify that all files that should be tracked are tracked, # new files will have to be added to the Makefile.am in # exchange.git as well! - git push + $ git push # Remember $REVISION of commit # # Go to exchange - cd $GIT/exchange/doc/prebuilt + $ cd $GIT/exchange/doc/prebuilt # Update submodule to point to latest commit - git checkout $REVISION + $ git checkout $REVISION Finally, the Automake ``Makefile.am`` files may have to be adjusted to include new ``*.texi`` files or images. @@ -573,14 +573,14 @@ include new ``*.texi`` files or images. For the exchange test cases to pass, ``make install`` must be run first. Without it, test cases will fail because plugins can't be located. -.. code-block:: sh +.. code-block:: console - ./bootstrap - ./configure # add required options for your system - make dist - tar -xf taler-$COMPONENT-$VERSION.tar.gz - cd taler-$COMPONENT-$VERSION - make install check + $ ./bootstrap + $ ./configure # add required options for your system + $ make dist + $ tar -xf taler-$COMPONENT-$VERSION.tar.gz + $ cd taler-$COMPONENT-$VERSION + $ make install check Wallet WebExtension ------------------- @@ -589,10 +589,10 @@ The version of the wallet is in *manifest.json*. The ``version_name`` should be adjusted, and *version* should be increased independently on every upload to the WebStore. -.. code-block:: sh +.. code-block:: console - ./configure - make dist + $ ./configure + $ make dist Upload to GNU mirrors --------------------- @@ -601,7 +601,7 @@ See https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads Directive file: -:: +.. code-block:: none version: 1.2 directory: taler @@ -644,13 +644,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 -------------------- @@ -675,19 +675,19 @@ What follows is a sort of Wizard. You can find detailed docs at https://docs.we Under *https://weblate.taler.net/create/component/vcs/*: - * **Source code repository** - Generally ``git+ssh://git@git.taler.net/<reponame>```. Check with ``git remote -v``. +* **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 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 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. +* **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 +* **Merge style** - *Rebase*, in line with GNU Taler development procedures - * **Translation license** - *GNU General Public License v3.0 or Later* +* **Translation license** - *GNU General Public License v3.0 or Later* - * **Adding new translation** - Decide how to handle adding new translations +* **Adding new translation** - Decide how to handle adding new translations How to Create a Translation --------------------------- @@ -778,16 +778,16 @@ First, ensure that you have the required dependencies installed: Then you can get the app's source code using git: -.. code-block:: shell +.. code-block:: console # Start by cloning the Android git repository - git clone https://git.taler.net/taler-android.git + $ git clone https://git.taler.net/taler-android.git # Change into the directory of the cloned repository - cd taler-android + $ cd taler-android # Find out which Android SDK version you will need - grep -i compileSdkVersion merchant-terminal/build.gradle + $ grep -i compileSdkVersion merchant-terminal/build.gradle The last command will return something like ``compileSdkVersion 29``. So visit the `Android Rebuilds <http://android-rebuilds.beuc.net/>`_ project @@ -801,22 +801,22 @@ In our example, the version is ``29`` which is available, so download the "SDK Platform" package of "Android 10.0.0 (API 29)" and unpack it: -.. code-block:: shell +.. code-block:: console # Change into the directory that contains your downloaded SDK - cd $HOME + $ cd $HOME # Unpack/extract the Android SDK - unzip android-sdk_eng.10.0.0_r14_linux-x86.zip + $ unzip android-sdk_eng.10.0.0_r14_linux-x86.zip # Tell the build system where to find the SDK - export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86" + $ export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86" # Change into the directory of the cloned repository - cd taler-android + $ cd taler-android # Build the merchant-terminal app - ./gradlew :merchant-terminal:assembleRelease + $ ./gradlew :merchant-terminal:assembleRelease If you get an error message complaining about build-tools @@ -935,11 +935,11 @@ in GNU Taler are: When shell scripts are used, they ``MUST`` begin with the following ``set`` command: -.. code-block:: shell +.. code-block:: console # Make the shell fail on undefined variables and # commands with non-zero exit status. - set -eu + $ set -eu Kotlin ------ @@ -1017,11 +1017,11 @@ Note: the main interpreter and the most part of CMDs and traits are hosted inside the exchange codebase, but nothing prevents the developer from implementing new CMDs and traits within other codebases. -:: +.. code-block:: c /* Without loss of generality, let's consider the * following logic to exist inside the run() method of CMD1 */ - .. + ... struct TALER_Amount *a; /** diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 01e8e926..f47101fd 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -103,6 +103,22 @@ User Management Return list of users. +Test API +-------- + +.. http:post:: {nexusBase}/bank-accounts/{acctid}/test-camt-ingestion/{type} + + This call allows tests to **directly** give Nexus a Camt document. After + the processing, all the payment(s) details should be ingested as if the + Camt came normally from a bank / the Sandbox. ``acctid`` must match the + label of a locally imported bank account, and ``type`` for now can only be + ``C53``. + + **Response** + + The successful case should respond with a ``200 OK`` and a empty JSON body. + + Bank Accounts ------------- @@ -281,33 +297,75 @@ manages payment initiations of the account and tracks the initiations of payment Optional, defaults to "earliest possible" date. - **Response:** A list of `Transaction` objects. + **Response:** A object with a unique field named ``transactions`` + that contains a list of `Transaction` objects. .. ts:def:: Transaction interface Transaction { - // local bank account involved in the transaction. - account: string; - // counterpart IBAN - counterpartIban: string; + // money moved by the transaction + amount: string; - // counterpart BIC - counterpartBic: string; + // CRDT or DBIT + creditDebitIndicator: string - // counterpart holder name - counterpartName: string; + // Two of the most used values are BOOK, or PENDING + status: string; - // amount, in the format [-]CURRENCY:XX.YY, - // where the minus sign as prefix indicates - // a debit for the user's bank account. - amount: string; + // FIXME + bankTransactionCode: string; - // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction. - date: string; + // FIXME + valueDate: string; + + // When this payment got booked. In the form YYYY-MM-DD + bookingDate: string; - // Payment subject. - subject: string; + // FIXME + accountServicerRef: string; + + // FIXME + batches: { + // list of batched transactions + batchTransactions: BatchedTransaction[]; + }; + } + + .. ts:def:: BatchedTransaction + + interface BatchedTransaction { + // FIXME + amount: string; + // FIXME + creditDebitIndicator: string; + // FIXME + details { + debtor: { + name: string; + }; + debtorAccount: { + iban: string; + }; + // Missing, when the payment is DBIT. + debtorAgent: { + bic: string; + }; + creditor: { + name: string; + }; + creditorAccount: { + iban: string; + }; + // Missing, when the payment is CRDT. + creditorAgent: { + iban: string; + }; + // FIXME + endToEndId: string; + // FIXME + unstructuredRemittanceInformation: string; + } } diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index d848ba40..d1214d52 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -9,28 +9,83 @@ HTTP API .. Payments. + +.. http:post:: /admin/payments/camt + + Return the history of one IBAN in Camt.053 format. + + **Request** + + .. code-block:: tsref + + interface CamtParams { + + // IBAN managed by the running Sandbox, for which + // the Camt.053 response is going to be generated. + iban: string; + + // The Camt type to return. Only '53' is allowed + // at this moment. + type: number; + } + + **Response** + + The expected Camt.053 document. + + +.. http:get:: /admin/payments + + Return the list of *all* the payments known by the sandbox. + + **Response** + + .. code-block:: tsref + + interface SandboxPayments { + + // The list of all known payments, regardless + // of any IBAN involved in them. + payments: SandboxPayment[]; + } + .. http:post:: /admin/payments Adds a new payment to the book. Mainly used for testing purposes. **Request:** + + One object of type `SandboxPayment` - .. ts:def:: PaymentRequest + .. ts:def:: SandboxPayment - interface PaymentRequest { + interface SandboxPayment { // IBAN that will receive the payment. creditorIban: string; + // FIXME + creditorBic: string; + // FIXME + creditorName: string; // IBAN that will send the payment. debitorIban: string; + // FIXME + debitorBic: string; + // FIXME + debitorName: string; amount: string; currency: string; // subject of the payment. subject: string; + + // Whether the payment is credit or debit *for* the + // account being managed *by* the running sandbox. + // Can take the values: "CRDT" or "DBIT". + direction: string; } .. diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index 82f1ba43..e919ed8c 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -16,7 +16,7 @@ Obtain Nexus ============ Nexus belongs to the LibEuFin project, and can be downloaded via Git: -.. code-block:: shell +.. code-block:: console $ git clone git://git.taler.net/libeufin @@ -26,14 +26,14 @@ Install Nexus ============= Navigate into the `libeufin` local repository, and from top-level run: -.. code-block:: shell +.. code-block:: console $ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix $ ./gradlew -Pprefix=$PREFIX cli:installToPrefix In case of success, the two following commands should be found: -.. code-block:: shell +.. code-block:: console $ which libeufin-nexus $ which libeufin-cli @@ -43,7 +43,7 @@ Connect Nexus with a EBICS account Use the following command to *(1) run the nexus service*: -.. code-block:: shell +.. code-block:: console $ libeufin-nexus @@ -55,7 +55,7 @@ for PostgreSQL will be provided. At this point a *(2) superuser account needs to be activated into the system*: -.. code-block:: shell +.. code-block:: console $ libeufin-nexus superuser foo # Will interactively ask for password @@ -75,74 +75,74 @@ creating a EBICS connection*. set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password in step (2). -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connections \ - new-ebics-connection \ - --ebics-url $EBICS_BASE_URL \ - --host-id $EBICS_HOST_ID \ - --partner-id $EBICS_PARTNER_ID \ - --ebics-user-id $EBICS_USER_ID \ - $CONNECTION_NAME + $ libeufin-cli \ + connections \ + new-ebics-connection \ + --ebics-url $EBICS_BASE_URL \ + --host-id $EBICS_HOST_ID \ + --partner-id $EBICS_PARTNER_ID \ + --ebics-user-id $EBICS_USER_ID \ + $CONNECTION_NAME If the step above executed correctly, Nexus created all the cryptographic material that is needed on the client side; in this EBICS example, it created the signature and identification keys. It is therefore advisable to *(4) make a backup copy* of such keys. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connections \ - export-backup \ - --passphrase $SECRET \ - --outputfile $BACKUP_FILE \ - $CONNECTION_NAME + $ libeufin-cli \ + connections \ + export-backup \ + --passphrase $SECRET \ + --outputfile $BACKUP_FILE \ + $CONNECTION_NAME At this point, Nexus must communicate all the details to the bank. Therefore, it will *(5) synchronize the connection*. In this EBICS example, Nexus will send the *INI* and *HIA* messages to the bank. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connections \ - sync \ - $CONNECTION_NAME + $ libeufin-cli \ + connections \ + sync \ + $CONNECTION_NAME Once the connection is synchronized, Nexus needs to import locally the data corresponding to the bank accounts offered by the bank connection just made. The command below *(6) downloads the list of the bank accounts offered by the* ``$CONNECTION_NAME``. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connections \ - download-bank-accounts \ - $CONNECTION_NAME + $ libeufin-cli \ + connections \ + download-bank-accounts \ + $CONNECTION_NAME It is now possible to *(7) list the accounts offered by the connection*. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connections \ - list-offered-bank-accounts \ - $CONNECTION_NAME + $ libeufin-cli \ + connections \ + list-offered-bank-accounts \ + $CONNECTION_NAME Nexus now needs an explicit *(8) import of the accounts it needs to manage*. This step is needed to let the user pick a custom name for such accounts. -.. code-block:: shell +.. code-block:: console - libeufin-cli - connections \ - import-bank-account \ - --offered-account-id $ACCOUNT_NATIVE_NAME \ - --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \ - $CONNECTION_NAME + $ libeufin-cli + connections \ + import-bank-account \ + --offered-account-id $ACCOUNT_NATIVE_NAME \ + --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \ + $CONNECTION_NAME Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``) under a certain connection (``$CONNECTION_NAME``), it is possible @@ -161,22 +161,22 @@ from the bank, and then ask it again to return the results. This command asks Nexus to *download the latest bank statements*: -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - accounts \ - fetch-transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli \ + accounts \ + fetch-transactions \ + $CUSTOM_RENAMING_FOR_ACCOUNT Once Nexus stored all the information in the database, the client can ask to actually **see** the transactions: -.. code-block:: shell +.. code-block:: console - libeufin-cli - accounts \ - transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli + accounts \ + transactions \ + $CUSTOM_RENAMING_FOR_ACCOUNT Make a payment ============== @@ -188,17 +188,17 @@ Payments pass through two phases: preparation and submission. The following command prepares a payment: -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - accounts \ - prepare-payment \ - --credit-iban $IBAN_TO_SEND_MONEY_TO \ - --credit-bic $BIC_TO_SEND_MONEY_TO \ - --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \ - --payment-amount $AMOUNT \ - --payment-subject $SUBJECT \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli \ + accounts \ + prepare-payment \ + --credit-iban $IBAN_TO_SEND_MONEY_TO \ + --credit-bic $BIC_TO_SEND_MONEY_TO \ + --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \ + --payment-amount $AMOUNT \ + --payment-subject $SUBJECT \ + $CUSTOM_RENAMING_FOR_ACCOUNT Note: the ``$AMOUNT`` value needs the format ``X.Y:CURRENCY``; for example ``10:EUR``, or ``1.01:EUR``. @@ -207,13 +207,13 @@ The previous command should return a value (``$UUID``) that uniquely identifies the prepared payment in the Nexus system. It'll be needed in the next step, to **send the payment instructions to the bank**: -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - accounts \ - submit-payment \ - --payment-uuid $UUID \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli \ + accounts \ + submit-payment \ + --payment-uuid $UUID \ + $CUSTOM_RENAMING_FOR_ACCOUNT Restore the backup @@ -224,14 +224,14 @@ associated with one bank connection subscription. For EBICS, this means that the INI and HIA secret keys will be restored for the requesting user. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - connection \ - restore-backup \ - --passphrase $SECRET \ - --outputfile $BACKUP_FILE \ - $CONNECTION_NAME + $ libeufin-cli \ + connection \ + restore-backup \ + --passphrase $SECRET \ + --outputfile $BACKUP_FILE \ + $CONNECTION_NAME Creating a Taler facade ======================= @@ -245,14 +245,14 @@ At this moment, only the *Taler facade type* is implemented in the Nexus, and the command below will show how to instantiate one under an existing bank account. -.. code-block:: shell +.. code-block:: console - libeufin-cli \ - taler-facade \ - new-facade \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli \ + taler-facade \ + new-facade \ + --facade-name $FACADE_NAME \ + $CONNECTION_NAME \ + $CUSTOM_RENAMING_FOR_ACCOUNT At this point, the additional *taler-wire-gateway* (link here) API becomes offered by the Nexus. The purpose is to let a Taler exchange diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index 35f5a799..432e2d1e 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -221,7 +221,7 @@ to export some of the tooling required by Taler. To download and install libgnunetutil, proceed as follows: -:: +.. code-block:: console $ git clone https://git.gnunet.org/gnunet/ $ cd gnunet/ @@ -237,7 +237,7 @@ which requires you to run the last step as ``root``. To download and install the GNU Taler exchange, proceeds as follows: -:: +.. code-block:: console $ git clone git://git.taler.net/exchange $ cd exchange @@ -320,7 +320,7 @@ choosing the backend, it is mandatory to supply the connection string - via configuration option CONFIG, under section [auditordb-BACKEND]. For example, the demo exchange is configured as follows: -:: +.. code-block:: ini [auditor] ... @@ -370,9 +370,9 @@ If this step is skipped, the auditor will malfunction at all future stages with a foreign key violation, as it doesn't know the exchange's master public key. -:: +.. code-block:: console - taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL + $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL .. _AuditorDenominations: @@ -392,9 +392,9 @@ receive the blob to sign (Website, manual delivery, ...). Note that the blob does not contain confidential data, but signing the wrong keys would be fatal. Given the blob, the auditor would sign it using: -:: +.. code-block:: console - taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE + $ taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE Those arguments are all mandatory. @@ -467,7 +467,7 @@ Performing an audit is done by invoking the ``taler-auditor`` and files, which can then be combined using the ``contrib/render.py`` script into the TeX report. -:: +.. code-block:: console $ taler-audit @@ -510,7 +510,7 @@ several categories of failures of different severity: the correct amount to a merchant). - Configuration issues (such was wire fees unavailable) - + .. _AuditorDatabaseUpgrades: @@ -520,9 +520,9 @@ Database upgrades To upgrade the database between Taler versions can be done by running: -:: +.. code-block:: console - $ taler-auditor-dbinit + $ taler-auditor-dbinit However, the above is the general rule. Please review the specific release notes to ensure this is correct for the @@ -531,7 +531,7 @@ specific upgrade. The auditor database can be re-initialized using: -:: +.. code-block:: console $ taler-auditor-dbinit -r @@ -654,7 +654,7 @@ CodeBlau reports the following checks: coin value without fee, total deposit without refunds - wire out fee is negative - + - coin arithmetic inconsistencies - refund (merchant) is negative @@ -672,13 +672,13 @@ CodeBlau reports the following checks: - wire out inconsistencies in amount - row inconsistencies - + - wire account given is malformed - h(wire) does not match wire - failed to compute hash of given wire data - + - database contains wrong hash code for wire details - no transaction history for coin claimed in aggregation @@ -715,7 +715,7 @@ CodeBlau reports the following checks: - arithmetic inconsistencies - melt contribution vs. fee - + - melt (cost) - refund fee diff --git a/taler-backoffice-manual.rst b/taler-backoffice-manual.rst index d87f100e..3042845d 100644 --- a/taler-backoffice-manual.rst +++ b/taler-backoffice-manual.rst @@ -26,7 +26,7 @@ The back-office Web service code is available at ``git://taler.net/backoffice``. The application can be installed in a GNU-ish fashion. -:: +.. code-block:: console # Get the code: $ git clone git://taler.net/backoffice @@ -63,7 +63,7 @@ read: https://docs.taler.net/exchange/html/taler-exchange.html#Configuration-format), a working configuration example is the following one: -:: +.. code-block:: ini [taler] # will be EUR, USD, or whatever currency the merchant @@ -120,9 +120,9 @@ Launching the backoffice The following example shows how to run the Web service. -:: +.. code-block:: console - # such invocation will work only if the configuration contains + # Such invocation will work only if the configuration contains # a section called "[backoffice-myshop]" which looks like the # example above. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 0b038216..e68bdf8f 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -257,7 +257,7 @@ to export some of the tooling required by Taler. To download and install libgnunetutil, proceed as follows: -:: +.. code-block:: console $ git clone git://git.gnunet.org/gnunet $ cd gnunet/ @@ -273,7 +273,7 @@ which requires you to run the last step as ``root``. To download and install the GNU Taler exchange, proceeds as follows: -:: +.. code-block:: console $ git clone git://git.taler.net/exchange $ cd exchange @@ -311,7 +311,7 @@ it under $HOME/.config/. A config file is a text file containing sections, and each section contains its values. The right format follows: -:: +.. code-block:: ini [section1] value1 = string @@ -330,7 +330,7 @@ variables that are unset, by using the following syntax: by defining them under a ``[paths]`` section, see example below, -:: +.. code-block:: ini [paths] TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data @@ -340,7 +340,7 @@ by defining them under a ``[paths]`` section, see example below, or by setting them in the environment: -:: +.. code-block:: console $ export VAR=/x @@ -378,7 +378,7 @@ file format and can also be edited by hand. Run -:: +.. code-block:: console $ taler-config -s $SECTION @@ -386,7 +386,7 @@ to list all of the configuration values in section ``$SECTION``. Run -:: +.. code-block:: console $ taler-config -s $section -o $option @@ -395,7 +395,7 @@ section ``$section``. Finally, to change a setting, run -:: +.. code-block:: console $ taler-config -s $section -o $option -V $value @@ -408,7 +408,7 @@ their value. To expand the ``$DATADIR`` or other $-variables in the configuration, pass the ``-f`` option to ``taler-config``. For example, compare: -:: +.. code-block:: console $ taler-config -s ACCOUNT-bank \ -o WIRE_RESPONSE @@ -496,7 +496,7 @@ starting with “exchange-account-” for the section name. You can ENABLE for each account whether it should be used, and for what (incoming or outgoing wire transfers): -:: +.. code-block:: ini [exchange-account-1] # With x-taler-bank (say for PyBank) @@ -530,7 +530,7 @@ The command line tool taler-exchange-wire is used to create the follows to create all of the WIRE_RESPONSE files (in the locations specified by the configuration): -:: +.. code-block:: console $ taler-exchange-wire @@ -554,7 +554,7 @@ apply whenever the exchange closes a reserve (sending back funds to the customer). The fees must be constant for a full year, which is specified as part of the name of the option. -:: +.. code-block:: ini [fees-iban] WIRE-FEE-2018 = EUR:0.01 @@ -583,7 +583,7 @@ choosing the backend, it is mandatory to supply the connection string - via configuration option CONFIG, under section [exchangedb-BACKEND]. For example, the demo exchange is configured as follows: -:: +.. code-block:: ini [exchange] ... @@ -741,9 +741,9 @@ by the tool ``taler-exchange-keyup``. The following command generates denomkeys and signkeys, plus the "blob" that is to be signed by the auditor. -:: +.. code-block:: console - taler-exchange-keyup -o blob + $ taler-exchange-keyup -o blob *blob* contains data about denomkeys that the exchange operator needs to get signed by every auditor he wishes (or is forced to) work with. @@ -753,9 +753,9 @@ blob to sign (Website, manual delivery, ..). Nonetheless, the exchange admin can fake an auditor signature — for testing purposes — by running the following command -:: +.. code-block:: console - taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE + $ taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE Those arguments are all mandatory. @@ -775,9 +775,9 @@ option ``AUDITOR_BASE_DIR`` under the section ``[exchangedb]``. Assuming following command will "add" the auditor identified by ``AUDITOR_URL`` to the exchange. -:: +.. code-block:: console - cp OUTPUT_FILE ${HOME}/.local/share/taler/auditors + $ cp OUTPUT_FILE ${HOME}/.local/share/taler/auditors If the auditor has been correctly added, the exchange’s ``/keys`` response must contain an entry in the ``auditors`` array mentioning the @@ -793,7 +793,7 @@ versions. The exchange database can be re-initialized using: -:: +.. code-block:: console $ taler-exchange-dbinit -r @@ -850,7 +850,7 @@ starting time at which the signing key can be used in microseconds since the Epoch. The file format is defined by the struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP: -:: +.. code-block:: c struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP { struct TALER_ExchangePrivateKeyP signkey_priv; @@ -883,7 +883,7 @@ struct TALER_EXCHANGEDB_DenominationKeyInformationP giving the attributes of the denomination key and the associated signature with the exchange’s long-term offline key: -:: +.. code-block:: c struct TALER_EXCHANGEDB_DenominationKeyInformationP { struct TALER_MasterSignatureP signature; @@ -940,7 +940,7 @@ Each file must contain a header with the public key information of the auditor, the master public key of the exchange, and the number of signed denomination keys: -:: +.. code-block:: c struct AuditorFileHeaderP { struct TALER_AuditorPublicKeyP apub; @@ -1008,7 +1008,7 @@ initialized using ``taler-exchange-keyup``. You can run a first simple benchmark using: -:: +.. code-block:: console $ createdb talercheck # if it does not yet exist $ taler-exchange-keyup -c benchmark.conf diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 33e0f8e5..2070a943 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -127,7 +127,7 @@ The public sandbox backend https://backend.demo.taler.net/ uses an API key in the ``Authorization`` header. The value of this header must be ``ApiKey sandbox`` for the public sandbox backend. -:: +.. code-block:: python >>> import requests >>> requests.get("https://backend.demo.taler.net", @@ -217,7 +217,7 @@ manual for details. A minimal Python snippet for creating an order would look like this: -:: +.. code-block:: python >>> import requests >>> body = dict(order=dict(amount="KUDOS:10", @@ -278,7 +278,7 @@ status of the payment, even if you know that the user did not pay yet. There are a few corner cases to consider when constructing this URL, so asking the backend to do it is the safest method. -:: +.. code-block:: python >>> import requests >>> r = requests.get("https://backend.demo.taler.net/private/orders/" + order_id, @@ -343,7 +343,7 @@ by the wallet. This code snipped illustrates giving a refund: -:: +.. code-block:: python >>> import requests >>> refund_req = dict(refund="KUDOS:10", @@ -435,7 +435,7 @@ Taler Merchant Operating Manual. To check if tipping is configured properly and if there are sufficient funds available for tipping, query the ``/tip-query`` endpoint: -:: +.. code-block:: python >>> import requests >>> requests.get("https://backend.demo.taler.net/tip-query?instance=default", @@ -463,7 +463,7 @@ up the tip. pick up tip This code snipped illustrates giving a tip: -:: +.. code-block:: python >>> import requests >>> tip_req = dict(amount="KUDOS:0.5", diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index a49b9163..bff0e84d 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -283,16 +283,6 @@ Installation of dependencies The following packages need to be installed before we can compile the backend: -- autoconf >= 2.69 - -- automake >= 1.14 - -- libtool >= 2.4 - -- autopoint >= 0.19 - -- libltdl >= 2.4 - - libunistring >= 0.9.3 - libcurl >= 7.26 (or libgnurl >= 7.26) @@ -313,17 +303,26 @@ backend: - GNU libmicrohttpd >= 0.9.71 -- GNUnet >= 0.14.0 +- GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__) -- GNU Taler exchange (from Git or see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__) +- GNU Taler exchange (see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__) Except for the last two, these are available in most GNU/Linux distributions and should just be installed using the respective package manager. Be careful with GNU libmicrohttpd; here, some distributions only include an older version that will not work. +While you are in the GNU Taler exchange +`download directory <http://ftpmirror.gnu.org/taler/>`__, +you might as well also download the tarball for GNU Taler merchant. + +GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. +The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match. +Exceptions to this general rule are documented in the release notes. +For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1. + The following sections will provide detailed instructions for installing -the libgnunetutil and GNU Taler exchange dependencies. +the ``libgnunetutil`` and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: @@ -336,13 +335,11 @@ Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. -To download and install GNUnet, proceed as follows: +To download and install GNUnet, unpack the tarball and change +into the resulting directory, then proceed as follows: -:: +.. code-block:: console - $ git clone https://git.gnunet.org/gnunet/ - $ cd gnunet/ - $ ./bootstrap $ ./configure [--prefix=GNUNETPFX] $ # Each dependency can be fetched from non standard locations via $ # the '--with-<LIBNAME>' option. See './configure --help'. @@ -364,20 +361,17 @@ Installing the GNU Taler exchange .. index:: exchange -After installing GNUnet, you can download and install the exchange as -follows: +After installing GNUnet, unpack the GNU Taler exchange tarball, +change into the resulting directory, and proceed as follows: - :: +.. code-block:: console - $ git clone https://git.taler.net/exchange.git/ - $ cd exchange - $ ./bootstrap - $ ./configure [--prefix=EXCHANGEPFX] \ - [--with-gnunet=GNUNETPFX] - $ # Each dependency can be fetched from non standard locations via - $ # the '--with-<LIBNAME>' option. See './configure --help'. - $ make - # make install + $ ./configure [--prefix=EXCHANGEPFX] \ + [--with-gnunet=GNUNETPFX] + $ # Each dependency can be fetched from non standard locations via + $ # the '--with-<LIBNAME>' option. See './configure --help'. + $ make + # make install If you did not specify a prefix, the exchange will install to ``/usr/local``, which requires you to run the last step as ``root``. You have to specify @@ -398,13 +392,12 @@ Installing the GNU Taler merchant backend The following steps assume all dependencies are installed. -Use the following commands to download and install the merchant backend: +First, unpack the GNU Taler merchant tarball and change into +the resulting directory. +Then, use the following commands to build and install the merchant backend: - :: +.. code-block:: console - $ git clone https://git.taler.net/merchant/ - $ cd merchant - $ ./bootstrap $ ./configure [--prefix=PFX] \ [--with-gnunet=GNUNETPFX] \ [--with-exchange=EXCHANGEPFX] @@ -435,30 +428,29 @@ Installing Taler on Debian GNU/Linux ------------------------------------ .. index:: Wheezy +.. index:: Jessie +.. index:: Stretch .. index:: Debian Debian wheezy is too old and lacks most of the packages required. +Debian jessie is better, but still lacks PostgreSQL 9.6. -On Debian jessie, only GNU libmicrohttpd needs to be compiled from -source. To install dependencies on Debian jesse, run the following +On Debian stretch, only GNU libmicrohttpd needs to be compiled from +source. To install dependencies on Debian stretch, run the following commands: - :: +.. code-block:: console # apt-get install \ - autoconf \ - automake \ - autopoint \ - libtool \ libltdl-dev \ libunistring-dev \ libsodium-dev \ - libargon2-dev \ + libargon2-0-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ libpq-dev \ - postgresql-9.4 + postgresql-9.6 # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig # gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC @@ -469,13 +461,9 @@ commands: For more recent versions of Debian, you should instead run: - :: +.. code-block:: console # apt-get install \ - autoconf \ - automake \ - autopoint \ - libtool \ libltdl-dev \ libunistring-dev \ libsodium-dev \ @@ -484,9 +472,12 @@ For more recent versions of Debian, you should instead run: libgcrypt20-dev \ libjansson-dev \ libpq-dev \ - postgresql-9.5 \ + postgresql-9.6 \ libmicrohttpd-dev +Note that stretch requires ``libargon2-0-dev``, +while later versions of Debian require ``libargon2-dev``. + For the rest of the installation, follow the generic installation instructions starting with the installation of libgnunetutil. Note that if you used the Debian wheezy instructions above, you need to pass @@ -536,7 +527,7 @@ Service address The following option sets the transport layer address used by the merchant backend: - :: +.. code-block:: ini [MERCHANT]/SERVE = TCP | UNIX @@ -556,10 +547,10 @@ the backend to the network. To run the Taler backend on TCP port 8888, use: - :: +.. code-block:: console - $ taler-config -s MERCHANT -o SERVE -V TCP - $ taler-config -s MERCHANT -o PORT -V 8888 + $ taler-config -s MERCHANT -o SERVE -V TCP + $ taler-config -s MERCHANT -o PORT -V 8888 @@ -569,7 +560,7 @@ Currency Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option - :: +.. code-block:: ini [TALER]/CURRENCY @@ -577,9 +568,9 @@ For testing purposes, the currency MUST match “KUDOS” so that tests will work with the Taler demonstration exchange at https://exchange.demo.taler.net/: - :: +.. code-block:: console - $ taler-config -s TALER -o CURRENCY -V KUDOS + $ taler-config -s TALER -o CURRENCY -V KUDOS Database @@ -588,7 +579,7 @@ Database In principle is possible for the backend to support different DBMSs. The option - :: +.. code-block:: ini [MERCHANT]/DB @@ -600,7 +591,7 @@ DBMS-specific options to access the database. For postgres, you need to provide: - :: +.. code-block:: ini [MERCHANTDB-postgres]/CONFIG @@ -610,33 +601,33 @@ Postgres database you want to use. Suppose ``$USER`` is the name of the user who will run the backend process. Then, you need to first run - :: +.. code-block:: console - $ sudo -u postgres createuser -d $USER + $ sudo -u postgres createuser -d $USER as the Postgres database administrator (usually ``postgres``) to grant ``$USER`` the ability to create new databases. Next, you should as ``$USER`` run: - :: +.. code-block:: console - $ createdb $DBNAME + $ createdb $DBNAME to create the backend’s database. Here, ``$DBNAME`` must match the database name given in the configuration file. To configure the Taler backend to use this database, run: - :: +.. code-block:: console - $ taler-config -s MERCHANTDB-postgres -o CONFIG \ - -V postgres:///$DBNAME + $ taler-config -s MERCHANTDB-postgres -o CONFIG \ + -V postgres:///$DBNAME Now you should create the tables and indices. To do this, run as ``$USER``: - :: +.. code-block:: console - $ taler-merchant-dbinit + $ taler-merchant-dbinit You can improve your security posture if you now REVOKE the rights to CREATE, @@ -659,29 +650,29 @@ section, the following options need to be configured: - The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example, to use the Taler demonstrator, specify: - :: + .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ - -o EXCHANGE_BASE_URL \ - -V https://exchange.demo.taler.net/ + -o EXCHANGE_BASE_URL \ + -V https://exchange.demo.taler.net/ - The “MASTER_KEY” option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: - :: + .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ - -o MASTER_KEY \ - -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + -o MASTER_KEY \ + -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 - The “CURRENCY” option specifies the exchange’s currency. For the Taler demonstrator, use: - :: + .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ - -o CURRENCY \ - -V KUDOS + -o CURRENCY \ + -V KUDOS Note that multiple exchanges can be added to the system by using different tokens in place of ``demo`` in the example above. Note that all of the @@ -702,29 +693,29 @@ that section, the following options need to be configured: - The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example, to use the Taler demonstrator's auditor, specify: - :: + .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ - -o AUDITOR_BASE_URL \ - -V https://exchange.demo.taler.net/ + -o AUDITOR_BASE_URL \ + -V https://exchange.demo.taler.net/ - The “AUDITOR_KEY” option specifies the auditor's public key in base32 encoding. For the Taler demonstrator, use: - :: + .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ - -o AUDITOR_KEY \ - -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 + -o AUDITOR_KEY \ + -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 - The “CURRENCY” option specifies the auditor’s currency. For the Taler demonstrator, use: - :: + .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ - -o CURRENCY \ - -V KUDOS + -o CURRENCY \ + -V KUDOS Note that multiple auditors can be added to the system by using different @@ -743,7 +734,7 @@ Sample backend configuration The following is an example for a complete backend configuration: - :: +.. code-block:: ini [TALER] CURRENCY = KUDOS @@ -792,7 +783,7 @@ Launching the backend Assuming you have configured everything correctly, you can launch the merchant backend as ``$USER`` using - :: +.. code-block:: console $ taler-merchant-httpd @@ -803,13 +794,13 @@ system for how to start and stop daemons. If everything worked as expected, the command - :: +.. code-block:: console $ curl http://localhost:8888/ should return the message - :: +.. code-block:: none Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. @@ -865,7 +856,7 @@ With the knowledge of the payto://-URI, instances can be configured by POSTing a request to :http:post:`/private/instances`. To create a first instance, create a file ``instance.json`` with an `InstanceConfigurationMessage` - :: +.. code-block:: json { payto_uris : [ "$PAYTO_URI" ], @@ -892,7 +883,7 @@ For details, see the :ref:`contract terms <contract-terms>` specification. You can then create the instance using: - :: +.. code-block:: console $ wget --post-file=instance.json http://localhost:8888/private/instances @@ -925,10 +916,10 @@ Using UNIX domain sockets To ensure that the merchant backend is not exposed directly to the network, you *should* bind the backend to a UNIX domain socket: - :: +.. code-block:: console - $ taler-config -s MERCHANT -o SERVE -V UNIX - $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock + $ taler-config -s MERCHANT -o SERVE -V UNIX + $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock Do not use a UNIX domain socket path in "/tmp": systemd (or other init systems) may give Web servers a private "/tmp" thereby hiding UNIX domain @@ -948,7 +939,7 @@ Nginx For Nginx, a possible basic reverse proxy configuration would be: - :: +.. code-block:: nginx proxy_pass http://unix:/some/path/here.sock; proxy_redirect off; @@ -967,16 +958,16 @@ Apache In Apache, make sure you have "mod_proxy", "mod_proxy_http" and "mod_headers" enabled: - :: +.. code-block:: console - a2enmod proxy - a2enmod proxy_http - a2enmod headers + $ a2enmod proxy + $ a2enmod proxy_http + $ a2enmod headers Then configure your Apache reverse proxy like this (you may change the endpoint): - :: +.. code-block:: apacheconf <Location "/"> ProxyPass "unix:/some/path/here.sock|http://example.com/" @@ -1014,7 +1005,7 @@ Nginx For Nginx, you can implement token-based merchant backend authentication as follows: - :: +.. code-block:: nginx location ~ /private/ { if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") { @@ -1033,7 +1024,7 @@ If you are running different instances on the same backend, you likely will want to specify different access control tokens for each instance: - :: +.. code-block:: nginx location ~ ^/instances/foo/private/ { if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") { @@ -1062,13 +1053,13 @@ Apache For Apache, you should first enable "mod_rewrite": - :: +.. code-block:: console - a2enmod rewrite + $ a2enmod rewrite Then, you can restrict to an access control token using: - :: +.. code-block:: apacheconf <Location "/"> RewriteEngine On @@ -1088,7 +1079,7 @@ If you are running different instances on the same backend, you likely will want to specify different access control tokens for each instance: - :: +.. code-block:: apacheconf <Location "/instances/foo/"> RewriteEngine On @@ -1196,17 +1187,17 @@ manual), and then install the latest version of the code. If you REVOKED database permissions, ensure that the rights to CREATE, DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run: - :: +.. code-block:: console - $ taler-merchant-dbinit + $ taler-merchant-dbinit to upgrade the database to the latest schema. After that, you may again REVOKE the database permissions. Finally, restart the HTTP service, either via your systemd or init system, or directly using: - :: +.. code-block:: console - $ taler-merchant-httpd + $ taler-merchant-httpd .. _Tipping-visitors: @@ -1235,9 +1226,9 @@ First, the reserve must be setup in the merchant backend. A reserve is always tied to a particular instance. To create a reserve with 10 KUDOS at instance "default" using the demo exchange, use: - :: +.. code-block:: console - $ taler-merchant-setup-reserve \ + $ taler-merchant-setup-reserve \ -a KUDOS:10 \ -e https://exchange.demo.taler.net/ \ -m http://localhost:8888/instances/default @@ -1254,7 +1245,7 @@ FIXME: add full example output. In our example, the output for the wire transfer subject is: -:: +.. code-block:: none QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG @@ -1356,7 +1347,7 @@ it under ``$HOME/.config/``. A config file is a text file containing sections, and each section contains its values. The right format follows: -:: +.. code-block:: ini [section1] value1 = string @@ -1375,17 +1366,17 @@ variables that are unset, by using the following syntax: by defining them under a ``[paths]`` section, see example below, -:: +.. code-block:: ini [paths] TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data - .. + ... [section-x] path-x = ${TALER_DEPLOYMENT_SHARED}/x or by setting them in the environment: -:: +.. code-block:: console $ export VAR=/x @@ -1425,7 +1416,7 @@ file format and can also be edited by hand. Run -:: +.. code-block:: console $ taler-config -s $SECTION @@ -1433,7 +1424,7 @@ to list all of the configuration values in section ``$SECTION``. Run -:: +.. code-block:: console $ taler-config -s $section -o $option @@ -1442,7 +1433,7 @@ section ``$section``. Finally, to change a setting, run -:: +.. code-block:: console $ taler-config -s $section -o $option -V $value @@ -1455,7 +1446,7 @@ their value. To expand the ``$DATADIR`` or other ``$``-variables in the configuration, pass the ``-f`` option to ``taler-config``. For example, compare: -:: +.. code-block:: console $ taler-config -s PATHS \ -o TALER_DATA_HOME @@ -1525,10 +1516,10 @@ exist before launching the benchmark. You also will need to ensure that the Exchange's details are setup, usually by running - :: +.. code-block:: console - taler-exchange-wire -c $CONFIG_FILE - taler-exchange-keyup -c $CONFIG_FILE + $ taler-exchange-wire -c $CONFIG_FILE + $ taler-exchange-keyup -c $CONFIG_FILE where "$CONFIG_FILE" should be replaced by the configuration file that is to be used. @@ -1560,7 +1551,7 @@ Any subcommand is also equipped with the canonical ``--help`` option, so feel free to issue the following command in order to explore all the possibilities. For example: -:: +.. code-block:: console $ taler-merchant-benchmark corner --help @@ -1619,14 +1610,14 @@ Because all of the Docker source file are kept in our “deployment“ repository, we start by checking out the ``git://git.taler.net/deployment`` codebase: -:: +.. code-block:: console $ git clone git://git.taler.net/deployment Now we actually build the merchant’s image. From the same directory as above: -:: +.. code-block:: console $ cd deployment/docker/merchant/ $ docker-compose build @@ -1634,7 +1625,7 @@ above: If everything worked as expected, the merchant is ready to be launched. From the same directory as the previous step: -:: +.. code-block:: console # Recall: the docker-machine should be up and running. $ docker-compose up @@ -1646,7 +1637,7 @@ message from postresql about already existing roles and databases. To test if everything worked as expected, it suffices to issue a simple request to the merchant, as: -:: +.. code-block:: console $ curl http://$(docker-machine ip)/ # A greeting message should be returned by the merchant. diff --git a/taler-merchant-pos-terminal.rst b/taler-merchant-pos-terminal.rst index 8bf50315..b81eb33d 100644 --- a/taler-merchant-pos-terminal.rst +++ b/taler-merchant-pos-terminal.rst @@ -86,7 +86,7 @@ Building from source Import in and build with Android Studio or run on the command line: -.. code-block:: sh +.. code-block:: console $ git clone https://git.taler.net/merchant-terminal-android.git $ cd merchant-terminal-android diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst index 81433878..1b3cfb18 100644 --- a/taler-nfc-guide.rst +++ b/taler-nfc-guide.rst @@ -48,7 +48,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. The following :http:post:`/private/orders` request to the merchant backend creates a simple order: - .. code-block:: sh + .. code-block:: console $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' @@ -71,7 +71,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. 2. The merchant checks the payment status of the order using :http:get:`/private/orders/$ORDER_ID`: - .. code-block:: sh + .. code-block:: console $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' @@ -97,7 +97,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. 3. The wallet processes the ``taler://pay/`` URI. In this example, we use the command-line wallet: - .. code-block:: sh + .. code-block:: console # Withdraw some toy money (KUDOS) from the demo bank $ taler-wallet-cli test-withdraw \ @@ -116,7 +116,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests. 4. The merchant checks the payment status again: - .. code-block:: sh + .. code-block:: console $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' diff --git a/taler-wallet.rst b/taler-wallet.rst index d9f9d7fb..18ae0496 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -13,7 +13,7 @@ The command-line wallet is used primarily for testing by developers. Building from source -------------------- -.. code-block:: sh +.. code-block:: console $ git clone https://git.taler.net/wallet-core.git $ cd wallet-core @@ -30,7 +30,7 @@ The wallet can also obtained via NPM, the Node Package Manager. To install the wallet as a global package, run: -.. code-block:: sh +.. code-block:: console $ npm install -g taler-wallet # check if installation was successful @@ -38,7 +38,7 @@ To install the wallet as a global package, run: To install the wallet only for your user, run: -.. code-block:: sh +.. code-block:: console $ npm install -g --prefix=$HOME/local taler-wallet # check if installation was successful @@ -47,7 +47,7 @@ To install the wallet only for your user, run: To use the wallet as a library in your own project, run: -.. code-block:: sh +.. code-block:: console $ npm install taler-wallet @@ -55,7 +55,7 @@ To use the wallet as a library in your own project, run: Manual withdrawing ================== -.. code-block:: sh +.. code-block:: console $ taler-wallet-cli advanced withdraw-manually \ --exchange https://exchange.eurint.taler.net/ \ @@ -67,7 +67,7 @@ WebExtension Wallet Building from source -------------------- -.. code-block:: sh +.. code-block:: console $ git clone https://git.taler.net/wallet-core.git $ cd wallet-core @@ -1093,7 +1093,7 @@ the subcommands. If the database file doesn't exist, it will be created. The following example does a simple withdrawal recoup: -.. code-block:: sh +.. code-block:: console # Withdraw digital cash $ taler-wallet-cli --wallet-db=mydb.json testing withdraw \ @@ -1140,7 +1140,7 @@ The following example does a simple withdrawal recoup: To test refreshing, force a refresh: -.. code-block:: sh +.. code-block:: console $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub" @@ -1148,7 +1148,7 @@ To test refreshing, force a refresh: To test zombie coins, use the timetravel option. It **must** be passed to the top-level command and not the subcommand: -.. code-block:: sh +.. code-block:: console # Update exchange /keys with time travel, value in microseconds $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.json \ |