[taler-cashless2ecash] branch master updated: docs: draft architecture

[gnunet]

This is an automated email from the git hooks/post-receive script.

joel-haeberli pushed a commit to branch master
in repository cashless2ecash.

The following commit(s) were added to refs/heads/master by this push:
     new b186387  docs: draft architecture
b186387 is described below

commit b186387b512b941c080fb123daa4eed193d807ef
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Mon Mar 25 21:50:39 2024 +0100

    docs: draft architecture
---
 docs/content/architecture/c2ec.tex           |  10 ++++++++++
 docs/content/architecture/overview.tex       |  16 +++++++++++-----
 docs/content/architecture/wallee.tex         |  13 +++++++++++++
 docs/content/architecture/wallet.tex         |  11 ++++++++++-
 docs/pictures/diagrams/components_images.png | Bin 0 -> 131896 bytes
 docs/project.bib                             |   7 +++++++
 docs/thesis.pdf                              | Bin 1463120 -> 1571422 bytes
 specs/components_images.odg                  | Bin 0 -> 302162 bytes
 specs/components_images.webp                 | Bin 0 -> 80158 bytes
 9 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/docs/content/architecture/c2ec.tex 
b/docs/content/architecture/c2ec.tex
index e3f5409..7bcb587 100644
--- 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 [...]
diff --git a/docs/content/architecture/overview.tex 
b/docs/content/architecture/overview.tex
index 4ed2aeb..731002a 100644
--- 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 proces [...]
 
 \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
index 9d682e2..3251924 100644
--- 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 inform [...]
 
diff --git a/docs/content/architecture/wallet.tex 
b/docs/content/architecture/wallet.tex
index 7882bf6..483d49c 100644
--- 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 p [...]
\ 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 p [...]
+
+\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
new file mode 100644
index 0000000..fd545d6
Binary files /dev/null and b/docs/pictures/diagrams/components_images.png differ
diff --git a/docs/project.bib b/docs/project.bib
index 1da4b60..fa73952 100644
--- 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
index 35eac69..017dbea 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ
diff --git a/specs/components_images.odg b/specs/components_images.odg
new file mode 100644
index 0000000..14df174
Binary files /dev/null and b/specs/components_images.odg differ
diff --git a/specs/components_images.webp b/specs/components_images.webp
new file mode 100644
index 0000000..4b4949e
Binary files /dev/null and b/specs/components_images.webp differ

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.