From bea5cde2dae8e35365844bf39ea927464c1f9cad Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 12 Jan 2016 15:37:11 +0100 Subject: Restructuring --- api-merchant.rst | 108 +++++++----------------------------------- banks.rst | 131 --------------------------------------------------- index.rst | 39 +++++++++++++-- integration-bank.rst | 73 ++++++++++++++++++++++++++++ 4 files changed, 126 insertions(+), 225 deletions(-) delete mode 100644 banks.rst create mode 100644 integration-bank.rst diff --git a/api-merchant.rst b/api-merchant.rst index 752b167f..c61a6df7 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -1,12 +1,13 @@ -================ -The Merchant API -================ +===================== +The Merchant HTTP API +===================== -This Merchant API defines the -interactions between a browser-based wallet and an HTTP-based RESTful merchant. -The protocol allows the customer and the merchant to agree upon a -contract and for the customer to spend coins according to the contract -proposed by the merchant. +The merchant API defines + +This Merchant API defines the interactions between a browser-based wallet and +an HTTP-based RESTful merchant. The protocol allows the customer and the +merchant to agree upon a contract and for the customer to spend coins according +to the contract proposed by the merchant. It is assumed that the browser has a secure and possibly customer-anonymizing channel to the merchant, typically by using the @@ -23,28 +24,9 @@ is expected to check that the time of his machine is approximately correct. ------------------------ -Architecture's Overview ------------------------ - -In our settlement, the "merchant" is divided in two independent -compontents, the `frontend` and the `backend`. - -The `frontend` is the existing shopping portal of the merchant. -The architecture tries to minimize the amount of modifications necessary -to the `frontend` as well as the trust that needs to be placed into the -`frontend` logic. Taler requires the frontend to facilitate two -JSON-based interactions between the wallet and the `backend`, and -one of those is trivial. - -The `backend` is a standalone C application intended to implement all -the cryptographic routines required to interact with the Taler wallet -and a Taler mint. - - -+++++++++++++++++++++++++++++ +----------------------------- Wallet-Frontend communication -+++++++++++++++++++++++++++++ +----------------------------- Taler's wallet is designed to notify the user when a certain webpage is offering Taler as a payment option. It does so by simply changing the color of @@ -87,9 +69,9 @@ A precise specification and sample code for implementing the signalling is provided in the dedicated :ref:`section `. -++++++++++++++++++++++++++++++ +------------------------------ Frontend-Backend communication -++++++++++++++++++++++++++++++ +------------------------------ To create a contract, the `frontend` needs to generate the body of a `contract` in JSON format. This `proposition` is then signed by the @@ -106,16 +88,16 @@ responsible for generating the fullfillment page. The contract format is specified in the `contract`_ section. -+++++++++ +--------- Encodings -+++++++++ +--------- Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`. .. _contract: Contract --------- +^^^^^^^^ A `contract` is a JSON object having the following structure, which is returned as a successful response to the following two calls: @@ -222,9 +204,9 @@ Wallet-Frontend .. _message-passing-ref: -+++++++++++++++++++ +------------------- Messagging protocol -+++++++++++++++++++ +------------------- In order to reach mutual acknowledgement, and to avoid signaling loops, we define two interactions. One is initiated by the HTML page inquiring @@ -427,58 +409,4 @@ cookies to identify the shopping session. The error codes and data sent to the wallet are a mere copy of those gotten from the mint when attempting to pay. The section about :ref:`deposit ` explains them in detail. ----------------- -Frontend-Backend ----------------- - -+++++++++++++++ -The RESTful API -+++++++++++++++ - -The following API are made available by the merchant's `backend` to the merchant's `frontend`. - -.. http:post:: /contract - - Ask the backend to add some missing (mostly related to cryptography) information to the contract. - - :reqheader Content-Type: application/json - - The `proposition` that is to be sent from the frontend is a `contract` object without the fields - - * `merchant_pub` - * `mints` - * `H_wire` - - The `backend` then completes this information based on its configuration. - - **Success Response** - - :status 200 OK: The backend has successfully created the contract. - :resheader Content-Type: application/json - - The `frontend` should pass this response verbatim to the wallet. - - **Failure Responses: Bad contract** - - :status 400 Bad Request: Request not understood. The JSON was invalid. Possibly due to some error in formatting the JSON by the `frontend`. - -.. http:post:: /pay - - Asks the `backend` to execute the transaction with the mint and deposit the coins. - - :reqheader Content-Type: application/json - - The `frontend` passes the :ref:`deposit permission ` received from the wallet, by adding the fields `max_fee`, `amount` (see :ref:`contract`) and optionally adding a field named `edate`, indicating a deadline by which he would expect to receive the bank transfer for this deal - - **Success Response: OK** - - :status 200 OK: The mint accepted all of the coins. The `frontend` should now fullfill the contract. This response has no meaningful body, the frontend needs to generate the fullfillment page. - - **Failure Responses: Bad mint** - - :status 400 Precondition failed: The given mint is not acceptable for this merchant, as it is not in the list of accepted mints and not audited by an approved auditor. - - - **Failure Responses: Mint trouble** - The `backend` will return verbatim the error codes received from the mint's :ref:`deposit ` API. If the wallet made a mistake, like by double-spending for example, the `frontend` should pass the reply verbatim to the browser/wallet. This should be the expected case, as the `frontend` cannot really make mistakes; the only reasonable exception is if the `backend` is unavailable, in which case the customer might appreciate some reassurance that the merchant is working on getting his systems back online. diff --git a/banks.rst b/banks.rst deleted file mode 100644 index c6565261..00000000 --- a/banks.rst +++ /dev/null @@ -1,131 +0,0 @@ -=================================== -Interaction with banks Web portals -=================================== - -This section describes the interactions that should occur between -a wallet and a bank which chooses to adapt its Web portal to interact -with the Taler wallet. This interaction is supposed to occur when -the user is sending a SEPA transfer to some mint (i.e. he is creating -a new reserve). - -Through this interaction, the wallet can generate a new reserve's public -key and insert it into the 'subject' field of the transfer without manual -copy&paste. Secondly, the wallet is then able to fetch the amount to be -tranferred to the mint directly from the Web form, in order to poll the mint -to check if the desired amount has been transferred. - ----------------------- -Mutual acknowledgement ----------------------- - -The mutual acknowledgement between a wallet and a bank portal occurs when -the user is on the page which hosts the SEPA form, and is realized by the -mean of JavaScript signals issued on the `body` HTML element. - -When the bank wants to notify to a wallet, it sends the following event: - - .. js:data:: taler-wire-probe - -This event must be sent from a callback for the `onload` event of the -`body` element, otherwise the extension would have not time to -register a listener for this event. It also needs to be sent when -the Taler extension is dynamically loaded, like when the user activates -the extension while he is on the SEPA form page. This is done by -listening for the - - .. js:data:: taler-load - -event. If the Taler extension is present, it will respond with a - - .. js:data:: taler-wallet-present - -event. The handler should then activate its mechanism to trigger the generation -of a new reserve key in the wallet, for example by updating the DOM to enable a -dedicated button. - -If the Taler extension is unloaded while the user is visiting a SEPA form page, -the page should listen for a - - .. js:data:: taler-unload - -event, in order to hide the previously enabled button. - -------------------------- -How to trigger the wallet -------------------------- - -This interaction will make the wallet generate a new reserve public key, -as well as allowing the user to choose his wanted mint. Finally, the wallet -will directly paste this information inside the SEPA form and submit it. -Lastly, it allows the wallet to fetch the desired amount to be transferred -to the mint from the SEPA form. Typically, this trigger is initiated by the -user pushing a button while he is on the page which hosts the SEPA Web form. - -The wallet listens to a - - .. js:data:: taler-create-reserve - -event, through which it expects to receive the following object: - -.. sourcecode:: javascript - - {form_id: sepa-form-id, - input_amount: input-amount-id, - input_pub: input-pub-id, - mint_rcv: receiving-money-mint} - -`input_amount` is the `id` attribute of the HTML `input` element which -hosts the amount to wire to the desired mint. Please note that the wallet will -only accept amounts of the form `n[.x[y]] CUR`, where `CUR` is the ISO code -of the specified currency. So it may be necessary for the bank's webmaster to -preprocess this data to give it to the wallet in the right format. - -`input_pub` must be the `id` attribute of the `input` element within the form -which represents this SEPA transfer's "subject". -`form_id` must be the `id` attribute of the SEPA `form` element (needed by the wallet to -call `submit()` on it). -Finally, `mint_rcv` is the `id` attribute of the `input` element within the form -from which the server side handler of this form will fetch the mint base URL to issue -`/admin/add/incoming` on; see :ref:`add-incoming`. - -The following source code highlights the key steps for adding the Taler button -to trigger the wallet on a SEPA form page: - -.. sourcecode:: javascript - - function has_taler_wallet_callback(aEvent){ - // This function is called if a Taler wallet is available. - // suppose the radio button for the Taler option has - // the DOM ID attribute 'taler-wallet-trigger' - var tbutton = document.getElementById("taler-wallet-trigger"); - tbutton.removeAttribute("disabled"); - }; - - function taler_wallet_load_callback(aEvent){ - // let the Taler wallet know that this is a SEPA form page - // which supports Taler (the extension will have - // missed our initial 'taler-wire-probe' from onload()) - document.body.dispatchEvent(new Event('taler-wire-probe')); - }; - - function taler_wallet_unload_callback(aEvent){ - // suppose the button which triggers the wallet has - // the DOM ID attribute 'taler-wallet-trigger' - var tbutton = document.getElementById("taler-wallet-trigger"); - tbutton.setAttribute("disabled", "true"); - }; - -.. sourcecode:: html - - - ... - diff --git a/index.rst b/index.rst index 1517cd8e..1a17a2d0 100644 --- a/index.rst +++ b/index.rst @@ -25,22 +25,44 @@ which is at the heart of the system. Operator Handbook ----------------- +The *Operator Handbook* is for people who want to run a mint or a merchant. +It focuses on how to install, configure and run the required software. + .. toctree:: :maxdepth: 2 impl-mint ----------------------- -Protocol Specification ----------------------- +------------------------ +Web Integration Handbook +------------------------ + +The *Web Integration Handbook* is for those who want to interact with Taler +wallets on their own website. Integrators will also have to be familiar with +the material covered in the *Operator Handbook*. + + +.. toctree:: + :maxdepth: 2 + + integration-general + integration-bank + integration-merchant + + +--------------------------- +HTTP Protocol Specification +--------------------------- + +The *Protocol Specification* defines the HTTP-based, predominantly RESTful +interfaces between the core components of Taler. .. toctree:: :maxdepth: 2 api-mint api-merchant - banks wallet @@ -51,15 +73,24 @@ Protocol Specification Developer Handbook ------------------ +The *Developer Handbook* brings developers up to speed who want to hack on the +core components of the Taler reference implementation. + .. toctree:: :maxdepth: 2 dev-wallet-wx + dev-merchant ------------------ Indices and tables ------------------ +.. toctree:: + :maxdepth: 1 + + glossary + * :ref:`search` diff --git a/integration-bank.rst b/integration-bank.rst new file mode 100644 index 00000000..58015cf2 --- /dev/null +++ b/integration-bank.rst @@ -0,0 +1,73 @@ +============================== +Interaction with bank websites +============================== + +This section describes how bank websites can interact with the +Taler wallet. + +Currently the following functionality is supported: + * Querying for the presence of a Taler wallet. + * Receiving change notifications from the Taler wallet. + * Creating a reserve. + + +For JavaScript code examples, see :ref:`communication`. + +-------------- +Presence Query +-------------- + +The bank website queries the wallet's presence by sending a ``taler-wire-probe`` event. The +event data should be `null`. + +If the wallet is present and active, it will respond with a ``taler-wallet-present`` event. + +------------------- +Change Notification +------------------- + +While the user agent is displaying a bank website, the user might deactivate or +re-activate the wallet. A bank website *should* react to those events, and +indicate to the user that they should (re-)enable if necessary. + +When the wallet is activated, the ``taler-wallet-load`` event is sent +by the wallet. When the wallet is deactivated, the ``taler-wallet-unload`` event +is sent by the wallet. + +------------------------- +Reserve Creation Request +------------------------- + +The bank website can request the creation of a :term:`reserve`. Note that the +user will always be prompted by the wallet before a reserve is created in the +wallet. + +As a result of the reserve creation request, the following steps will happen insequence: + 1. The wallet will prompt the user for the *mint base URL* and ask the user to + confirm creating the reserve. + 2. The wallet will create a key pair for the reserve. + 3. The wallet will make a request to the bank, containing + the reserve's public key and the mint base URL chosen by the user + +The bank should then take steps that will establish the reserve at the +customer's requested mint. This could, depending on the bank and mint, either +be a SEPA wire transfer or some other means. + +In response to the reserve creation request, the Taler wallet MAY cause the +current document location to be changed, in order to navigate to a +wallet-internal confirmation page. + +The bank requests reserve creation with the ``taler-create-reserve`` event. +The event data must be a JavaScript ``object`` with the following fields: + + * ``form_id``: The ``id`` of the ``form`` HTML element that contains data for the HTTP POST request + that confirms reserve creation with the bank. + * ``input_amount``: Amount of the reserve in the format ``N.C CUR``, where ``CUR`` is the + currency code. + * ``mint_rcv``: The ``id`` of the ``input`` HTML element in the reserve creation form + that will contain mint base URL for the reserve + * ``input_pub``: The ``id`` of the ``input`` HTML element in the reserve creation form + that will contain the reserve's public key. + +Note that the bank website MUST contain an HTML form with the data required for the request and +input fields for receiving data from the mint. -- cgit v1.2.3