commit b186387b512b941c080fb123daa4eed193d807ef
parent 8d788b2b6a319deef49f267b8966bfe226bcbc20
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Mon, 25 Mar 2024 21:50:39 +0100
docs: draft architecture
Diffstat:
9 files changed, 52 insertions(+), 7 deletions(-)
diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex
@@ -6,6 +6,16 @@ The API of the C2EC (cashless2ecash) component handles the flow from the creatio
The exact specification can be found in the official Taler docs repository as part of the core specifications \cite{taler-c2ec-spec}
+\subsection{C2EC Perspective}
+From the perspective of C2EC, the system looks as follows:
+
+\begin{itemize}
+ \item Is requested by the \textit{Taler Wallet} to register a new \textit{wopid} to reserve public key mapping.
+ \item Is notified by the \textit{Wallee Terminal} about a payment.
+ \item Attests a payment by requesting the payment proof at the \textit{Wallee Backend}
+ \item Supplies the Taler Wire Gateway API that the respective \textit{Exchange} can retrieve new transactions and create reserves which are then created and can be withdrawn by the \textit{Taler Wallet}.
+\end{itemize}
+
\subsection{Withdrawal-Operation state transitions}
Basically C2EC mediates between the stakeholders of a withdrawal in order to maintain the correct state of the withdrawal. Therefore it decides when a withdrawal's status can be transitioned. The diagram in \autoref{fig-withdrawal-operation-state-transition-diagram} shows the transitions of states in which a withdrawal operation can be and which events will trigger a transition. The term attestation in this context means, that the backend of the provider was asked and the transaction was successfully processed (or not). So if a transaction was successfully processed by the provider, the final state is the success case \textit{confirmed}, where the \textit{Exchange} will create a reserve and allow the withdrawal. If the attestation fails, thus the provider could not process the transaction successfully, the failure case \textit{aborted}, is reached as final state.
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -2,16 +2,15 @@
\begin{figure}[h]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/system_overview.png}
- \caption{Diagram of included components and their interactions}
- \label{fig-diagram-all-components}
+ \includegraphics[width=0.7\textwidth]{pictures/diagrams/components_images.png}
+ \caption{Involved components and devices}
+ \label{fig-logo-components}
\end{figure}
The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card owned by the user, two systems are involved and within each system two components are required to fulfill the task. The Taler ecosystem which represents the Taler Wallet and the Taler Exchange (C2EC is a part of the Exchange) involved in the withdrawal process. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process. The numbers in the diagrams are picked up by the description of the process further down.
\section{Process}
-
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/diagrams/nonce2ecash.png}
@@ -19,7 +18,14 @@ The component diagram shows the components involved by the withdrawal using the
\label{fig-diagram-all-sequence}
\end{figure}
-The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to withdraw digital cash using the credit card terminal and Taler. It shows when the components of \autoref{fig-diagram-all-components} interact with each other. It shows the implementation of the flow. Terminal, Wallet and Exchange are linked leveraging a \textit{wopid} initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a public key.
+The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to withdraw digital cash using the credit card terminal and Taler. It shows when the components of \autoref{fig-diagram-all-components} interact with each other. It shows the implementation of the flow. Terminal, Wallet and Exchange are linked leveraging a \textit{wopid} initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a reserve public key.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/diagrams/system_overview.png}
+ \caption{Diagram of included components and their interactions}
+ \label{fig-diagram-all-components}
+\end{figure}
The process requires three parties interacting with each other. The Terminal, the Wallet and the Exchange must therefore interact with each other. In this section the highlevel process as showed in \autoref{fig-diagram-all-sequence} is explained.
diff --git a/docs/content/architecture/wallee.tex b/docs/content/architecture/wallee.tex
@@ -1,6 +1,15 @@
\section{Wallee}
Wallee offers level 1 PCI-DSS \cite{pci-dss} compliant payment processes to its customers \cite{wallee-pcidss-compliance} and allows an easy integration of its process into various kinds of merchant systems (e.g. websites, terminals, etc).
+\subsection{Wallee Perspective}
+From the perspective of Wallee, the system looks as follows:
+
+\begin{itemize}
+ \item Uses the Bank-Integration API of \textit{C2EC} to get notified about parameter selection and inform \textit{C2EC} about the payment.
+ \item Needs the credit card of the customer in order to execute the payment.
+ \item Uses the \textit{Wallee Backend} to execute the payment using the supplied Android Till SDK \autoref{ref-wallee-till-api}
+\end{itemize}
+
\subsection{Wallee Terminal}
Wallee Terminals are based on android and run a modified, certified android version as operating system. Thus they can be used for payments and establish strong authentication in a trusted way.
@@ -12,6 +21,10 @@ The Wallet gains the \textit{wopid} value when scanning the QR code at the Termi
Besides the entropy needed to establish a correct \textit{wopid}, the hash function leveraged must be specified. (TODO - 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))
+\subsubsection{Wallee Till API}
+\label{ref-wallee-till-api}
+Wallee supplies the Wallee Android Till SDK \cite{wallee-till-sdk} which allows the implementation of custom application for their android based terminals. The API facilitates the integration with the Wallee backend and using it to create payments.
+
\subsection{Wallee Backend and API}
Terminals of Wallee are used to communicate with the customer at the shop of the merchant. The payment and processing of the transaction is run on the \textit{Wallee Backend}. The \textit{Wallee Backend} is used by C2EC to attest a payment, when a \texttt{C2ECPaymentNotification} message reaches C2EC. The \textit{Wallee Backend} is also used in order to do refunds, in case something goes wrong during the payment. Therefore the API of \textit{Wallee Backend} is used to collect this information or process a refund. Wallee structures its API using \textit{Services}. For C2EC this means that the \textit{Transaction Service} \cite{wallee-transaction-service-docs} and \textit{Refund Service} \cite{wallee-refund-service-docs} must be implemented.
diff --git a/docs/content/architecture/wallet.tex b/docs/content/architecture/wallet.tex
@@ -2,4 +2,13 @@
The \textit{Taler Wallet} is responsible to create a reserve key pair which will allow him the withdrawal using the \textit{Exchange} using the reserve public key of the key pair.
-The reserve public key is created by the \textit{Taler Wallet} and sent to C2EC to establish the mapping between the \textit{wopid} and the reserve public key. The reserve public key is used to eventually create a reserve at the exchange which contains the digital cash. The \textit{Taler Wallet} can then withdraw the digital cash from this reserve using the withdrawal process of the wallet \cite{wallet-withdrawal}. The process for the case of C2EC is slightly different from the present processes because the requests to the Bank-Integration API contain different properties than the currently supported. This means the \textit{Taler Wallet} must be extended in order to allow the withdrawal using C2EC.
-\ No newline at end of file
+The reserve public key is created by the \textit{Taler Wallet} and sent to C2EC to establish the mapping between the \textit{wopid} and the reserve public key. The reserve public key is used to eventually create a reserve at the exchange which contains the digital cash. The \textit{Taler Wallet} can then withdraw the digital cash from this reserve using the withdrawal process of the wallet \cite{wallet-withdrawal}. The process for the case of C2EC is slightly different from the present processes because the requests to the Bank-Integration API contain different properties than the currently supported. This means the \textit{Taler Wallet} must be extended in order to allow the withdrawal using C2EC.
+
+\subsection{Taler Wallet Perspective}
+From the perspective of the Wallet, the system looks as follows:
+
+\begin{itemize}
+ \item Uses the QR Code displayed on the \textit{Wallee Terminal} to identify nonce and read exchange information.
+ \item Uses the Bank-Integration API of \textit{C2EC} to register the reserve public key and retrieve information about the confirmation of the withdrawal.
+ \item Uses the \textit{Exchange} to withdraw the digital cash.
+\end{itemize}
+\ No newline at end of file
diff --git a/docs/pictures/diagrams/components_images.png b/docs/pictures/diagrams/components_images.png
Binary files differ.
diff --git a/docs/project.bib b/docs/project.bib
@@ -50,6 +50,13 @@
howpublished = {\url{https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0.pdf}}
}
+@misc{wallee-till-sdk,
+ author = {Wallee},
+ title = {Wallee Android Till SDK},
+ url = {https://github.com/wallee-payment/android-till-sdk},
+ howpublished = {\url{https://github.com/wallee-payment/android-till-sdk}}
+}
+
@misc{wallee-transaction-process,
author = {Wallee},
title = {Transaction States},
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
diff --git a/specs/components_images.odg b/specs/components_images.odg
Binary files differ.
diff --git a/specs/components_images.webp b/specs/components_images.webp
Binary files differ.
