diff options
| -rw-r--r-- | articles/ui/ui.tex | 147 |
1 files changed, 62 insertions, 85 deletions
diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex index d1f95523b..c48d76494 100644 --- a/articles/ui/ui.tex +++ b/articles/ui/ui.tex @@ -825,9 +825,12 @@ X-Taler-Contract-Url: https://shop/generate-contract/42 \label{listing:http-contract} \end{figure*} +\subsubsection{Offer} + The offer URL of the Web shop can then initiate payments by sending a -\emph{contract proposal} (Figure~\ref{listing:json-contract}) to the wallet, either via the HTTP status -code {\tt 402 Payment Required} (Figure~\ref{listing:http-contract}), or via Taler's JavaScript API +\emph{contract proposal} (Figure~\ref{listing:json-contract}) to the +wallet, either via the HTTP status code {\tt 402 Payment Required} +(Figure~\ref{listing:http-contract}), or via Taler's JavaScript API (Figure~\ref{listing:contract}). The wallet then presents the contract to the user. The format of the contract is in an extensible JSON-based format defined by Taler and not HTML, as the rendering of @@ -836,16 +839,6 @@ representation of the terms and prices. In case that transaction fees need to be covered by the customer, these are shown together with the rest of the proposed contract. -If the customer approves the contract by clicking the ``Confirm -Payment'' button (Figure~\ref{subfig:payment}), their wallet signs the -contract with enough coins to cover the contract's cost, stores all of -the information in its local database, and transmits the payment to -the {\em payment} URI of the Web shop. Once the Web shop confirms the -payment, the wallet redirects the browser to the {\em fulfillment} URL -provided by the merchant (Figure~\ref{subfig:fulfillment}). - -\subsection{Browser security} - The Taler wallet operates from a securely isolated {\em background} context on the client side. The user interface that displays the contract and allows the user to confirm the payment is displayed by @@ -857,44 +850,62 @@ wallet's payment page (Figure~\ref{subfig:payment}), as such a page would still not have access to the private keys of the coins that are exclusive to the background context. -%The current Taler specification is written to accommodate for -%the rather restrictive set of APIs that WebExtension, a -%cross-browser extension API, provides. - -\subsection{Managing browser session state} - -% FIXME: this is where we probably want to revise quite a bit, -% including improving the description AND addressing the JS-less -% implementation. - -% Say that this doesn't require accounts! -% explain that HTTP session state can be restored -% from the wallet state (replay!) - -% explain repurchase correlation ID - -% contract vs complete fulfillment URL - -% design that allows merchant to not store any information - -A purchase by a customer, completed or in progress, is uniquely -identified by a URL, called the \emph{fulfillment URL}. The -information contained in the fulfillment URL must allow the merchant -to restore the full contract that was associated with the purchase, -either directly from the URL or indirectly from an identifier in a -database. Efficiently reconstructing the contract entirely from the -URL instead of using costly database transactions can be important, as -costly disk operations for incomplete purchases make merchants -more susceptible to denial-of-service attacks from adversaries -pretending to be customers. - -When a customer completed a purchase, navigating to the fulfillment -URL in a browser will show the resource associated with the purchase. -This resource can be a digital good such as a news article, or simply -a confirmation for products that are delivered by other means. - -% FIXME: maybe we should have the URL that we are requesting -% in the example, and not just the response? +If the customer approves the contract by clicking the ``Confirm +Payment'' button (Figure~\ref{subfig:payment}), their wallet signs the +contract with enough coins to cover the contract's cost, stores all of +the information in its local database, and redirects the browser to +the {\em fulfillment} URL provided by the merchant in the contract +(Figure~\ref{subfig:fulfillment}). + +\subsubsection{Fulfillment} + +The fulfillment URL uniquely identifies a purchase by some customer, +while the offer URL identifies a generic offer that is not specific to +a customer. The purchase identified by a fulfillment URL may have +been completed or still be in progress. The information contained in +the fulfillment URL must allow the merchant to restore the full +contract (including a unique transaction identifier) that was +associated with the purchase, either directly from the URL or +indirectly from an identifier in a database. Efficiently +reconstructing the contract entirely from the URL instead of using +costly database transactions can be important, as costly disk +operations for incomplete purchases make merchants more susceptible to +denial-of-service attacks from adversaries pretending to be customers. + +When a customer has completed a purchase, navigating to the +fulfillment URL in a browser will show the resource associated with +the purchase. This resource can be a digital good such as a news +article, or simply a confirmation for products that are delivered by +other means. + +When a customer has not yet completed a purchase (this is always the +case when a customer visits the fulfillment URL for the first time), +or when the Web shop cannot confirm that this visitor has paid for the +contract, for example because the session state was +lost,\footnote{This can happen when when privacy conscious users + delete their cookies. Also, some user agents (such as the TOR + browser) do not support persistent (non-session) cookies.} the Web +store responds by (again) triggering a payment process (either via +JavaScript or using {\tt 402 Payment Required}, see +Figure~\ref{listing:http-execute}). However, unlike the response from +the offer URL, the 402 response from the fulfillment page includes the +headers {\tt X-Taler-Contract-Hash}, {\tt X-Taler-Pay-Url} and {\tt + X-Taler-Offer-Url}. + +If the contract hash matches a payment which the user already +previously approved, the wallet reacts to this by injecting the logic +to transmit the payment to the {\em pay} URL of the Web shop into +the page. Then the wallet inspects the response as it may contain +error reports about a failed payment which the wallet has to handle. +By submitting the payment this way, we also ensure that this +intermediate request does not require JavaScript and still does not +interfer with navigation. Once the Web shop confirms the payment, the +wallet causes the fulfillment URL to be reloaded. + +If the contract hash does not match a payment which the user +already approved, for example because the user obtained the link +from another user, the wallet navigates to the offer URL included +in the header. \begin{figure*}[t!] \lstset{language={}} @@ -922,41 +933,7 @@ X-Taler-Offer-Url: https://shop/generate-contract/42 \label{listing:http-execute} \end{figure*} -In order to ensure that only the paying customer has access to the Web -resources behind the fulfillment URL, the Web store's server must -check the browser's session state. If the merchant can confirm that -the visitor has paid, the respective Web resource is returned. If the -merchant cannot confirm that the visitor has paid for the contract, -for example because the session state was lost,\footnote{This can - happen when when privacy conscious users delete their cookies. - Also, some user agents (such as the TOR browser) do not support - persistent (non-session) cookies.} it {\em again} triggers a payment -process (either via JavaScript or using {\tt 402 Payment Required}, see Figure~\ref{listing:http-execute}). -Since the fulfillment URL refers to a contract that typically is already known -to the user's wallet, it suffices to pass the contract hash (instead of -full contract) to the wallet. -If the user previously approved paying for the contract with this hash, the -wallet will (re-)transmit the signed coins that are associated -with the contract to the merchant. - -When a user visits a fulfillment URL without having the associated -contract in their wallet, the wallet redirects the browser to the {\em - offer} URL for that purchase, if applicable. This behavior is -useful when a user wishes to share a fulfillment link with another -user to point him to the same resource. - -Note that due to the limited WebExtensions API, the session state can -only be acquired when the wallet causes the browser to navigate to the -fulfillment URL (first without session state), since the session state -must be set from the same origin as the fulfillment URL. As a result, -the shop cannot simply return the fulfillment information in response -to the wallet performing the payment. However, this extra round trip -is also justified as the wallet needs to inspect the response anyway -as it may contain error reports about a failed payment which the wallet -has to handle. Finally, it ensures that the fulfillment page is fetched -via an HTTP GET request instead of an HTTP POST request, which is -important to nicely support the use of navigation (``back'', ``forward'' -buttons) and bookmarks. +\subsubsection{Discussion} Various failure modes are considered in this design: |