commit 639234ecba71478d20482d27a203f9224242d259
parent d556d2d26c59ae9a8af7da2ec993bbf3d1b32b03
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Wed, 20 Mar 2024 12:24:50 +0100
docs: draft payto REFUND
Diffstat:
9 files changed, 114 insertions(+), 2 deletions(-)
diff --git a/docs/content/architecture/nonce2ecash.tex b/docs/content/architecture/nonce2ecash.tex
@@ -53,4 +53,32 @@ Withdrawals with a nonce2ecash are based on withdrawal operations which register
The database of the nonce2ecash component must track two different aspects. The first is the mapping of a nonce to a reserve public key to enable withdrawals and the second aspect is the authentication of terminals allowing withdrawals owned by terminal providers like \textit{Wallee}.
-
+\subsubsection{Terminal Provider}
+Table in \autoref{fig-erd-terminal-provider} describing providers of nonce2ecash terminals. The name of the provider is important, because it decides which flow shall be taken in order to attest the payment.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
+ \caption{Terminal Provider Table}
+ \label{fig-erd-terminal-provider}
+\end{figure}
+
+\subsubsection{Terminal}
+Table in \autoref{fig-erd-terminal} contains information about terminals of providers. This includes the provider they belong to and an authentication token, which is generated by the Exchange and allows authenticating the terminal. A terminal belongs to one terminal provider.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
+ \caption{Terminal Table}
+ \label{fig-erd-terminal}
+\end{figure}
+
+\subsubsection{Withdrawal}
+Table in \autoref{fig-erd-withdrawal} represents the withdrawal processes initiated by terminals. This table therefore contains information about the withdrawal like the amount, which terminal the withdrawal was initiated from and which reserve public key is used to create a reserve in the Exchange.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
+ \caption{Withdrawal Table}
+ \label{fig-erd-withdrawal}
+\end{figure}
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -73,3 +73,30 @@ The Wallet must attest its presence to the terminal by registering a nonce and b
\item The Wallet sends the reserve public key and the scanned nonce to the Exchange
\item The Wallet can withdraw money from the created reserve.
\end{enumerate}
+
+\subsection{Nonce}
+The nonce is leveraged by all components to establish the connection to an entry in the mapping table of nonce2ecash. The nonce is therefore crucial and every participant of the withdrawal must eventually gain knowledge about the value of the nonce in order to process the withdrawal. The nonce is created by the Terminal and advertised to the Exchange by requesting notification, when the reserve public key belonging to the nonce was received and the mapping could be created.
+The Wallet gains the nonce value when scanning the QR code at the Terminal and then sends the nonce (and the other parameters) to the Exchange.
+
+\subsubsection{Nonce creation}
+Besides the entropy needed to establish a correct nonce, the hash function leveraged must be specified. (TODO - possibly one of FIPS 180-4 or FIPS 202 families)
+
+\subsection{Reserve Public Key}
+The reserve public key is created by the Wallet and sent to the Exchange to establish the mapping between the nonce and the reserve public key. The reserve public key, can then be retrieved by the Terminal and used during the payment. The reserve public key is used to eventually create a reserve at the exchange which contains the money. The Wallet can then withdraw the money from this reserve using the withdrawal process of the wallet \cite{wallet-withdrawal}.
+
+\subsection{Payto REFUND extension}
+RFC 8905 \cite{rfc8905} specifies a URI scheme (complying with RFC 3986 \cite{rfc3986}), which allows to address a creditor with theoretically any protocol that can be used to pay someone (such as IBAN, BIC etc.) in a standardized way. Therefore it introduces a registry which holds the specific official values of the standard.
+
+For the case of refunds, which might occur in case a credit card transaction does not succeed, a new \textit{target type} called REFUND is registered. It takes a transaction identifier as \textit{target identifier} which identifies the transaction for which a refund process shall be triggered. The idea is that the receiver of the payto URI is able to deduct the transaction and handle the specific process. Like this any refund process can be handled through this single \textit{target type}.
+
+The transaction identifier is not provider agnostic. This means that the identifier can be sourced by various formatted identifiers, depending on the originating system. Therefore, the transaction identifier is a hash of the actual identifier allowing a standardized format for the \textit{target identifier}. This requires the owner of the process triggering the refund to maintain a mapping of the \textit{target identifier} and the respective hash. The owner of the process triggering the refund of the transaction could also hash every transaction-id on request, but this will possibly lead to bad performance and bad style.
+
+The idea of the REFUND \textit{target type} is to trigger a refund process by the owner of the refund process without other services needing to deal with the refund logic. Therefore transactions which allow refund but the receiver cannot directly execute the refund, the payto REFUND \textit{target type} can be used to advice the owner to of the refund process, to execute the refund linked to the transaction identifier supplied using the \textit{target identifier}, which is a hash of the transaction identifier.
+
+\subsubsection{Refund Target Identifier Hash}
+In order to allow a generic adoption of the REFUND \textit{target type}, the transaction identifier must be transformed to a general format. Therefore a hash function can be leveraged. This hash function must be configurable and therefore the \textit{generic option} called \textit{instruction} holds the name of the hash function. The name shall correspond to one of the offical terms used in e.g. FIPS 180-4 \cite{fips-180-4} (SHA-1 and SHA-2 families) or FIPS-202 \cite{fips-202} (SHA-3 family, which is still beeing reviewed). This allows the provider of the refund process to choose the applied hash function and the hash can also be migrated to other hashes in case a hash becomes unusable for an arbitrary reason.
+
+\subsubsection{Payto refund using Wallee}
+Wallee allows to trigger refunds using the Refund Service of the Wallee backend. The service allows to trigger a refund given a transaction identifier. Therefore the nonce2ecash component can trigger the refund using the refund service if needed, and the payto-uri retrieved as debit account by the wirewatch gateway API, is leveraged to delegate the refund process to the Wallee Backend using the Refund Service.
+
+\pagebreak
+\ No newline at end of file
diff --git a/docs/content/sysview/taler.tex b/docs/content/sysview/taler.tex
@@ -4,4 +4,6 @@ GNU Taler is a payment system which allows paying for goods in an anonymous way
\subsection{Wirewatch Gateway RESTful API}
-The wirewatch gateway helps communicating with the Exchange core using a convenient API. This includes retrieving information about transactions which were sent through the EBICS system. EBICS stands for \textit{Electronic Banking Internet Communication Standard} and represents an interface for interbank communication based on TCP/IP. Taler can retrieve incoming transaction through the EBICS interface using the Taler Nexus component, which acts as subscriber to an EBICS instance. This will help nonce2ecash to capture the transaction of the Terminal Backend to the Exchange's account and therefore allow the withdrawal by the customer. Therefore the wirewatch gateway API is used in nonce2ecash. When the wirewatch gateway captures a transaction pointed to the Exchanges account, it will automatically create a reserve if the payment purpose contains a valid reserve public key.
+The wirewatch gateway helps communicating with the Exchange core using a convenient API. It helps the Exchange to get guarantees, that a certain transaction went through and that the reserve can be created and withdrawn. This will help nonce2ecash to capture the transaction of the Terminal Backend to the Exchange's account and therefore allow the withdrawal by the customer. Therefore the wirewatch gateway API is used in nonce2ecash. When the wirewatch gateway captures a transaction pointed to the Exchanges account, it will automatically create a reserve with the corresponding reserve public key.
+
+
diff --git a/docs/pictures/database/table_terminal.png b/docs/pictures/database/table_terminal.png
Binary files differ.
diff --git a/docs/pictures/database/table_terminal_provider.png b/docs/pictures/database/table_terminal_provider.png
Binary files differ.
diff --git a/docs/pictures/database/table_withdrawal.png b/docs/pictures/database/table_withdrawal.png
Binary files differ.
diff --git a/docs/pictures/diagrams/layer_diagram.png b/docs/pictures/diagrams/layer_diagram.png
Binary files differ.
diff --git a/docs/project.bib b/docs/project.bib
@@ -57,3 +57,57 @@
month = jan,
abstract = {This document registers the "secret-token" URI scheme to aid in the identification of authentication tokens.},
}
+
+@misc{rfc8905,
+ series = {Request for Comments},
+ number = 8905,
+ howpublished = {RFC 8905},
+ publisher = {RFC Editor},
+ doi = {10.17487/RFC8905},
+ url = {https://www.rfc-editor.org/info/rfc8905},
+ author = {Florian Dold and Christian Grothoff},
+ title = {{The 'payto' URI Scheme for Payments}},
+ pagetotal = 12,
+ year = 2020,
+ month = oct,
+ abstract = {This document defines the 'payto' Uniform Resource Identifier (URI) scheme for designating targets for payments. A unified URI scheme for all payment target types allows applications to offer user interactions with URIs that represent payment targets, simplifying the introduction of new payment systems and applications.},
+}
+
+@misc{rfc3986,
+ series = {Request for Comments},
+ number = 3986,
+ howpublished = {RFC 3986},
+ publisher = {RFC Editor},
+ doi = {10.17487/RFC3986},
+ url = {https://www.rfc-editor.org/info/rfc3986},
+ author = {Tim Berners-Lee and Roy T. Fielding and Larry M Masinter},
+ title = {{Uniform Resource Identifier (URI): Generic Syntax}},
+ pagetotal = 61,
+ year = 2005,
+ month = jan,
+ abstract = {A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. {[}STANDARDS-TRACK{]}},
+}
+
+@misc{fips-180-4,
+ author = {Quynh Dang},
+ title = {Secure Hash Standard},
+ year = {2015},
+ month = {2015-08-04},
+ publisher = {Federal Inf. Process. Stds. (NIST FIPS), National Institute of Standards and Technology, Gaithersburg, MD},
+ doi = {https://doi.org/10.6028/NIST.FIPS.180-4},
+ language = {en},
+}
+
+@misc{fips-202,
+ author = { National Institute of Standards and Technology },
+ title = {SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions},
+ url = {https://doi.org/10.6028/NIST.FIPS.202},
+ howpublished = {\url{https://doi.org/10.6028/NIST.FIPS.202}},
+}
+
+@misc{wallet-withdrawal,
+ author = {Taler},
+ title = {Withdrawal},
+ url = {https://docs.taler.net/taler-wallet.html#withdrawal},
+ howpublished = {\url{https://docs.taler.net/taler-wallet.html#withdrawal}}
+}
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
