diff options
author | Christian Grothoff <christian@grothoff.org> | 2020-05-18 19:29:11 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-05-18 19:29:11 +0200 |
commit | c6014d72d0db9f199a6462c9841ffa4785985d45 (patch) | |
tree | e2ee15e7e372c6bb9dcd7ee306065911563686f0 | |
parent | 66b09780c1911e90c5b702f0374ef71dfbaa9f8a (diff) | |
parent | 16466dd547243332ad1284827f34369442e1bc3c (diff) | |
download | docs-c6014d72d0db9f199a6462c9841ffa4785985d45.tar.gz docs-c6014d72d0db9f199a6462c9841ffa4785985d45.tar.bz2 docs-c6014d72d0db9f199a6462c9841ffa4785985d45.zip |
Merge branch 'master' of git+ssh://git.taler.net/docs
-rw-r--r-- | anastasis-db.png | bin | 51727 -> 52516 bytes | |||
-rw-r--r-- | conf.py | 8 | ||||
-rw-r--r-- | libeufin/api-nexus.rst | 79 | ||||
-rw-r--r-- | libeufin/api-sandbox.rst | 196 | ||||
-rw-r--r-- | libeufin/bank-transport-ebics.rst | 55 | ||||
-rw-r--r-- | libeufin/index.rst | 5 | ||||
-rw-r--r-- | taler-wallet.rst | 131 |
7 files changed, 264 insertions, 210 deletions
diff --git a/anastasis-db.png b/anastasis-db.png Binary files differindex 3681fa4e..4a2fc5c1 100644 --- a/anastasis-db.png +++ b/anastasis-db.png @@ -229,6 +229,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ + ('taler-auditor-manual', 'taler-auditor-manual.tex', + 'GNU Taler Auditor Manual', 'GNU Taler team', 'manual'), ('taler-exchange-manual', 'taler-exchange-manual.tex', 'GNU Taler Exchange Manual', 'GNU Taler team', 'manual'), ('taler-merchant-manual', 'taler-merchant-manual.tex', @@ -239,7 +241,7 @@ latex_documents = [ 'GNU Taler team', 'manual'), ('taler-backoffice-manual', 'taler-backoffice-manual.tex', 'GNU Taler Back Office Manual', 'GNU Taler team', 'manual'), - ('onboarding', 'onboarding.tex', 'GNU Taler Developer Onboarding Manual', + ('developers-manual', 'developers-manual.tex', 'GNU Taler Developer Onboarding Manual', 'GNU Taler team', 'manual'), ] @@ -327,6 +329,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ + ("taler-auditor-manual", "taler-auditor", "Taler Auditor Manual", + "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), ("taler-exchange-manual", "taler-exchange", "Taler Exchange Manual", "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), ("taler-merchant-manual", "taler-merchant", "Taler Merchant Manual", @@ -336,7 +340,7 @@ texinfo_documents = [ "DESCRIPTION", "CATEGORY"), ("taler-bank-manual", "taler-bank", "Taler Bank Manual", "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), - ("onboarding", "onboarding", "Taler Onboarding Manual", "GNU Taler team", + ("developers-manual", "developers-manual", "Taler Developer Onboarding Manual", "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), ] diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index bc3dacce..681811aa 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -48,7 +48,7 @@ Users Management **Details:** - .. ts:def:: CreateUserRequest + .. ts:def:: User interface User { @@ -82,7 +82,7 @@ Bank Account Management holder: string; } -.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments/submit +.. http:post:: <nexus>/bank-accounts/prepared-payments/submit Ask nexus to submit one prepare payment at the bank. @@ -96,7 +96,22 @@ Bank Account Management uuid: string; // Specify the bank transport to use for the submission. - transport?: string; + transport?: Transport; + } + + + .. ts:def:: Transport + + interface Transport { + + // Transport type: 'ebics', 'local', 'fints' (forthcoming). + // It must match one of the types actually implemented by + // nexus. + type: string; + + // A mnemonic identifier given by the user to one particular + // transport instance. + name: string; } :status 404 Not Found: the unique identifier **or** @@ -176,10 +191,9 @@ Bank Account Management uuid: string; } -.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions +.. http:post:: <nexus>/bank-accounts/collected-transactions - Ask the default transport to download the latest transactions - related to ``my-acct`` and store them locally. + Nexus will download bank transactions from the given transport. **Request:** @@ -188,7 +202,7 @@ Bank Account Management interface CollectedTransaction { // Optional field to specify the bank transport to // use for such operation. - bankTransport?: string; + bankTransport?: Transport; // dashed date (YYYY-MM-DD) of the earliest payment // in the result. Optional, defaults to "earliest // possible" date. @@ -251,27 +265,37 @@ to the real bank. Activate a new bank transport for the requesting user. **Request:** - Object of the type `BankTransport` - - **Response:** - - :status 409 Conflict: The ``name`` field exists already for - the requesting user. - - **Details:** .. ts:def:: BankTransport interface BankTransport { - // Mnemonic identifier for the transport bein created. - name: string; + transport: Transport; - // Restore a previous transport. + // Restore a previous transport. Take precedence + // over the 'new' field. backup?: TransportBackup; + + // Data to create a fresh bank transport without + // restoring any backup. + data?: TransportNew; + } + + + .. ts:def:: TransportNew + + interface TransportNew { + + // This type is strictly dependent on + // the transport being created. For Ebics, + // it will contain the required fields (as strings): + // 'ebicsURL', 'userID', 'partnerID', 'hostID', and + // the optional 'systemID'. + + // Other transport types, like 'local' (used for testing + // purposes skipping any interaction with the bank service) + // and 'fints' are all work in progress! - // Type of the transport (ebics, fints, native, ..) - type: string; } @@ -279,16 +303,25 @@ to the real bank. interface TransportBackup { - // The information needed in this type depend entirely - // on which transport is being restored. + // The information needed in this type depend entirely + // on which transport is being restored. } -.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG. + **Response:** + + :status 409 Conflict: The ``name`` field exists already for + the requesting user. + +.. http:post:: <nexus>/bank-transports/sendMSG. Perform the ``MSG`` operation offered by ``transport-name`` **without** affecting the nexus database. + **Request:** + + A `Transport` object. + **Response:** :status 404 Not Found: ``transport-name`` doesn't exist for diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index ee298d85..015b8d59 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -1,189 +1,49 @@ + Sandbox API ########### -Entities -======== - -Bank Account - ... - -EBICS Host - -EBICS Subscriber - ... - -EBICS Partner - ... - - - HTTP API ======== +.. + Payments. -.. http:post:: /ebicsweb +.. http:post:: /admin/payments + + Adds a new payment to the book. - Submit an EBICS request to the sandbox. +.. + Host management. +.. http:post:: /admin/ebics/hosts + + Creates a new Ebics host. -.. http:post:: /admin/customers +.. http:get:: /admin/ebics/hosts + + Shows the list of all the hosts existing + in the system. - Create a new customer. A customer identifies a human that - may own multiple bank accounts. +.. + Subscriber management. - When creating a customer, one EBICS subscriber is automatically - created for the customer. +.. http:post:: /admin/ebics/subscribers - In the future, we might add an API to create multiple additional subscribers for - a customer. + Creates a new subscriber. - When creating a new customer, an ID will be assigned automatically. +.. http:get:: /admin/ebics/subscribers - .. code-block:: tsref + Shows the list of all the subscribers existing + in the system. - interface CustomerCreationRequest { - // human-readable name for the customer - name: string; - } +.. http:post:: /admin/ebics/bank-accounts -.. http:get:: /admin/customers/:id + Associates a new bank account to an existing subscriber. - Get information about a customer. +.. + Main EBICS service. - .. ts:def:: CustomerInfo +.. http:post:: /ebicsweb - interface CustomerInfo { - ebicsInfo?: CustomerEbicsInfo; - finTsInfo?: CustomerFinTsInfo; - } - - .. ts:def:: CustomerEbicsInfo - - interface CustomerEbicsInfo { - ebicsHostId: string; - ebicsParterId: string; - ebicsUserId: string; - - // Info for the customer's "main subscriber" - subscriberInitializationState: "NEW" | "PARTIALLY_INITIALIZED_INI" | "PARTIALLY_INITIALIZED_HIA" | "READY" | "INITIALIZED"; - } - - .. ts:def:: CustomerFinTsInfo - - // TODO - -.. http:post:: /admin/customers/:id/ebics/keyletter - - Accept the information from the customer's ("virtual") INI-Letter and HIA-Letter - and change the key's state as required. - - .. code-block:: tsref - - interface KeyLetterRequest { - - ini: { - // The user ID that participates in a EBICS subscriber. - userId: string; - - // The customer ID specific to the bank (therefore not - // participating in a EBICS subscriber). - customerId: string; - - // Human name of the user - name: string; - - // As per specification, this value is: - // "Date of processing of the corresponding EBICS order". DD.MM.YYYY format. - date: string; - - // As per specification, this value is: - // "Time of processing of the corresponding EBICS order". HH:MM:SS format. - time: string; - - // Identification token of the bank. Not required to obey to any particular standard. - recipient: string; - - // Electronic signature version. Admitted values: A005, A006. - version: string; - - // Length in bits of the key exponent. - public_exponent_length: number; - // RSA key exponent in hexadecimaml notation. - public_exponent: string; - - // Length in bits of the key modulus. - public_modulus_length: number; - // RSA key modulus in hexadecimaml notation. - public_modulus: string; - - // RSA key hash. - // - // A005, A005 versions require hash type SHA-256. - hash: string; - } - - hia: { - // The user ID that participates in a EBICS subscriber. - userId: string; - - // The customer ID specific to the bank (therefore not - // participating in a EBICS subscriber). - customerId: string; - - // Human name of the user - name: string; - - // As per specification, this value is: - // "Date of processing of the corresponding EBICS order". DD.MM.YYYY format. - date: string; - - // As per specification, this value is: - // "Time of processing of the corresponding EBICS order". HH:MM:SS format. - time: string; - - // Identification token of the bank. Not required to obey to any particular standard. - recipient: string; - - //////////////////////////////////////////////////// - // Identification and Authentication key details. // - //////////////////////////////////////////////////// - - // Identification and authentication signature version. - // Admitted value: X002. - ia_version: string; - - // length of the exponent, in bits. - ia_public_exponent_length: number; - // RSA key exponent in hexadecimaml notation. - ia_public_exponent: string; - - // length of the modulus, in bits. - ia_public_modulus_length: number; - // RSA key modulus in hexadecimaml notation. - ia_public_modulus: string; - - // SHA-256 hash of the identification and authentication key. - ia_hash: string; - - ///////////////////////////// - // Encryption key details. // - ///////////////////////////// - - // Encryption version. Admitted value: E002. - enc_version: string; - - // length of the exponent, in bits. - enc_public_exponent_length: number; - // RSA key exponent in hexadecimaml notation. - enc_public_exponent: string; - - // length of the modulus, in bits. - enc_public_modulus_length: number; - // RSA key modulus in hexadecimaml notation. - enc_public_modulus: string; - - // SHA-256 hash of the encryption key. - enc_hash: string; - } - } + Serves all the Ebics requests. diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst new file mode 100644 index 00000000..0d06f83b --- /dev/null +++ b/libeufin/bank-transport-ebics.rst @@ -0,0 +1,55 @@ +The EBICS Bank Transport +======================== + +An EBICS bank transport in LibEuFin conceptually corresponds +to the "EBICS Subscriber" in EBICS terminology. + + +Bank Transport Setup +-------------------- + +The following steps are required to set up an EBICS bank transport: + +1. The bank must set up the EBICS access for the user. + The bank will notify the user of the following parameters: + + * the URL of the EBICS server used by the bank + * the HostID of the bank within the EBICS server (sometimes one EBICS server hosts multiple banks) + * the PartnerID (typically identifies the owner of the bank account within the banking system) + * the UserID (typically identifies the person that accesses the bank account, can be different from the owner) + * the SystemID (optional and rarely used, basically a "sub-identity" of a subscriber when multiple technical + systems have access to the account via EBICS) + +2. The user enters the information from the list above in the setup dialog in the LibEuFin nexus (UI/CLI). + +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 + identifying the subscriber (PartnerID, UserID, SystemID). + +6. The user print a document that contains the public key and hashes for all three key pairs. + The user then signs this document sends it to the bank (physically/scanned). + +7. 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". + 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. + 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. + + +Alternative ways of setting up the EBICS bank transport are: + +* Importing from a backup. The backup contains metadata (EBICS URL, HostID, + UserId, ...) and the three passphrase-protected subscriber keys. +* Certificate-based setup (currently not supported by LibEuFin, only used in France) + + diff --git a/libeufin/index.rst b/libeufin/index.rst index bc00b964..49d44ded 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -7,7 +7,8 @@ LibEuFin is a project providing free software tooling for European FinTech. :glob: concepts - ebics - api-sandbox + bank-transport-ebics api-nexus + api-sandbox + ebics iso20022 diff --git a/taler-wallet.rst b/taler-wallet.rst index 11167ea9..ce369002 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -81,19 +81,65 @@ APIs and Data Formats These APIs are still a work in progress and *not* final. +Balances +-------- + +Balances are the amounts of digital cash held by the wallet. + +:name: ``"getBalances"`` +:description: Get a list of balances per currency. +:response: + .. ts:def:: BalancesResponse + + interface BalancesResponse { + // a list of balances sorted by currency. + // (currencies with shorter names first, then lexically ascending). + // + // Note: Even when a currency has no balance, but pending or past transactions, + // it should be included in this list with a balance of zero. + balances: Balance[]; + } + + .. ts:def:: Balance + + interface Balance { + currency?: string; + + // The total Amount that is currently available to be spent + // including amounts tied up in ongoing refresh operations. These are hidden from the user. + // If the user tries to spend coins locked up this way, + // the wallet will give an error message different from "insufficient balance". + available: Amount; + + // the total incoming amount that will be added to the available balance + // when all pending transactions succeed (including internal refreshes) + pendingIncoming: Amount; + + // the total outgoing amount that will be subtracted from the available balance + // when all pending transactions succeed (including internal refreshes) + pendingOutgoing: Amount; + + // true if the balance has pending transactions + hasPendingTransactions: boolean; + + // true if the balance requires user-interaction, e.g. accepting a tip + // (DEV: can be left out of a first implementation) + requiresUserInput: boolean; + } + Transactions ------------ Transactions are all operations or events that are affecting the balance. -:name: ``"transactions"`` +:name: ``"getTransactions"`` :description: Get a list of past and pending transactions. :request: .. ts:def:: TransactionsRequest interface TransactionsRequest { - // return only transactions in the given currency - currency: string; + // return only transactions in the given currency, if present + currency?: string; // if present, results will be limited to transactions related to the given search string search?: string; @@ -105,7 +151,8 @@ Transactions are all operations or events that are affecting the balance. // a list of past and pending transactions sorted by pending, timestamp and transactionId. // In case two events are both pending and have the same timestamp, // they are sorted by the transactionId - // (lexically ascending and locale-independent comparison). + // (i.e. pending before non-pending transactions, newer before older + // and if all equal transactionId lexically ascending). transactions: Transaction[]; } @@ -127,6 +174,9 @@ Transactions are all operations or events that are affecting the balance. // but its transactionId will remain unchanged pending: boolean; + // if present, the transaction encountered a fatal error that needs to be shown to the user + error?: TransactionError; + // Raw amount of the transaction (exclusive of fees or other extra costs) amountRaw: Amount; @@ -144,6 +194,20 @@ Transactions are all operations or events that are affecting the balance. TransactionRefresh ) + .. ts:def:: TransactionError + + interface TransactionError { + // TALER_EC_* unique error code. + // The action(s) offered and message displayed on the transaction item depend on this code. + ec: number; + + // English-only error hint, if available. + hint?: string; + + // Error details specific to "ec", if applicable/available + details?: any; + } + .. ts:def:: TransactionWithdrawal // This should only be used for actual withdrawals @@ -166,6 +230,7 @@ Transactions are all operations or events that are affecting the balance. amountRaw: Amount; // Amount that actually was (or will be) added to the wallet's balance. + // Should always be shown as a positive amount. amountEffective: Amount; } @@ -177,14 +242,14 @@ Transactions are all operations or events that are affecting the balance. // Additional information about the payment. info: TransactionInfo; - // true if the payment failed, false otherwise. - // Note that failed payments with zero effective amount will not be returned by the API. - failed: boolean; + // The current status of this payment. + status: PaymentStatus; // Amount that must be paid for the contract amountRaw: Amount; // Amount that was paid, including deposit, wire and refresh fees. + // Should always be shown as a negative amount. amountEffective: Amount; } @@ -210,6 +275,26 @@ Transactions are all operations or events that are affecting the balance. fulfillmentUrl: string; } + .. ts:def:: PaymentStatus + + enum PaymentStatus { + // Explicitly aborted after timeout / failure + Aborted = "aborted", + + // Payment failed, wallet will auto-retry. + // User should be given the option to retry now / abort. + Failed = "failed", + + // Paid successfully + Paid = "paid", + + // Only offered, user must accept / decline + Offered = "offered", + + // User accepted, payment is processing. + Accepted = "accepted", + } + .. ts:def:: TransactionRefund interface TransactionRefund extends Transaction { @@ -227,7 +312,8 @@ Transactions are all operations or events that are affecting the balance. // Amount that has been refunded by the merchant amountRaw: Amount; - // Amount will be added to the wallet's balance after fees and refreshing + // Amount will be added to the wallet's balance after fees and refreshing. + // Should always be shown as a positive amount. amountEffective: Amount; } @@ -236,11 +322,8 @@ Transactions are all operations or events that are affecting the balance. interface TransactionTip extends Transaction { type: string = "tip", - // true if the user still needs to accept/decline this tip - waiting: boolean; - - // true if the user has accepted this top, false otherwise - accepted: boolean; + // The current status of this tip. + status: TipStatus; // Exchange that the tip will be (or was) withdrawn from exchangeBaseUrl: string; @@ -251,10 +334,27 @@ Transactions are all operations or events that are affecting the balance. // Raw amount of the tip, without extra fees that apply amountRaw: Amount; - // Amount will be (or was) added to the wallet's balance after fees and refreshing + // Amount will be (or was) added to the wallet's balance after fees and refreshing. + // Should always be shown as a positive amount. amountEffective: Amount; } + .. ts:def:: TipStatus + + enum TipStatus { + // Only offered, user must accept / decline + Offered = "offered", + + // User accepted, tip is processing. + Accepted = "accepted", + + // User declined. + Declined = "declined", + + // Received successfully + Received = "received", + } + .. ts:def:: TransactionRefresh // A transaction shown for refreshes that are not associated to other transactions @@ -269,7 +369,8 @@ Transactions are all operations or events that are affecting the balance. // Raw amount that is refreshed amountRaw: Amount; - // Amount that will be paid as fees for the refresh + // Amount that will be paid as fees for the refresh. + // Should always be shown as a negative amount. amountEffective: Amount; } |