commit 1f03f5ea5a940186aad160cd01e3f4ffac0e3841 parent d3b4f78d93e4d40845faf7c324df6a40fbe93d96 Author: Christian Grothoff <christian@grothoff.org> Date: Sat, 28 Nov 2020 18:56:50 +0100 Merge branch 'master' of git+ssh://git.taler.net/docs Diffstat:
30 files changed, 358 insertions(+), 326 deletions(-)
diff --git a/anastasis.rst b/anastasis.rst @@ -51,7 +51,7 @@ A **recovery document** includes all of the information a user needs to recover access to their core secret. It specifies a set of **escrow methods**, which specify how the user should convince the Anastasis server that they are "real". Escrow methods can for example include SMS-based -verification, Video-identification or a security question. For each escrow +verification, video identification or a security question. For each escrow method, the Anastasis server is provided with **truth**, that is data the Anastasis operator may learn during the recovery process to authenticate the user. Examples for truth would be a phone number (for SMS), a picture of the @@ -136,9 +136,9 @@ information as the **identifier**. This identifier will be first hashed with Argon2, to provide a **kdf_id** which will be used to derive other keys later. The Hash must also include the respective **server_salt**. This also ensures that the **kdf_id** is different -on each server. The use of Argon2 and the respective server_salt is intended -to make it difficult to brute-force **kdf_id** values and help protect user's -privacy. Also this ensures that the kdf_ids on every server differs. However, +on each server. The use of Argon2 and the respective **server_salt** is intended +to make it difficult to brute-force **kdf_id** values and help protect the user's +privacy. Also this ensures that the **kdf_id**\ s on every server differs. However, we do not assume that the **identifier** or the **kdf_id** cannot be determined by an adversary performing a targeted attack, as a user's **identifier** is likely to always be known to state actors and may @@ -151,7 +151,7 @@ likely also be available to other actors. **identifier**: The secret defined from the user beforehand. -**server_salt**: The salt from the Server +**server_salt**: The salt from the Server. **keysize**: The desired output size of the KDF, here 32 bytes. @@ -162,7 +162,7 @@ Verification For users to authorize "policy" operations we need an EdDSA key pair. As we cannot assure that the corresponding private key is truly secret, such policy operations must never be destructive: Should an adversary learn the private -key, they could access (and with the kdf_id decrypt) the user's policy (but +key, they could access (and with the **kdf_id** decrypt) the user's policy (but not the core secret), or upload a new version of the **encrypted recovery document** (but not delete an existing version). @@ -175,7 +175,7 @@ HKDF to ensure that the result differs from other cases where we hash :: - ver_secret:= HKDF(kdf_id, "ver", keysize) + ver_secret := HKDF(kdf_id, "ver", keysize) eddsa_priv := eddsa_d_to_a(ver_secret) eddsa_pub := get_EdDSA_Pub(eddsa_priv) @@ -186,7 +186,7 @@ HKDF to ensure that the result differs from other cases where we hash **key_size**: Size of the output, here 32 bytes. -**ver_secret**: Derived key from the kdf_id, serves as intermediate step for the generation of the private key +**ver_secret**: Derived key from the kdf_id, serves as intermediate step for the generation of the private key. **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: @@ -214,11 +214,11 @@ key material using an HKDF over a nonce and the kdf_id. **HKDF()**: The HKDF-function uses two phases: First we use HMAC-SHA512 for the extraction phase, then HMAC-SHA256 is used for expansion phase. -**kdf_id**: Hashed identifier +**kdf_id**: Hashed identifier. -**keysize**: Size of the AES symmetric key, here 32 bytes +**keysize**: Size of the AES symmetric key, here 32 bytes. -**ivsize**: Size of the AES GCM IV, here 12 bytes +**ivsize**: Size of the AES GCM IV, here 12 bytes. **prekey**: Original key material. @@ -227,7 +227,7 @@ avoid key reuse. So, we have to use different nonces to get different keys and i **key**: Symmetric key which is later used to encrypt the documents with AES256-GCM. -**iv**: IV which will be used for AES-GCM +**iv**: IV which will be used for AES-GCM. --------- @@ -267,7 +267,7 @@ Nonce must contain the string "ERD". 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 +**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 the same number as specified above for *encrypted_key_share_i*. Nonce must contain the string "EKS" plus the according *i*. Signatures @@ -282,7 +282,7 @@ algorithm is equivalent for **Anastasis-Policy-Signature**. (anastasis-account-signature) = eddsa_sign(h_body, eddsa_priv) ver_res = eddsa_verifiy(h_body, anastasis-account-signature, eddsa_pub) -**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code TALER_SIGNATURE_ANASTASIS_POLICY_UPLOAD (1400) (see GNUnet EdDSA signature API for the use of purpose) +**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_UPLOAD`` (1400) (see GNUnet EdDSA signature API for the use of purpose). **h_body**: The hashed body. @@ -296,7 +296,7 @@ When requesting policy downloads, the client must also provide a signature: (anastasis-account-signature) = eddsa_sign(version, eddsa_priv) ver_res = eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) -**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD (1401) (see GNUnet EdDSA signature API for the use of purpose) +**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401) (see GNUnet EdDSA signature API for the use of purpose). **version**: The version requested as a 64-bit integer, 2^64-1 for the "latest version". @@ -309,7 +309,7 @@ Availability Considerations Anastasis considers two main threats against availability. First, the Anastasis server operators must be protected against denial-of-service attacks -where an adversary attempts to exhaust operator's resources. The API protects +where an adversary attempts to exhaust the operator's resources. The API protects against these attacks by allowing operators to set fees for all operations. Furthermore, all data stored comes with an expiration logic, so an attacker cannot force servers to store data indefinitely. @@ -448,10 +448,10 @@ Manage policy This API is used by the Anastasis client to deposit or request encrypted recovery documents with the escrow provider. Generally, a client will deposit the same encrypted recovery document with each escrow provider, but provide -different truth to each escrow provider. +a different truth to each escrow provider. -Operations by the client are identified and authorized by $ACCOUNT_PUB, which -should be kept secret from third parties. $ACCOUNT_PUB should be an account +Operations by the client are identified and authorized by ``$ACCOUNT_PUB``, which +should be kept secret from third parties. ``$ACCOUNT_PUB`` should be an account public key using the Crockford base32-encoding. In the following, UUID is always defined and used according to `RFC 4122`_. @@ -501,18 +501,18 @@ In the following, UUID is always defined and used according to `RFC 4122`_. *Etag*: Set by the server to the Base32-encoded SHA512 hash of the body. Used for caching and to prevent redundancies. The server MUST send the Etag if the status code is 200 OK. - *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has reveived before from the server. + *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has received before from the server. The client SHOULD send this header with every request (except for the first request) to avoid unnecessary downloads. - *Anastasis-Account-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to download the requested encrypted recovery document. The purpose used MUST be TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD (1401). + *Anastasis-Account-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to download the requested encrypted recovery document. The purpose used MUST be ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401). .. http:post:: /policy/$ACCOUNT_PUB 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). - If request has been seen before, the server should do nothing, and otherwise store the new version. + should just be the bytestream of the raw data (i.e. 32-byte nonce followed + by 16-byte tag followed by the encrypted document). + If the 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 Anastasis server cannot fully validate the format, but MAY impose @@ -534,18 +534,18 @@ In the following, UUID is always defined and used according to `RFC 4122`_. case. *If-Match*: Unless the client expects to upload the first encrypted recovery document to this account, the client - SHOULD provide an Etag matching the latest version already known to the server. If this - header is present, the server MUST refuse the upload if the latest known version prior to - this upload does not match the given Etag. + SHOULD provide an Etag matching the latest version already known to the server. If this + header is present, the server MUST refuse the upload if the latest known version prior to + this upload does not match the given Etag. *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client. - The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue" - before uploading the body. The server MUST - use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded. - The server MUST refuse the upload with a "304" status code if the Etag matches - the latest version already known to the server. + The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue" + before uploading the body. The server MUST + use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded. + The server MUST refuse the upload with a "304" status code if the Etag matches + the latest version already known to the server. - *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to upload an encrypted recovery document. + *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to upload an encrypted recovery document. *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see 402 status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a 402 response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. @@ -553,12 +553,12 @@ In the following, UUID is always defined and used according to `RFC 4122`_. :http:statuscode:`204 No content`: The encrypted recovery document was accepted and stored. "Anastasis-Version" and "Anastasis-UUID" headers - incidate what version and UUID was assigned to this encrypted recovery document upload by the server. + indicate what version and UUID was assigned to this encrypted recovery document upload by the server. :http:statuscode:`304 Not modified`: The same encrypted recovery document was previously accepted and stored. "Anastasis-Version" header - incidates what version was previously assigned to this encrypted recovery document. + indicates what version was previously assigned to this encrypted recovery document. :http:statuscode:`400 Bad request`: - The $ACCOUNT_PUB is not an EdDSA public key or mandatory headers are missing. + The ``$ACCOUNT_PUB`` is not an EdDSA public key or mandatory headers are missing. The response body MUST elaborate on the error using a Taler error code in the typical JSON encoding. :http:statuscode:`402 Payment required`: The account's balance is too low for the specified operation. @@ -673,7 +673,7 @@ the escrow provider. An **escrow method** specifies an Anastasis provider and how the user should authorize themself. The **truth** API allows the user to provide the (encrypted) key share to the respective escrow provider, as well as auxiliary -data required for such an respective escrow method. +data required for such a respective escrow method. An Anastasis-server may store truth for free for a certain time period, or charge per truth operation using GNU Taler. @@ -736,10 +736,10 @@ 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). + 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). 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. + 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. **Response**: @@ -766,7 +766,7 @@ charge per truth operation using GNU Taler. Server is out of Service. *Truth-Decryption-Key*: Key used to encrypt the **truth** (see encrypted_truth within TruthUploadRequest_) and which has to provided by the user. The key is stored with - the according EscrowMethod_. The server needs this key to get the info out of TruthUploadRequest_ needed to verify the $RESPONSE. + the according EscrowMethod_. The server needs this key to get the info out of TruthUploadRequest_ needed to verify the ``$RESPONSE``. **Details:** @@ -2616,7 +2616,7 @@ SMS (sms) ^^^^^^^^^ Sends an SMS with a code to the users phone. -The user must send this code back with his request (see $RESPONSE under 'Managing truth'). +The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_). If the transmitted code is correct, the server responses with the requested encrypted key share. FIXME: details! @@ -2624,7 +2624,7 @@ FIXME: details! Email verification (email) ^^^^^^^^^^^^^^^^^^^^^^^^^^ Sends an email with a code to the users mail address. -The user must send this code back with his request (see $RESPONSE under 'Managing truth'). +The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_). If the transmitted code is correct, the server responses with the requested encrypted key share. FIXME: details! diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst @@ -134,7 +134,7 @@ manages payment initiations of the account and tracks the initiations of payment Ask nexus to submit one prepare payment at the bank. :http:statuscode:`404 Not found`: the unique identifier **or** - the bank connection could not be found in the system + the bank connection could not be found in the system .. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid} @@ -178,7 +178,7 @@ manages payment initiations of the account and tracks the initiations of payment .. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations Ask nexus the list of initiated payments. At this stage of the API, - **all** is returned: submitted and non submitted payments. + **all** is returned: submitted and non-submitted payments. **Response** @@ -276,9 +276,9 @@ manages payment initiations of the account and tracks the initiations of payment **Query parameters:** * **start** start (dashed YYYY-MM-DD) date of desired payments. - Optional, defaults to "earliest possible" date + Optional, defaults to "earliest possible" date. * **end** end (dashed YYYY-MM-DD) date of desired payments. - Optional, defaults to "earliest possible" date + Optional, defaults to "earliest possible" date. **Response:** A list of `Transaction` objects. diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst @@ -19,7 +19,7 @@ HTTP API .. ts:def:: PaymentRequest interface PaymentRequest { - + // IBAN that will receive the payment. creditorIban: string; @@ -37,7 +37,7 @@ HTTP API Host management. .. http:post:: /admin/ebics/hosts - + Creates a new Ebics host. **Request:** @@ -45,32 +45,31 @@ HTTP API .. ts:def:: EbicsHostRequest interface EbicsHostRequest { - + // Ebics version. hostID: string; // Name of the host. ebicsVersion: string; } - + .. http:get:: /admin/ebics/hosts - - Shows the list of all the hosts existing - in the system. + + Shows the list of all the hosts in the system. **Response:** .. ts:def:: EbicsHostResponse interface EbicsHostResponse { - + // shows the host IDs that are active in the system. // The Ebics version *is* missing, but it's still available // via the HEV message. ebicsHosts: string[]; } - + .. Subscriber management. @@ -84,7 +83,7 @@ HTTP API .. ts:def:: SubscriberRequest interface SubscriberRequest { - + // hostID hostID: string; @@ -98,26 +97,25 @@ HTTP API systemID: string; } - + .. http:get:: /admin/ebics/subscribers - Shows the list of all the subscribers existing - in the system. + Shows the list of all the subscribers in the system. **Response:** .. ts:def:: SubscribersResponse interface SubscribersResponse { - + subscribers: Subscriber[] } - + .. ts:def:: Subscriber interface Subscriber { - + // userID userID: string; diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst @@ -24,26 +24,26 @@ The following steps are required to set up an EBICS bank transport: 3. The LibEuFin nexus generates cryptographic key material (3 RSA key pairs). -5. The nexus sends the public keys electronically to the bank's EBICS server, together with the information +4. The nexus sends the public keys electronically to the bank's EBICS server, together with the information identifying the subscriber (PartnerID, UserID, SystemID). -6. The user prints a document that contains the public key and hashes for all three key pairs. +5. The user prints a document that contains the public key and hashes for all three key pairs. The user then signs this document and sends it to the bank (physically/scanned). -7. The bank receives the letter and verifies that the keys from the letter correspond +6. The bank receives the letter and verifies that the keys from the letter correspond to the electronically sent keys. If they match, the bank sets the state of the subscriber to "ready". -8. The user now has to wait until the bank has set the EBICS subscriber state to "ready". +7. The user now has to wait until the bank has set the EBICS subscriber state to "ready". There is no in-band notification for this, but the Nexus can try downloading the bank's cryptographic parameters. This will only succeed once the EBICS subscriber is set to "ready" by the bank. -9. The user should confirm the public keys of the bank received in the previous step. +8. The user should confirm the public keys of the bank received in the previous step. Typically the bank gives the value of these public keys in an out-of-band channel. -10. Now the user can finally use the EBICS bank transport. The first step after finishing - the setup should be to import the bank accounts accessible for this EBICS subscriber. +9. Now the user can finally use the EBICS bank transport. The first step after finishing + the setup should be to import the bank accounts accessible for this EBICS subscriber. Alternative ways of setting up the EBICS bank transport are: diff --git a/libeufin/banking-protocols.rst b/libeufin/banking-protocols.rst @@ -111,7 +111,7 @@ Open Bank Project The `Open Bank Project <https://www.openbankproject.com/>`__ provides a free software implementation of banking middleware that supports various APIs, including PSD2-compatible APIs (based on Berlin Group). -API Docs: https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture +API Docs: `<https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture>`__ UK Open Banking @@ -122,4 +122,4 @@ Open Banking is the (quite confusing!) name of a UK-based open banking initiativ What's nice about Open Banking is that their APIs are really close to ISO 20022, unlike many similar HTTP+JSON APIs. -https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications +`<https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications>`__ diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst @@ -58,13 +58,13 @@ EBICS Glossary FTAM Historical predecessor protocol to EBICS (*file transfer, access and management*). - + HEV The *Host EBICS Version*. Queried by the client with an HEV request message. Human Subscriber - See :term:`Subscriber`. + See :term:`Subscriber`. H004 Host protocol version 4. Refers to the XML Schema defined in *EBICS 2.5*. @@ -84,7 +84,7 @@ EBICS Glossary The Order Number is used to match VEUs in a second upload to the original order. An Order Number matches the format ``[A-Z][A-Z0-9]{3}`` (and is not really a number!). - Must be unique per customer ID and per order type + Must be unique per customer ID and per order type. Transaction ID A transaction ID is a 128-bit cryptographically strong random number. @@ -100,7 +100,7 @@ EBICS Glossary Partner ID In German, this is called "Kunden ID" (= Customer ID). One partner can have multiple "participants", which are identified by user IDs. - + Practical example: A company has one Partner ID. Each person at the company that can access the company's bank accounts gets their own User ID. When the person is indirectly accessing the bank server (for example via @@ -131,7 +131,7 @@ EBICS Glossary EBICS implements its own protocol-level segmentation of business-related messages. The segmentation can be seen as an alternative to the HTTP facilities of ``Accept-Ranges``. - The order data of an ebics message may not exceed 1 MB. The segmentation applies both + The order data of an EBICS message may not exceed 1 MB. The segmentation applies both to requests and responses. Subscriber @@ -145,7 +145,7 @@ EBICS Glossary and ``UserId``. A technical subscriber cannot sign a bank-technical request. Technical Subscriber - See :term:`Subscriber`. + See :term:`Subscriber`. TLS *Transport Layer Security*. All messages in EBICS are sent over HTTP with TLS. @@ -178,11 +178,11 @@ Relevant Order Types BTD **Only EBICS3.0+**. Business Transaction Format Download. - Administrative order type to download a file, described in more detail by the BTF structure + Administrative order type to download a file, described in more detail by the BTF structure. BTU **Only EBICS3.0+**. Business Transaction Format Upload. - Administrative order type to upload a file, described in more detail by the BTF structure + Administrative order type to upload a file, described in more detail by the BTF structure. C52 **Before EBICS 3.0**. Download bank-to-customer account report (intra-day information). @@ -193,19 +193,19 @@ Relevant Order Types CRZ Type: Download. - Fetch payment status report (pain.002) + Fetch payment status report (pain.002). CCC Type: Upload. Send SEPA Credit Transfer Initiation (pain.001) via XML container. - This is the DFÜ variant (Appendix 3 DFÜ-Agreement) + This is the DFÜ variant (Appendix 3 DFÜ-Agreement). CCT Type: Upload. Send SEPA Credit Transfer Initiation (pain.001) directly. - This is the DFÜ variant (Appendix 3 DFÜ-Agreement) + This is the DFÜ variant (Appendix 3 DFÜ-Agreement). CIZ Type: Download. @@ -219,19 +219,19 @@ Relevant Order Types **Before EBICS 3.0, France**. File Download. Mainly used by France-style EBICS. HAA - Type: Download, Optional + Type: Download, Optional. - Download order types for which there is new data available. + Download order types for which there is new data available. HTD - Type: Download + Type: Download. - Download information about a subscriber. From German "Teilnehmerdaten". + Download information about a subscriber. From German "Teilnehmerdaten". HKD - Type: Download, Optional + Type: Download, Optional. - Download information about a customer (=partner). From German "Kundendaten". + Download information about a customer (=partner). From German "Kundendaten". HIA Transmission of the subscriber keys for (1) identification and authentication and (2) @@ -376,7 +376,7 @@ type. Each transaction is either an upload transaction or a download transaction, neither both. Uploads and downloads must proceed in segments of at most ``1 MB``. The -segmentation happens after (1) encryption (2) zipping and (3) base64-encoding +segmentation happens after (1) encryption, (2) zipping, and (3) base64-encoding of the order data. The number of segments is always fixed starting from the first message sent @@ -398,7 +398,7 @@ are some conditions for that: * Segment ``n`` can only be downloaded/uploaded when segments ``[0..n-1]`` have been downloaded/uploaded. -* The (implementation-defined) retry counter may not be exceeded. +* The (implementation-defined) retry limit may not be exceeded. Formats @@ -407,7 +407,7 @@ Formats ISO 20022 --------- -ISO 20022 is XML-based and defines message format for many finance-related activities. +ISO 20022 is XML-based and defines the message format for many finance-related activities. ISO 20022 messages are identified by a message identifier in the following format: @@ -431,17 +431,17 @@ SWIFT Proprietary ================= SWIFT Proprietary messages are in a custom textual format. -The relevant messages are MT940 and MT942 +The relevant messages are MT940 and MT942. * MT940 contains *pre-advice*, in the sense that transactions in it might still - change or be reversed -* MT942 contains the settled transactions by the end of the day + change or be reversed. +* MT942 contains the settled transactions by the end of the day. SWIFT will eventually transition from MT messages to ISO20022, but some banks might still only give us account statements in the old SWIFT format. - + Key Management ============== @@ -523,11 +523,12 @@ Cryptography EBICS uses the XML Signature standard for signatures. It does *not* use XML encryption. The EBICS specification doesn't directly reference the standardized URIs for the various -signing algorithms. Some of these URIs are defined in `<https://tools.ietf.org/html/rfc6931>`__. +signing algorithms. Some of these URIs are defined +in `RFC 6931 <https://tools.ietf.org/html/rfc6931>`__. -* A005 is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 +* A005 is `<http://www.w3.org/2001/04/xmldsig-more#rsa-sha256>`__. - * the ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme + * The ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme mentioned in the EBICS spec. * A006 is `<http://www.w3.org/2007/05/xmldsig-more#rsa-pss>`__ as defined in RFC 6931. @@ -546,7 +547,7 @@ In EBICS, only **enveloped** signatures are used. In the XML Signature standard, the element for a signature is ``Signature``. EBICS violates this standard by always mandating ``AuthSignature`` as the name. ``AuthSignature`` is an alias to -the ``SignatureType`` xsd type in the XML Schema. +the ``SignatureType`` XSD type in the XML Schema. Canonicalization vs transforms: * Canonicalization refers to the processing of the ``SignedInfo`` element. @@ -592,5 +593,3 @@ Others * `<https://wiki.windata.de/index.php?title=EBICS-Auftragsarten>`_ * `<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_ - - diff --git a/libeufin/frontend.rst b/libeufin/frontend.rst @@ -42,4 +42,4 @@ Shows activity of payments and its transaction history (WIP). /components/bank-accounts ------------------------- -Shows bank accounts that are imported. A bank account drawer is shown to facilitate setting up of bank accounts. Each bank account is displayed in a card to display extra details for e.g its' print document. +Shows bank accounts that are imported. A bank account drawer is shown to facilitate setting up of bank accounts. Each bank account is displayed in a card to display extra details for e.g its print document. diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst @@ -5,15 +5,15 @@ ISO 20022 is the standard that defines many XML messages for FinTech. It is very general, and often countries/orgs define subsets (TVS, technical validation subset) of the schema. -Documentation for message fields can be viewed at https://www.iso20022.org/standardsrepository +Documentation for message fields can be viewed at `<https://www.iso20022.org/standardsrepository>`__. The primary syntax for ISO 20022 messages is XML. To avoid LibEuFin clients having to deal with XML, we define a mapping from ISO 20022 messages into JSON. The specifics of this mapping are: - * The JSON should be "idiomatic" and easy to process - * When possible, the highly nested structures of ISO 20022 should be flattened + * The JSON should be "idiomatic" and easy to process. + * When possible, the highly nested structures of ISO 20022 should be flattened. * It must be possible round-trip between the LibEuFin JSON and ISO 20022 XML messages. The mapping of message types is not 1-to-1, as some ISO 20022 messages are very similar and can be mapped to the same JSON structure. @@ -36,7 +36,7 @@ Reasons for not using ISO 20022 directly are: to JSON, they are difficult to use due to their verbosity. 3. Underspecification. Messages like camt.05x leave many "degrees of freedom" when translating the underlying data into a message. -4. No interoperability. As a result of underspecification, different countries/organisations +4. No interoperability. As a result of underspecification, different countries/organizations define their own subset and interpretation rules for ISO 20022 messages. This can lead to even contradictory usage rules. An example for this is how the Swiss and EPC interpretations handle transaction amounts in the presence of multiple currencies. @@ -209,4 +209,3 @@ FIXME: This is not complete yet. proprietaryIssuer?: string; proprietaryCode?: string; } - diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst @@ -6,16 +6,19 @@ Nexus How-To Nexus is a Web service that provides a JSON abstraction layer to access bank accounts. It is **not** itself a bank, but a translator between JSON requests and more structured banking protocols (like -EBICS, for example.), that are offered by actual banks. +EBICS, for example), that are offered by actual banks. -This document explains how to setup Nexus to access a bank account +This document explains how to set up Nexus to access a bank account via the EBICS protocol. In order to follow all the steps below, the reader should already have one EBICS subscriber activated at their bank. Obtain Nexus ============ Nexus belongs to the LibEuFin project, and can be downloaded via Git: -``$ git clone git://git.taler.net/libeufin`` + +.. code-block:: shell + + $ git clone git://git.taler.net/libeufin Note that Kotlin+Gradle should already work on the host system. @@ -47,7 +50,7 @@ Use the following command to *(1) run the nexus service*: After the startup, Nexus should have created a ``.sqlite3`` file in its current working directory. Feel free to use the ``--with-db`` option to change the database name and path. In future releases, the support -for Postgresql will be provided. +for PostgreSQL will be provided. At this point a *(2) superuser account needs to be activated into the system*: @@ -58,18 +61,18 @@ into the system*: For simplicity, we'll enable the superuser to access the bank account via the EBICS protocol, but a API to create less privileged users is -as well offered. +offered as well. Nexus needs now to associate the user to a EBICS subscriber that was activated on the bank. In the Nexus terminology, this is called *(3) creating a EBICS connection*. .. note:: - + The command line interface needs the following three values - to be defined into the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``, - and ``NEXUS_PASSWORD``. In this example, NEXUS_USERNAME should be - set to ``foo``, and NEXUS_PASSWORD to the value given for its password + to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``, + and ``NEXUS_PASSWORD``. In this example, ``NEXUS_USERNAME`` should be + set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password in step (2). .. code-block:: shell @@ -205,7 +208,7 @@ 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 - + libeufin-cli \ accounts \ submit-payment \ diff --git a/libeufin/transaction-identification.rst b/libeufin/transaction-identification.rst @@ -16,7 +16,7 @@ ISO 20022 camt.05X ------------------ The camt52/53/54 messages defined by ISO 20022 do not have a mandatory transaction -identifier. Instead if defines a handful of optional references. +identifier. Instead it defines a handful of optional references. Two identifiers seem to be used in practice: The *Account Servicer Reference* and the *Entry Reference*. Of these, only the *Account Servicer Reference* seems to be useful @@ -65,7 +65,7 @@ LibEuFin intends to solve this problem in the following ways: the status (booked, pending, info) is examined: 1. When the status is booked, an error is reported, and corresponding bank message - will be made available for review + will be made available for review. 2. When the status is "pending" or "info", the entry will simply be ignored. In the future, this might be extended to be less restrictive: diff --git a/manpages/taler-auditor-dbinit.1.rst b/manpages/taler-auditor-dbinit.1.rst @@ -13,8 +13,11 @@ Synopsis ======== **taler-auditor-dbinit** -[**-h** | **–help**] [**-g** | **–gc**] [**-R** | **–reset**] [**-r** | **–restart**] -[**-v** | **–version**] +[**-h** | **––help**] +[**-g** | **––gc**] +[**-R** | **––reset**] +[**-r** | **––restart**] +[**-v** | **––version**] Description =========== @@ -25,25 +28,25 @@ Taler exchange to operate. Its options are as follows: -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-g** \| **–gc** +**-g** \| **––gc** Garbage collect database. Deletes all unnecessary data in the database. -**-R** \| **–reset** +**-R** \| **––reset** Drop tables. Dangerous, will delete all existing data in the database. -**-r** \| **--restart** +**-r** \| **––restart** Restart all auditors from the beginning. Useful for testing. -**-v** \| **–version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-auditor-exchange.1.rst b/manpages/taler-auditor-exchange.1.rst @@ -11,9 +11,11 @@ taler-auditor-exchange(1) Synopsis ======== -**taler-auditor-exchange** [**-h** | **--help**] [**-r** | **--remove**] -[**-m** *MASTERKEY* | **--exchange-key=**\ \ *MASTERKEY*] -[**-u** *EXCHANGE_URL* | **--auditor-url=**\ \ *EXCHANGE_URL*] +**taler-auditor-exchange** +[**-h** | **––help**] +[**-r** | **––remove**] +[**-m** *MASTERKEY* | **––exchange-key=**\ \ *MASTERKEY*] +[**-u** *EXCHANGE_URL* | **––auditor-url=**\ \ *EXCHANGE_URL*] Description =========== @@ -25,18 +27,18 @@ denomination keys with taler-auditor-sign or trying to audit it with taler-auditor or taler-wire-auditor. Afterwards the exchange will be visible via the /exchanges API of the taler-auditor-httpd. -**-m** *MASTERKEY* \| **--exchange-key=**\ \ *MASTERKEY* +**-m** *MASTERKEY* \| **––exchange-key=**\ \ *MASTERKEY* Public key of the exchange in Crockford base32 encoding, for example as generated by gnunet-ecc -p. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-u** *EXCHANGE_URL* \| **--auditor-url=**\ \ *EXCHANGE_URL* +**-u** *EXCHANGE_URL* \| **––auditor-url=**\ \ *EXCHANGE_URL* URL of the exchange. The exchange’s HTTP API must be available at this address. -**-r** \| **--remove** +**-r** \| **––remove** Instead of adding the exchange, remove it. Note that this will drop ALL data associated with that exchange, including existing auditing information. So use with extreme care! diff --git a/manpages/taler-auditor-sign.1.rst b/manpages/taler-auditor-sign.1.rst @@ -11,11 +11,13 @@ taler-auditor-sign(1) Synopsis ======== -**taler-auditor-sign** [**-a** *FILE* | **--auditor-key=**\ \ *FILE*] -[**-h** | **--help**] [**-m** *KEY* | **--exchange-key=**\ \ *KEY*] -[**-u** *URL* | **--auditor-url=**\ \ *URL*] -[**-r** *FILE* | **--exchange-request=**\ \ *FILE*] -[**-o** *FILE* | **--output=**\ \ *FILE*] +**taler-auditor-sign** +[**-a** *FILE* | **––auditor-key=**\ \ *FILE*] +[**-h** | **––help**] +[**-m** *KEY* | **––exchange-key=**\ \ *KEY*] +[**-u** *URL* | **––auditor-url=**\ \ *URL*] +[**-r** *FILE* | **––exchange-request=**\ \ *FILE*] +[**-o** *FILE* | **––output=**\ \ *FILE*] Description =========== @@ -28,26 +30,26 @@ exchange is properly accounting for those coins. The exchange for which keys were signed must have been added to the auditor using taler-auditor-exchange first! -**-a** *FILE* \| **--auditor-key=**\ \ *FILE* +**-a** *FILE* \| **––auditor-key=**\ \ *FILE* Location of the private EdDSA auditor key. If it does not exist, it will be created. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-m** *KEY* \| **--exchange-key=**\ \ *KEY* +**-m** *KEY* \| **––exchange-key=**\ \ *KEY* Public key of the exchange in Crockford base32 encoding, for example as generated by gnunet-ecc -p. -**-u** *URL* \| **--auditor-url=**\ \ *URL* +**-u** *URL* \| **––auditor-url=**\ \ *URL* URL of the auditor. Provides informative link for the user to learn more about the auditor. -**-r** *FILE* \| **--exchange-request=**\ \ *FILE* +**-r** *FILE* \| **––exchange-request=**\ \ *FILE* File with the exchange’s denomination key signing request as generated by taler-exchange-keyup -o. -**-o** *FILE* \| **--output=**\ \ *FILE* +**-o** *FILE* \| **––output=**\ \ *FILE* File where the auditor should write the EdDSA signature. See Also diff --git a/manpages/taler-auditor.1.rst b/manpages/taler-auditor.1.rst @@ -11,8 +11,9 @@ taler-auditor(1) Synopsis ======== -**taler-auditor** [**-h** | **--help**] -[**-m** *MASTER_KEY* | **--exchange-key=**\ \ *MASTER_KEY*] +**taler-auditor** +[**-h** | **––help**] +[**-m** *MASTER_KEY* | **––exchange-key=**\ \ *MASTER_KEY*] Description @@ -28,10 +29,10 @@ found in the database. It does NOT check with the bank to see that the incoming and outgoing wire transfers that the bank claims to have matches the exchange’s database. Its options are as follows. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-m** *KEY* \| **--exchange-key=**\ \ *KEY* +**-m** *KEY* \| **––exchange-key=**\ \ *KEY* Public master key of the exchange in Crockford base32 encoding, for example as generated by gnunet-ecc -p. If this option is missing, taler-auditor will use the MASTER_PUBLIC_KEY value from the diff --git a/manpages/taler-bank-transfer.1.rst b/manpages/taler-bank-transfer.1.rst @@ -12,20 +12,20 @@ Synopsis ======== **taler-bank-transfer** -[**-a** *VALUE* | **--amount=**\ \ *VALUE*] -[**-b** *URL* | **--bank=**\ \ *URL*] -[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] -[**-C** *ACCOUNT* | **--credit=**\ \ *ACCOUNT*] -[**-D** *ACCOUNT* | **--debit=**\ \ *ACCOUNT*] -[**-h** | **--help**] -[**-i** | **--credit-history**] -[**-o** | **--debit-history**] -[**-p** *PASSPHRASE* | **--pass=**\ \ *PASSPHRASE*] -[**-s** *ACCOUNT-SECTION* | **--section=**\ \ *ACCOUNT-SECTION*] -[**-S** *STRING* | **--subject=**\ \ *STRING*] -[**-u** *USERNAME* | **--user=**\ \ *USERNAME*] -[**-v** | **--version**] -[**-w** *ROW* | **--since-when=**\ \ *ROW*] +[**-a** *VALUE* | **––amount=**\ \ *VALUE*] +[**-b** *URL* | **––bank=**\ \ *URL*] +[**-c** *FILENAME* | **––config=**\ \ *FILENAME*] +[**-C** *ACCOUNT* | **––credit=**\ \ *ACCOUNT*] +[**-D** *ACCOUNT* | **––debit=**\ \ *ACCOUNT*] +[**-h** | **––help**] +[**-i** | **––credit-history**] +[**-o** | **––debit-history**] +[**-p** *PASSPHRASE* | **––pass=**\ \ *PASSPHRASE*] +[**-s** *ACCOUNT-SECTION* | **––section=**\ \ *ACCOUNT-SECTION*] +[**-S** *STRING* | **––subject=**\ \ *STRING*] +[**-u** *USERNAME* | **––user=**\ \ *USERNAME*] +[**-v** | **––version**] +[**-w** *ROW* | **––since-when=**\ \ *ROW*] Description =========== @@ -49,51 +49,51 @@ on transaction history operations. Options ======= -**-a** *VALUE* \| **--amount=**\ \ *VALUE* +**-a** *VALUE* \| **––amount=**\ \ *VALUE* Amount to transfer. Given in the Taler-typical format of CURRENCY:VALUE.FRACTION. -**-b** *URL* \| **--bank=**\ \ *URL* +**-b** *URL* \| **––bank=**\ \ *URL* URL at which the bank is operation. Conflicts with **-s**. -**-c** *FILENAME* \| **--config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the given configuration file. -**-C** *ACCOUNT* \| **--credit=**\ \ *ACCOUNT* +**-C** *ACCOUNT* \| **––credit=**\ \ *ACCOUNT* When doing a wire transfer from the exchange, the money should be credited to *ACCOUNT*. Specifies the payto:// URI of the account. Can also be used as a filter by credit account when looking at transaction histories. -**-D** *ACCOUNT* \| **--debit=**\ \ *ACCOUNT* +**-D** *ACCOUNT* \| **––debit=**\ \ *ACCOUNT* When doing a wire transfer to the exchange, the *ACCOUNT* is to be debited. Specifies the payto:// URI of the account. Can also be used as a filter by debit account when looking at transaction histories. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-i** \| **--credit-history** +**-i** \| **––credit-history** Obtain credit history of the exchange. Conflicts with **-o**. -**-o** \| **--debit-history** +**-o** \| **––debit-history** Obtain debit history of the exchange. Conflicts with **-i**. -**-S** *SUBJECT* \| **--subject=**\ \ *SUBJECT* +**-S** *SUBJECT* \| **––subject=**\ \ *SUBJECT* Use *SUBJECT* for the wire transfer subject. Must be a reserve public key for credit operations and a wire transfer identifier for debit operations. If not specified, a random value will be generated instead. -**-s** *ACCOUNT_SECTION* \| **--section=**\ \ *ACCOUNT-SECTION* +**-s** *ACCOUNT_SECTION* \| **––section=**\ \ *ACCOUNT-SECTION* Obtain exchange account information from the *ACCOUNT-SECTION* of the configuration. Conflicts with **-u**, **-p** and **-b**. Note that either **-b** or **-s** must be specified. -**-u** *USERNAME* \| **--user=**\ \ *USERNAME* +**-u** *USERNAME* \| **––user=**\ \ *USERNAME* Specifies the username for authentication. Optional and conflicts with **-s**. If neither **-u** nor **-s** are used, we will attempt to talk to the bank without authentication. -**-p** *PASSPHRASE* \| **--pass=**\ \ *PASSPHRASE* +**-p** *PASSPHRASE* \| **––pass=**\ \ *PASSPHRASE* Specifies the pass phrase for authentication. Conflicts with **-s**. -**-v** \| **--version** +**-v** \| **––version** Print version information. -**-w** *ROW* \| **--since-when=**\ \ *ROW* +**-w** *ROW* \| **––since-when=**\ \ *ROW* Specifies a *ROW* from which the history should be obtained. If not given, the 10 youngest transactions are returned. diff --git a/manpages/taler-config-generate.1.rst b/manpages/taler-config-generate.1.rst @@ -13,17 +13,21 @@ Synopsis ======== **taler-config-generate** -[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] -[**-C** *CURRENCY* | **--currency=**\ \ *CURRENCY*] -[**-e** | **--exchange**] [**-f** *AMOUNT* | *-wirefee=*\ \ *AMOUNT*] -[**-m** | **--merchant**] [**-t** | **--trusted**] -[**-w** *WIREFORMAT* | **--wire** *WIREFORMAT*] -[**-j** *JSON* | **--wire-json-merchant=**\ \ *JSON*] -[**-J** *JSON* | **--wire-json-exchange=**\ \ *JSON*] [**--bank-uri**] -[**--exchange-bank-account**] [**--merchant-bank-account**] -[**-h** | **--help**] -[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] -[**-v** | **--version**] +[**-c** *FILENAME* | **––config=**\ \ *FILENAME*] +[**-C** *CURRENCY* | **––currency=**\ \ *CURRENCY*] +[**-e** | **––exchange**] +[**-f** *AMOUNT* | *––wirefee=*\ \ *AMOUNT*] +[**-m** | **––merchant**] +[**-t** | **––trusted**] +[**-w** *WIREFORMAT* | **––wire** *WIREFORMAT*] +[**-j** *JSON* | **––wire-json-merchant=**\ \ *JSON*] +[**-J** *JSON* | **––wire-json-exchange=**\ \ *JSON*] +[**––bank-uri**] +[**––exchange-bank-account**] +[**––merchant-bank-account**] +[**-h** | **––help**] +[**-L** *LOGLEVEL* | **––loglevel=**\ \ *LOGLEVEL*] +[**-v** | **––version**] Description =========== @@ -31,59 +35,59 @@ Description **taler-config-generate** can be used to generate configuration files for the Taler exchange or Taler merchants. -**-c** *FILENAME* \| **--config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Location where to write the generated configuration. Existing file will be updated, not overwritten. -**-C** *CURRENCY* \| **--currency=**\ \ *CURRENCY* +**-C** *CURRENCY* \| **––currency=**\ \ *CURRENCY* Which currency should we use in the configuration. -**-e** \| **--exchange** +**-e** \| **––exchange** Generate configuration for a Taler exchange. **-f** *AMOUNT* \| *-wirefee=*\ \ *AMOUNT* Setup wire transfer fees for the next 5 years for the exchange (for all wire methods). -**-m** \| **--merchant** +**-m** \| **––merchant** Generate configuration for a Taler merchant. -**-t** \| **--trusted** +**-t** \| **––trusted** Setup current exchange as trusted with current merchant. Generally only useful when configuring for testcases. -**-w** *WIREFORMAT* \| **--wire** *WIREFORMAT* +**-w** *WIREFORMAT* \| **––wire** *WIREFORMAT* Specifies which wire format to use (i.e. “test” or “sepa”) -**-j** *JSON* \| **--wire-json-merchant=**\ \ *JSON* +**-j** *JSON* \| **––wire-json-merchant=**\ \ *JSON* Wire configuration to use for the merchant. -**-J** *JSON* \| **--wire-json-exchange=**\ \ *JSON* +**-J** *JSON* \| **––wire-json-exchange=**\ \ *JSON* Wire configuration to use for the exchange. -**--bank-uri** +**––bank-uri** Alternative to specify wire configuration to use for the exchange and merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the URI of the bank. -**--exchange-bank-account** +**––exchange-bank-account** Alternative to specify wire configuration to use for the exchange for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the bank account number of the exchange. -**--merchant-bank-account** +**––merchant-bank-account** Alternative to specify wire configuration to use for the merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the bank account number of the merchant. -**-h** \| **--help** +**-h** \| **––help** Shows this man page. -**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* +**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. -**-v** \| **--version** +**-v** \| **––version** Print GNUnet version number. Bugs diff --git a/manpages/taler-exchange-aggregator.1.rst b/manpages/taler-exchange-aggregator.1.rst @@ -12,7 +12,9 @@ Synopsis ======== **taler-exchange-aggregator** -[**-h** | **--help**] [**-t** | **--test**] [**-v** | **--version**] +[**-h** | **––help**] +[**-t** | **––test**] +[**-v** | **––version**] Description =========== @@ -21,17 +23,17 @@ Description to the same merchant into larger wire transfers. The actual transfers are then done by **taler-exchange-transfer**. -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-t** \| **--test** +**-t** \| **––test** Run in test mode and exit when idle. -**-v** \| **--version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-benchmark.1.rst b/manpages/taler-exchange-benchmark.1.rst @@ -14,11 +14,13 @@ Synopsis ======== **taler-exchange-benchmark** -[**-c** *CONFIG_FILENAME* | **--config=**\ \ *CONFIG_FILENAME*] -[**-b** *BANK_URL* | **—bank-url=**\ \ *BANK_URL*] [-f] [-K] -[**-n** *HOWMANY_COINS* | **--coins-number=**\ \ *HOWMANY_COINS*] -[**-l** *LOGLEVEL* | **--log-level=**\ \ *LOGLEVEL*] -[**-h** | **--help**] +[**-c** *CONFIG_FILENAME* | **––config=**\ \ *CONFIG_FILENAME*] +[**-b** *BANK_URL* | **––bank-url=**\ \ *BANK_URL*] +[**-f** | **––fakebank**] +[**-K** | **––linger**] +[**-n** *HOWMANY_COINS* | **––coins-number=**\ \ *HOWMANY_COINS*] +[**-l** *LOGLEVEL* | **––log-level=**\ \ *LOGLEVEL*] +[**-h** | **––help**] Description =========== @@ -30,34 +32,34 @@ the (fake)bank - listen to URLs not subject to any reverse proxy, as say Nginx. Moreover, the benchmark runs on a “volatile” database, that means that table are always erased during a single benchmark run. -**-c** *CONFIG_FILENAME* \| **--config=**\ \ *CONFIG_FILENAME* +**-c** *CONFIG_FILENAME* \| **––config=**\ \ *CONFIG_FILENAME* (Mandatory) Use CONFIG_FILENAME. -**-b** *BANK_URL* \| **—bank-url=**\ \ *BANK_URL* +**-b** *BANK_URL* \| **––bank-url=**\ \ *BANK_URL* (Mandatory) The URL where the fakebank listens at. Must match the host component in the exchange’s escrow account “payto” URL. -**-f** \| **--fakebank** +**-f** \| **––fakebank** Launch a fakebank instead of the Python bank. Only meaningful if the mode is to launch more than just a client. Note that using the fakebank will cause the benchmark application to reset all databases as the fakebank is stateless and thus previous database state would inherently cause trouble. -**-K** \| **--linger** +**-K** \| **––linger** Linger around until keypress after the benchmark is done. -**-n** *HOWMANY_COINS* \| **--coins-number=**\ \ *HOWMANY_COINS* +**-n** *HOWMANY_COINS* \| **––coins-number=**\ \ *HOWMANY_COINS* Defaults to 1. Specifies how many coins this benchmark should withdraw and spend. After being spent, each coin will be refreshed with a REFRESH_PROBABILITY probability, which is (hardcoded as) 0.1; future versions of this tool should offer this parameter as a CLI option. -**-l** *LOGLEVEL* \| **--log-level=**\ \ *LOGLEVEL* +**-l** *LOGLEVEL* \| **––log-level=**\ \ *LOGLEVEL* GNUnet-compatible log level, takes values “ERROR/WARNING/INFO/DEBUG” -**-h** \| **--help** +**-h** \| **––help** Prints a compiled-in help text. See Also diff --git a/manpages/taler-exchange-closer.1.rst b/manpages/taler-exchange-closer.1.rst @@ -12,7 +12,9 @@ Synopsis ======== **taler-exchange-closer** -[**-h** | **--help**] [**-t** | **--test**] [**-v** | **--version**] +[**-h** | **––help**] +[**-t** | **––test**] +[**-v** | **––version**] Description =========== @@ -22,17 +24,17 @@ reserves that have been idle for too long, causing transfers to the originating bank account to be scheduled. -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-t** \| **--test** +**-t** \| **––test** Run in test mode and exit when idle. -**-v** \| **--version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst @@ -13,8 +13,10 @@ Synopsis ======== **taler-exchange-dbinit** -[**-h** | **–help**] [**-g** | **–gc**] [**-r** | **–reset**] -[**-v** | **–version**] +[**-h** | **––help**] +[**-g** | **––gc**] +[**-r** | **––reset**] +[**-v** | **––version**] Description =========== @@ -25,18 +27,18 @@ Taler exchange to operate. Its options are as follows: -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-g** \| **–gc** +**-g** \| **––gc** Garbage collect database. Deletes all unnecessary data in the database. -**-r** \| **–reset** +**-r** \| **––reset** Drop tables. Dangerous, will delete all existing data in the database before creating the tables. diff --git a/manpages/taler-exchange-httpd.1.rst b/manpages/taler-exchange-httpd.1.rst @@ -11,12 +11,14 @@ taler-exchange-httpd(1) Synopsis ======== -**taler-exchange-httpd** [**-C** | **–connection-close**] -[**-c** *FILENAME* | **–config=**\ \ *FILENAME*] -[**-f** *FILENAME* | **–file-input=**\ \ *FILENAME*] -[**-h** | **–help**] -[**-L** *LOGLEVEL* | **–loglevel=**\ \ *LOGLEVEL*] -[**-t** *SECONDS* | **–timeout=**\ \ *SECONDS*] [**-v** | **–version**] +**taler-exchange-httpd** +[**-C** | **––connection-close**] +[**-c** *FILENAME* | **––config=**\ \ *FILENAME*] +[**-f** *FILENAME* | **––file-input=**\ \ *FILENAME*] +[**-h** | **––help**] +[**-L** *LOGLEVEL* | **––loglevel=**\ \ *LOGLEVEL*] +[**-t** *SECONDS* | **––timeout=**\ \ *SECONDS*] +[**-v** | **––version**] Description =========== @@ -27,29 +29,29 @@ must exist before running this command. Its options are as follows: -**-a** \| **–allow-timetravel** +**-a** \| **––allow-timetravel** Allow clients to request /keys for arbitrary timestamps. This should only be enabled for testing and development, as clients could abuse this in denial of service attacks, as it makes the /keys response generation much more expensive. -**-C** \| **–connection-close** +**-C** \| **––connection-close** Force each HTTP connection to be closed after each request (useful in combination with **-f** to avoid having to wait for nc to time out). -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-v** \| **–version** +**-v** \| **––version** Print version information. -**-f** *FILENAME* \| **–file-input=**\ \ *FILENAME* +**-f** *FILENAME* \| **––file-input=**\ \ *FILENAME* This option is only available if the exchange was compiled with the - configure option –enable-developer-mode. It is used for generating + configure option ––enable-developer-mode. It is used for generating test cases against the exchange using AFL. When this option is present, the HTTP server will @@ -64,11 +66,11 @@ Its options are as follows: to test taler-exchange-httpd against many different possible inputs in a controlled way. -**-t** *SECONDS* \| **–timeout=**\ \ *SECONDS* +**-t** *SECONDS* \| **––timeout=**\ \ *SECONDS* Specifies the number of SECONDS after which the HTTPD should close (idle) HTTP connections. -**-L** *LOGLEVEL* \| **–loglevel=**\ \ *LOGLEVEL* +**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: DEBUG, INFO, WARNING, ERROR. diff --git a/manpages/taler-exchange-keycheck.1.rst b/manpages/taler-exchange-keycheck.1.rst @@ -13,7 +13,8 @@ Synopsis ======== **taler-exchange-keycheck** -[**-h** | **–help**] [**-v** | **–version**] +[**-h** | **––help**] +[**-v** | **––version**] Description =========== @@ -25,21 +26,21 @@ that the files are correct. Its options are as follows: -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-i** *AMOUNT* \| **–denomination-info-hash=**\ \ *AMOUNT* +**-i** *AMOUNT* \| **––denomination-info-hash=**\ \ *AMOUNT* Output the full denomination key hashes and the validity starting times of all denomination keys for the given *AMOUNT*. Useful to identify hashes when revoking keys. -**-L** *LOGLEVEL* \| **–loglevel=**\ \ *LOGLEVEL* +**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: DEBUG, INFO, WARNING, ERROR. -**-v** \| **–version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-keyup.1.rst b/manpages/taler-exchange-keyup.1.rst @@ -13,11 +13,12 @@ Synopsis ======== **taler-exchange-keyup** -[**-h** | **–help**] [**-m** *FILE* | **–master-key=**\ \ *FILE*] -[**-o** *FILE* | **–output=**\ \ *FILE*] -[**-r** *DKH* | **–revoke=**\ \ *DKH*] -[**-t** *TIMESTAMP* | **–time=**\ \ *TIMESTAMP*] -[**-v** | **–version**] +[**-h** | **––help**] +[**-m** *FILE* | **––master-key=**\ \ *FILE*] +[**-o** *FILE* | **––output=**\ \ *FILE*] +[**-r** *DKH* | **––revoke=**\ \ *DKH*] +[**-t** *TIMESTAMP* | **––time=**\ \ *TIMESTAMP*] +[**-v** | **––version**] Description =========== @@ -31,44 +32,44 @@ operates. Its options are as follows: -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. -**-f** *DIRNAME* \| **–feedir=**\ \ *DIRNAME* +**-f** *DIRNAME* \| **––feedir=**\ \ *DIRNAME* Directory where to write the wire transfer fee structure. If not given, the one from the main configuration will be used. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-L** *LOGLEVEL* \| **–loglevel=**\ \ *LOGLEVEL* +**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: DEBUG, INFO, WARNING, ERROR. -**-k** *BITS* \| **–replacement-keysize=**\ \ *BITS* +**-k** *BITS* \| **––replacement-keysize=**\ \ *BITS* When revoke an active denomination key (see **--r** option), use *BITS* bit for the replacement denomination key. Default is 2048 (bits). -**-m** *FILE* \| **–master-key=**\ \ *FILE* +**-m** *FILE* \| **––master-key=**\ \ *FILE* Location of the private EdDSA offline master key of the exchange. If not given, the location given in the configuration file will be used. -**-o** *FILE* \| **–output=**\ \ *FILE* +**-o** *FILE* \| **––output=**\ \ *FILE* Where to write a denomination key signing request file to be given to the auditor. -**-r** *DKH* \| **–revoke=**\ \ *DKH* +**-r** *DKH* \| **––revoke=**\ \ *DKH* Revoke the denomination key where the denomination public key’s hash is DKH. -**-T** *[+/-]MICROSECONDS* \| **–timetravel=**\ \ *[+/-]MICROSECONDS* +**-T** *[+/-]MICROSECONDS* \| **––timetravel=**\ \ *[+/-]MICROSECONDS* Modify system time (as seen by this process) by the given offset (for debugging/testing). -**-t** *TIMESTAMP* \| **–time=**\ \ *TIMESTAMP* +**-t** *TIMESTAMP* \| **––time=**\ \ *TIMESTAMP* Operate as if the current time was *TIMESTAMP*. -**-v** \| **–version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-transfer.1.rst b/manpages/taler-exchange-transfer.1.rst @@ -12,7 +12,9 @@ Synopsis ======== **taler-exchange-transfer** -[**-h** | **--help**] [**-t** | **--test**] [**-v** | **--version**] +[**-h** | **––help**] +[**-t** | **––test**] +[**-v** | **––version**] Description =========== @@ -20,17 +22,17 @@ Description **taler-exchange-transfer** is a command line tool to actually execute scheduled wire transfers (using the bank/wire gateway). The transfers are prepared by the **taler-exchange-aggregator** and **taler-exchange-closer** tools. -**-c** *FILENAME* \| **–config=**\ \ *FILENAME* +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. -**-h** \| **--help** +**-h** \| **––help** Print short help on options. -**-t** \| **--test** +**-t** \| **––test** Run in test mode and exit when idle. -**-v** \| **--version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-wire.1.rst b/manpages/taler-exchange-wire.1.rst @@ -12,9 +12,10 @@ taler-exchange-wire(1) Synopsis ======== -**taler-exchange-wire** [**-h** | **–help**] -[**-m** *MASTERKEYFILE* | **–master=**\ \ *MASTERKEYFILE*] -[**-v** | **–version**] +**taler-exchange-wire** +[**-h** | **––help**] +[**-m** *MASTERKEYFILE* | **––master=**\ \ *MASTERKEYFILE*] +[**-v** | **––version**] Description =========== @@ -25,13 +26,13 @@ response. This needs to be done using the long-term offline master key. Its options are as follows: -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-m** *MASTERKEYFILE* \| **–master=**\ \ *MASTERKEYFILE* +**-m** *MASTERKEYFILE* \| **––master=**\ \ *MASTERKEYFILE* Specifies the name of the file containing the exchange’s master key. -**-v** \| **–version** +**-v** \| **––version** Print version information. See Also diff --git a/manpages/taler-exchange-wirewatch.1.rst b/manpages/taler-exchange-wirewatch.1.rst @@ -12,8 +12,11 @@ Synopsis ======== **taler-exchange-wirewatch** -[**-t** *PLUGINNAME* | **–type=**\ \ *PLUGINNAME*] [**-h** | **–help**] -[**-T** | **–test**] [**-r** | **–reset**] [**-v** | **–version**] +[**-t** *PLUGINNAME* | **––type=**\ \ *PLUGINNAME*] +[**-h** | **––help**] +[**-T** | **––test**] +[**-r** | **––reset**] +[**-v** | **––version**] Description =========== @@ -23,25 +26,25 @@ transactions into the Taler exchange database. Its options are as follows: -**-t** *PLUGINNAME* \| **–type=**\ \ *PLUGINNAME* +**-t** *PLUGINNAME* \| **––type=**\ \ *PLUGINNAME* Use the specified wire plugin and its configuration to talk to the bank. -**-h** \| **–help** +**-h** \| **––help** Print short help on options. -**-T** \| **–test** +**-T** \| **––test** Run in test mode and exit when idle. -**-r** \| **–reset** +**-r** \| **––reset** Ignore our own database and start with transactions from the beginning of time. -**-v** \| **–version** +**-v** \| **––version** Print version information. diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst @@ -31,11 +31,11 @@ ordinary default instance) and aggregated by the exchange. Takes the following options. - -p PN, --payments-number=PN + **-p** *PN* \| **––payments-number=**\ \ *PN* Perform PN many payments, defaults to 1. - -t TN, --tracks-number=TN + **-t** *TN* \| **––tracks-number=**\ \ *TN* Perform TN many tracking operations, defaults to 1. @@ -45,17 +45,17 @@ corner instance. Takes the following options. - -t TC, --two-coins=TC + **-t** *TC* \| **––two-coins=**\ \ *TC* Perform TC many payments that use two coins (normally, all the payments use only one coin). TC defaults to 1. - -i AI, --alt-instance=AI + **-i** *AI* \| **––alt-instance=**\ \ *AI* Use AI as the instance, instead of 'default' (which is the default instance used.) - -u UN, --unaggregated-number=UN + **-u** *UN* \| **––unaggregated-number=**\ \ *UN* Generate UN payments that will be left unaggregated. Note that subsequent invocations of the generator may pick those unaggregated payments and actually aggregated them. @@ -65,34 +65,33 @@ corner Common Options ============== --k K, --currency=K +**-k** *K* \| **––currency=**\ \ *K* Use currency K, mandatory. --m URL, --merchant-url=URL +**-m** *URL* \| **––merchant-url=**\ \ *URL* Use URL as the merchant base URL during the benchmark. The URL is mainly used to download and pay for contracts. Mandatory. --b URL, --bank-url=URL +**-b** *URL* \| **––bank-url=**\ \ *URL* Use URL as the bank's base URL during the benchmark. The URL is used to test whether the bank is up and running. Mandatory. --c FILENAME, --config=FILENAME +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. --h, --help +**-h** \| **––help** Print short help on options. --v, --version +**-v** \| **––version** Print version information. --l LF, --logfile=LF +**-l** *LF* \| **––logfile=**\ \ *LF* Sends logs to file whose path is LF. - --L LOGLEVEL, --log=LOGLEVEL +**-L** *LOGLEVEL* \| **––log=**\ \ *LOGLEVEL* Use loglevel LOGLEVEL. diff --git a/manpages/taler-merchant-httpd.1.rst b/manpages/taler-merchant-httpd.1.rst @@ -26,19 +26,19 @@ before running this command. Options ======= --C, --connection-close +**-C** \| **––connection-close** Force each HTTP connection to be closed after each request (useful in combination with -f to avoid having to wait for nc to time out). --c FILENAME, --config=FILENAME +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. --h, --help +**-h** \| **––help** Print short help on options. --v, --version +**-v** \| **––version** Print version information. diff --git a/manpages/taler-merchant-setup-reserve.1.rst b/manpages/taler-merchant-setup-reserve.1.rst @@ -27,54 +27,54 @@ from the exchange needed to fill the reserve. Options ======= --a VALUE, --amount=VALUE +**-a** *VALUE* \| **––amount=**\ \ *VALUE* Amount to be transferred to the reserve. Mandatory. --A USERNAME:PASSWORD, --auth=USERNAME:PASSWORD +**-A** *USERNAME:PASSWORD* \| **––auth=**\ \ *USERNAME:PASSWORD* Use USERNAME and PASSWORD for HTTP client authentication. The ":" must be present as a separator. Note that this form of authentication has nothing to do with the TLS client certificate authentication supported with the "-C", "-k" and "-p" options. The PASSWORD given to this option is given to the server! Optional. --C CERTFILE, --cert=CERTFILE +**-C** *CERTFILE* \| **––cert=**\ \ *CERTFILE* The specified CERTFILE contains a TLS client certificate to be used to authenticate the client. Optional. See also "-t". --e URL, --exchange-url=URL +**-e** *URL* \| **––exchange-url=**\ \ *URL* Use URL for the exchange base URL. This is the exchange where the reserve will be created. The currency used in the amount specification must be offered by this exchange. Mandatory. --k KEYFILE, --key=KEYFILE +**-k** *KEYFILE* \| **––key=**\ \ *KEYFILE* The specified KEYFILE contains a TLS client private key to be used to authenticate the client. Optional. See also "-p" and "-C". --m URL, --merchant-url=URL +**-m** *URL* \| **––merchant-url=**\ \ *URL* Use URL as the merchant base URL. Should include the path to the instance if the reserve is to be created for a non-default instance. Mandatory. --p KEYFILEPASSPHRASE, --pass=KEYFILEPASSPHRASE +**-p** *KEYFILEPASSPHRASE* \| **––pass=**\ \ *KEYFILEPASSPHRASE* The specified KEYFILEPASSPHRASE is to be used to decrypt the KEYFILE. Optional. See also "-k". Not to be confused with "-A". The KEYFILEPASSPHRASE given here is only used locally to decrypt the KEYFILE. --t CERTTYPE, --type=CERTTYPE +**-t** *CERTTYPE* \| **––type=**\ \ *CERTTYPE* The specified CERTFILE contains a TLS client certificate of CERTTYPE. Default is "PEM". Optional. See also "-C". --w METHOD, --wire-method=METHOD +**-w** *METHOD* \| **––wire-method=**\ \ *METHOD* Which wire method should be used. Needed to select the wire transfer method of the exchange. The method must be supported by the exchange. Typical values would be "iban" or "x-taler-bank". Mandatory. --c FILENAME, --config=FILENAME +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. --h, --help +**-h** \| **––help** Print short help on options. --v, --version +**-v** \| **––version** Print version information. --l LF, --logfile=LF +**-l** *LF* \| **––logfile=**\ \ *LF* Sends logs to file whose path is LF. --L LOGLEVEL, --log=LOGLEVEL +**-L** *LOGLEVEL* \| **––log=**\ \ *LOGLEVEL* Use loglevel LOGLEVEL. diff --git a/manpages/taler-wallet-cli.1.rst b/manpages/taler-wallet-cli.1.rst @@ -11,7 +11,11 @@ taler-wallet-cli(1) Synopsis ======== -**taler-auditor** [**-h** | **-\\-help**][**-\\-verbose**][**-V** | **-\\-version**]<command>[<args>] +**taler-auditor** +[**-h** | **––help**] +[**––verbose**] +[**-V** | **––version**] +<command> [<args>] Description @@ -20,16 +24,16 @@ Description **taler-wallet-cli** is a command line tool to be used by developers for testing. -**-h** | **-\\-help** +**-h** | **––help** Print short help on options. -**-\\-verbose** +**––verbose** Enable verbose output. -**-V** | **-\\-version** +**-V** | **––version** Output the version number. -**test-withdraw** [**-e** URL | **-\\-exchange** URL] [**-a** AMOUNT | **-\\-amount** AMOUNT][**-b** URL | **-\\-bank** URL] +**test-withdraw** [**-e** URL | **––exchange** URL] [**-a** AMOUNT | **––amount** AMOUNT][**-b** URL | **––bank** URL] withdraw test currency from the test bank **balance** @@ -38,7 +42,7 @@ for testing. **history** show wallet history -**test-merchant-qrcode** [**-a** AMOUNT | **-\\-amount** AMOUNT][**-s** SUMMARY | **-\\-summary** SUMMARY] +**test-merchant-qrcode** [**-a** AMOUNT | **––amount** AMOUNT][**-s** SUMMARY | **––summary** SUMMARY] **withdraw-uri** URI @@ -46,9 +50,9 @@ for testing. **refund-uri** URI -**pay-uri** [**-y** | **-\\-yes**] URI +**pay-uri** [**-y** | **––yes**] URI -**integrationtest** [**-e** URL | **-\\-exchange** URL][**-m** URL | **-\\-merchant** URL][**-k** APIKEY | **-\\-merchant-api-key** APIKEY][**-b** URL | **-\\-bank** URL][**-w** AMOUNT | **-\\-withdraw-amount** AMOUNT][**-s** AMOUNT | **-\\-spend-amount** AMOUNT] +**integrationtest** [**-e** URL | **––exchange** URL][**-m** URL | **––merchant** URL][**-k** APIKEY | **––merchant-api-key** APIKEY][**-b** URL | **––bank** URL][**-w** AMOUNT | **––withdraw-amount** AMOUNT][**-s** AMOUNT | **––spend-amount** AMOUNT] Run integration test with bank, exchange and merchant. .. See Also