commit b44d71d4ec23b1349a394f5321584b5bf1ce7e00 parent bae792a2d72746036d720d43e42e87b2bee266e1 Author: Joel-Haeberli <haebu@rubigen.ch> Date: Thu, 22 Feb 2024 20:55:21 +0100 docs: init Diffstat:
51 files changed, 1835 insertions(+), 0 deletions(-)
diff --git a/.gitignore b/.gitignore @@ -0,0 +1,126 @@ +LocalMakefile + +*.png +!/docs/**/*.png + +#################### +### LaTex ignore ### +#################### +## see https://gitlab.ti.bfh.ch/bfh-latex/bfh-ci/-/blob/master/.gitignore + +reports +*.zip +*.tar* +_* + +### LaTeX ### +## Core latex/pdflatex auxiliary files: +*.aux +*.lof +*.log +*.lot +*.fls +*.out +*.toc +*.fmt +*.fot +*.cb +*.cb2 +.*.lb + +## Intermediate documents: +*.dvi +*.xdv +*-converted-to.* + +## Bibliography auxiliary files (bibtex/biblatex/biber): +*.bbl +*.bcf +*.blg +*-blx.aux +*-blx.bib +*.run.xml + +## Build tool auxiliary files: +*.fdb_latexmk +*.synctex +*.synctex(busy) +*.synctex.gz +*.synctex.gz(busy) +*.pdfsync + +## Build tool directories for auxiliary files +# latexrun +latex.out/ +# BFH terminal module +report.listing + +## Auxiliary and intermediate files from other packages: +# algorithms +*.alg +*.loa + +# endnotes +*.ent + +# glossaries +*.acn +*.acr +*.glg +*.glo +*.gls +*.glsdefs +*.lzo +*.lzs + +# uncomment this for glossaries-extra (will ignore makeindex's style files!) +*.ist + +# listings +*.lol + +# makeidx +*.idx +*.ilg +*.ind + +### Linux ### + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +### OSX ### +# General +.DS_Store + +# Thumbnails +._* + +### Vim ### +# Swap +[._]*.s[a-v][a-z] +!*.svg # comment out if you don't need vector files +[._]*.sw[a-p] +[._]s[a-rt-v][a-z] +[._]ss[a-gi-z] +[._]sw[a-p] + +# Session +Session.vim +Sessionx.vim + +# Temporary +.netrwhist +# Auto-generated tag files +tags +# Persistent undo +[._]*.un~ diff --git a/README b/README @@ -0,0 +1,10 @@ +# Cashless to E-Cash + +In order to buy Taler using a terminal, transactions must be verified with the terminal operator. +This repository contains the code for the verification of such transactions. It stores a nonce generated +by the terminal operator and the reserve public-key for the withdrawal reserve. It implements long-polling to +the terminal operators backend in order to have an atomic proof that the transaction got through and +the exchange got the guarantee that the payment will eventually reach the exchanges bankaccount. + +The flow establishes trust not with the final transaction, but the authenticated guarantee, that the +terminal operator will eventually pay the amount to the bankaccount of the exchange. diff --git a/docs/Makefile b/docs/Makefile @@ -0,0 +1,11 @@ +all: pdf + +pdf: + latexmk -pdf thesis.tex + +clean-all: + latexmk -C + rm -Rf *.glg *.glo *.gls *.ist *.lol *.bbl + +clean: + latexmk -c +\ No newline at end of file diff --git a/docs/README.md b/docs/README.md @@ -0,0 +1,69 @@ +# How to use this template +This is a template for creating a thesis document (BSc or MSc) based on the bfh-ci package using the bfhthesis class. It helps to get started quickly. Problems and improvements can be reported via our issue tracker. Any kind of improvement is welcome, also other templates that cover a use case based on bfhthesis or bfhpub class. + +## Installing the dependencies +Install a recent LaTeX distribution and the latest version of the LaTeX package bfh-ci. How to do this is described in detail in the online manual. Follow the instructions for your operating system. + * https://latex.ti.bfh.ch + +## Information about the structure +The "*.tex" is a LaTeX document with a preamble and a LaTeX body with placeholder text. We recommend that you use this example as a quick introduction to writing short reports, such as a lab report. For an example of how to insert citations to online articles, books, etc., we recommend using biblatex. The bibliography database is stored in a ".bib" file. The content of such a file follows the definitions described in the biblatex user manual. Use the sample.bib file to get started. + +## Parameterization +There is a local `latexmk` configuration file called ".latexmkrc". This file contains some pre-configurations like the name of the output directory ("_build") and the default latex compiler ("lualatex"). Modify or delete this file. + +## Note +We recommend using Git for version control. If you are using Git, create a gitignore file with a good set of ignore patterns. For a quick start, we recommend the following patterns. + * Get a general set of ignore patterns + * https://www.toptal.com/developers/gitignore?templates=latex,windows,linux,vim,emacs,osx + ``` + curl -L -o .gitignore https://www.toptal.com/developers/gitignore/api/latex,windows,linux,vim,emacs,osx + ``` + * Ignore all directories that start with an underscore '_*/' + ``` + echo '_*/' >> .gitignore + ``` + +## Compiling +To compile the LaTeX document, use your favorite LaTeX editor together with the TeX compiler (xelatex and lualatex are supported). Thre is no support for pdflatex compiler. + +If you use latexmk on the command line, the following command will do the compilation. + +#### Running Latexmk + * In the simplest case you just have to type +```bash +latexmk -lualatex +``` + *This runs LaTeX on all .tex files in the current directory using the output format specified by the configuration files.* + + * If you want to make sure to get a .pdf file as output, just mention it: +```bash +latexmk -pdflua +``` + * If you want to compile only one specific .tex file in the current directory, just provide the file name: +```bash +latexmk -lualatex myfile.tex +``` + * If you want to preview the resulting output file(s), just use +```bash +latexmk -pv -lualatex +``` + * And now the killer feature: If you want LaTeXmk to continuously check all input files for changes and re-compile the whole thing if needed and always display the result, type +```bash +latexmk -pvc -lualatex -interaction=nonstopmode +``` +Then, whenever you change something in any of your source files and save your changes, the preview is automatically updated. But: This doesn’t work with all viewers, especially not with Adobe Reader. See the section about configuration files below for setting a suitable viewer application. + + * Of course, options can be combined, e.g. +```bash +latexmk -outdir=_build -pdf -pv myfile.tex +``` + +#### Cleanup + * After running LaTeX, the current directory is contaminated with a myriad of temporary files; you can get rid of them with +```bash +latexmk -c +``` + * Previous command doesn’t delete the final .pdf/.ps/.dvi files. If you want to delete those too, use +```bash +latexmk -C +``` diff --git a/README b/docs/content/.gitkeep diff --git a/docs/content/abstract.tex b/docs/content/abstract.tex @@ -0,0 +1,7 @@ +In order to buy Taler, the Taler Exchange needs guarantees to legally secure the payment. Buying Taler physically establishes +direct trust, since cash can be used in order to buy Taler and the transaction is completed. If you want +to buy Taler using cashless systems like credit cards, the Exchange has no proof that the payment has succeeded. +In order to fill this cap, this thesis establishes a trust relationship between the terminal manufacturer Wallee +and the Taler Exchange through a newly created component called 'cashless2ecash'. This enables a trust relationship +between the Taler Exchange and the terminal operator which allows withdrawing Taler without using cash. The liability for +the money is on the side of the terminal operator and therefore establishes the guarantees for the Taler Exchange. diff --git a/docs/content/appendix/meeting_notes.tex b/docs/content/appendix/meeting_notes.tex @@ -0,0 +1,149 @@ +\subsection*{17.01.2024} + +\textbf{Participants} + +\begin{itemize} + \item Fehrensen Benjamin + \item Grothoff Christian + \item H\"aberli Joel +\end{itemize} + +\textbf{Topics} +\begin{itemize} + \item Kickoff + \item Understanding the Task + \item Device + \item Taler +\end{itemize} + +\textbf{Questions} +\begin{itemize} + \item What am I going to do? + \item Which components are roughly involved? +\end{itemize} + +\textbf{Action points} +\begin{itemize} + \item Setup Thesis Document + \item GNU Taler Copyright Assignment + \item SSH-Public Key for git + \item Inspect taler-exchange-wirewatch +\end{itemize} + +\textbf{Decisions} +\begin{itemize} + \item Implement process 'cashless2ecash' as part of Taler-Exchange + \item Wallet initializes process by scanning QR code like in the 'cash2ecash' showcase + \begin{itemize} + \item cash2ecash was implented by the guy named "windfisch" on mattermost + \end{itemize} +\end{itemize} + +\subsection*{20.02.2024} + +\textbf{Participants} + +\begin{itemize} + \item Jung Florian + \item H\"aberli Joel +\end{itemize} + +\textbf{Topics} +\begin{itemize} + \item Introduce each other and explain ideas + \item Discuss nonce2ecash draft + \item Discuss who wants to do what +\end{itemize} + +\textbf{Action points} +\begin{itemize} + \item I send Flo a plan of what I'm going to do until when (approximately) + \item I update the sequence diagram as discussed and send the openapi spec to Flo for review. +\end{itemize} + +\textbf{Decisions} +\begin{itemize} + \item We can establish a generic approach for both our cases. Therefore the abstraction of \textit{Providers} will be implemented. The \textit{Providers} abstract and generalize some endpoint which can accept money in any form (Credit Card, Cash, and so on) and give the Exchange the guarantee, that the money will eventually be transferred to the Exchange. + \item The verification at the provider from the perspective of the exchange must be optional (withdrawing at an ATM will not get any better than the amount the ATM sends to the Excahnge in the payment notification). Therefore an additional request to the provider will not bring any benefit. +\end{itemize} + +\textbf{Notes} +\begin{itemize} + \item Flo wants to create a Reserve containing money from the ATM. He then wants to trigger a peer to peer transaction. And therefore this reserve deals as guarantee to the Exchange. This flow is possible if the provider is controlled, which in my case is not given (Wallee is a company and I cannot easily alter their source code to open a reserve) +\end{itemize} + +\subsection*{22.02.2024} + +\textbf{Participants} + +\begin{itemize} + \item Hiltgen Alain + \item Fehrensen Benjamin + \item Grothoff Christian + \item H\"aberli Joel +\end{itemize} + +\textbf{Topics} +\begin{itemize} + \item Task description + \item Deeper understanding of the topic established? + \item I contacted Florian Jung (alias Windfisch) and we bespoke his work on cash2ecash. + \begin{itemize} + \item Where do we draw the line (scope)? + \item Florian wants to hand in a "Förderantrag" to integrate the scan-before-withdraw feature into Taler Wallet. + \item Can I for the sake of my bachelor rely on his work, he is planning to do (therefore only adhere to a specified contract)? + \end{itemize} +\end{itemize} + +\textbf{Questions} +\begin{itemize} + \item Repository of Wallee Application will be different than 'cashless2ecash' (bfh gitlab)? + \item Wallee: Master Password? (Password received by Ben) + \item Wallee: Which SDK to use? Till-SDK (API to Wallee-Backend) + \item Taler / Wallee : Which nonce to use? How to generate the nonce? Is there a preferred kind to generate nonces within taler? + \item Do we add a maximal limit amount for a withdrawal on the side of the Taler Exchange? + \item How do we want to handle different currencies? How about currencies like Bitcoin? + \item How can I create a reserve from the mapping table? +\end{itemize} + +\textbf{Action points} +\begin{itemize} + \item +\end{itemize} + +\textbf{Decisions} +\begin{itemize} + \item +\end{itemize} + +% TEMPLATE % +\subsection*{TEMPLATE} + +\textbf{Participants} + +\begin{itemize} + \item Fehrensen Benjamin + \item Grothoff Christian + \item H\"aberli Joel +\end{itemize} + +\textbf{Topics} +\begin{itemize} + \item +\end{itemize} + +\textbf{Questions} +\begin{itemize} + \item +\end{itemize} + +\textbf{Action points} +\begin{itemize} + \item +\end{itemize} + +\textbf{Decisions} +\begin{itemize} + \item +\end{itemize} +% TEMPLATE % +\ No newline at end of file diff --git a/docs/content/architecture/bigpicture.tex b/docs/content/architecture/bigpicture.tex @@ -0,0 +1,81 @@ +\section*{Big Picture} + +\subsection*{Components} + +\begin{figure}[h] + \centering + \includegraphics[width=0.7\textwidth]{pictures/diagrams/component.png} + \caption{Diagram of included components} + \label{fig:diagram-all-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. We have the Taler system which represents the ecosystem for the Taler payment system with the Taler Wallet and the Taler Exchange involved in the withdrawal of Taler coins. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process. + +\begin{figure}[h] + \centering + \includegraphics[width=0.7\textwidth]{pictures/diagrams/nonce2ecash.png} + \caption{Diagram of high level flow} + \label{fig:diagram-all-sequence} +\end{figure} + +The diagram in \autoref*{fig:diagram-sequence} shows the high level flow to withdraw Taler using the credit card terminal. It shows when the components of \autoref*{fig:diagram-components} interact with each other. It shows the implementation of the \textbf{nonce2ecash} flow. Terminal, Wallet and Exchange are linked leveraging a nonce initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a public key. + +\subsection*{The three parts} + +The process requires three parties. The Terminal, the Wallet and the Exchange must therefore interact with each other. + +\subsubsection*{The Terminal} + +The Terminal initiates the withdrawal leveraging an application which works as follows: + +\begin{enumerate} + \item At startup of the application, the terminal loads the Exchange configuration + \item When a user wishes to do a withdrawal, the owner of the terminal opens the application and initiates a new withdrawal. + \begin{enumerate} + \item Application creates a nonce + \item The application starts long polling at the Exchange and awaits the establishment of the nonce (by the Exchange). + \item Nonce is packed into a QR code (with Exchange and amount) + \item QR code is displayed + \end{enumerate} + \item The user now scans the QR Code using his wallet. + \item The application receives the establishment notification of the Exchange. + \item The owner of the terminal enters the amount the user likes to withdraw. + \item Terminal calculates fees and shows summary and the Terms of Service (ToS) of Taler. + \item The user accepts the offer, agrees with the ToS and pays using his Credit Card. + \item The Terminal executes the payment and presents the result to the user. +\end{enumerate} + +\subsubsection*{The Exchange} + +The Exchange manages the withdrawal using a third party and seeks guarantees of the third party in order to provide a reserve containing Taler which can be withdrawn by the wallet. + +\begin{enumerate} + \item The Exchange retrieves a long polling request for a nonce (from the Terminal). + \item The Exchange creates a mapping entry with the nonce and an empty reserve public key field + \item The Exchange retrieves a request including a nonce and a reserve public key. + \item The Exchange validates the request and adds the key to the mapping. This establishes the nonce to reserve public key mapping. + \item The Exchange ends the long polling from the terminal (by sending back the reserve public key). + \item The Exchange receives payment notification of the terminal. + \item The Exchange verifies the notification by asking the terminal backend for confirmation. + \item The Exchange, upon successfully checking the notification, creates the reserve with the verified amount +\end{enumerate} + +\subsubsection*{The Wallet} + +The Wallet must attest its presence to the terminal by registering a nonce and belonging reserve public key which will hold the Taler that can eventually be withdrawn by the wallet. + +\begin{enumerate} + \item The Wallet scans the QR Code (nonce, Exchange information) on the Terminal + \item It creates a reserve key pair + \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*{Taler system} +\subsubsection*{Taler Wallet} +\subsubsection*{Taler Exchange} + +\subsection*{Terminal system} +\subsubsection*{Terminal} +\subsubsection*{Terminal Manufacturer Backend} +\subsubsection*{Terminal Fulfillment } +\ No newline at end of file diff --git a/docs/content/architecture/cashless2ecash.tex b/docs/content/architecture/cashless2ecash.tex @@ -0,0 +1,5 @@ +\section*{nonce2ecash} + +\subsection*{Model} + +\subsubsection*{Database} diff --git a/README b/docs/content/architecture/exchange.tex diff --git a/docs/content/architecture/terminal.tex b/docs/content/architecture/terminal.tex @@ -0,0 +1,8 @@ +\section*{Wallee Terminal Application} + +\subsection*{Wallee Transaction Process} +describe: https://app-wallee.com/de-de/doc/payment/transaction-process +document implications for cashless2ecash component (which states are reliable to cashout coins). + +https://app-wallee.com/de-de/doc/api/web-service#_transactionstate +https://app-wallee.com/de-de/doc/api/web-service#_transaction +\ No newline at end of file diff --git a/docs/content/architecture/testing.tex b/docs/content/architecture/testing.tex @@ -0,0 +1,13 @@ +\section*{Testing} + +Testing is a crucial part and makes sure, every component behaves as intended. To make sure implementations are tested, this section describes the testing concept taken in place in order to do so. Two scopes will be leveraged in testing. One is the unit testing scope which tests single functions for their well behaving. The integration testing scope will then test the integration of the distributed parts with one another. While the unit tests will be automated tests, integrationtests are thought to be manual tests which are described in the respective section further down. + +\subsection*{Testing in general} + +\subsection*{Unit Testing} + +\subsection*{Component Testing} + +\subsection*{Integration Testing} + +\subsubsection*{Test cases} diff --git a/docs/content/architecture/usecase.tex b/docs/content/architecture/usecase.tex @@ -0,0 +1 @@ +\section*{Use Case} +\ No newline at end of file diff --git a/docs/content/architecture/wallet.tex b/docs/content/architecture/wallet.tex @@ -0,0 +1 @@ +\section*{Wallet} +\ No newline at end of file diff --git a/docs/content/expl_fragments.tex b/docs/content/expl_fragments.tex @@ -0,0 +1,440 @@ +\section{Some \texorpdfstring{\LaTeX}{LaTeX}~Examples} + +\blindtext[1] + +\subsection{Tabular} + +\begin{tabular}[h]{l|l|l} + \centering + Measure & Data & Unit \\ \hline + 1 & 2 & 3 \\ + 4 & 5 & 6 +\end{tabular} + +% Example for a Table in BFH-Style with a simple Design +\begin{table}[ht] + \centering + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab1} +\end{table} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab2} +\end{table} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumRed!10} + \colorlet{BFH-tablehead}{BFH-MediumRed!50} + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab3} +\end{table} + + +\begin{description} +\item[More about Tables] Further information about tables : \url{https://www.latex-tutorial.com/tutorials/tables/} +\item[Long Tables] Further information about long tables : \url{https://www.overleaf.com/learn/latex/tables} +\end{description} + + +\begin{longtable}{|l|l|l|} +\caption{A sample long table} \label{tab:long} \\ + + +\hline \multicolumn{1}{|c|}{\textbf{First column}} & \multicolumn{1}{c|}{\textbf{Second column}} & \multicolumn{1}{c|}{\textbf{Third column}} \\ \hline +\endfirsthead + +\multicolumn{3}{c}% +{{\tablename\ \thetable{}: \hfill $...$~continued from previous page}} \\ +\hline \multicolumn{1}{|c|}{\textbf{First column}} & \multicolumn{1}{c|}{\textbf{Second column}} & \multicolumn{1}{c|}{\textbf{Third column}} \\ \hline +\endhead + +\hline \multicolumn{3}{|r|}{{Continued on next page$...$}} \\ \hline +\endfoot + +\hline \hline +\endlastfoot +\centering + +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +\end{longtable} + + +\subsection{Math} +%% Mathematical equations +\begin{align} +\left(\begin{array}{r} +\dot{x_{1}} \\ +\dot{x_{2}} \\ +\dot{x_{3}} \\ +\end{array}\right) = +\left[\begin{array}{rrr} +0 & 1 & 0 \\ +0 & -\frac{b_{f}}{J} & \frac{K_{m}}{J} \\ +0 & -\frac{K_{g}}{L} & \frac{R}{L} \\ +\end{array}\right] +\left(\begin{array}{r} +x_{1} \\ +x_{2} \\ +x_{3} \\ +\end{array}\right) + +\left[\begin{array}{rr} +0 & 0 \\ +-\frac{1}{J} & 0 \\ +0 & \frac{1}{L} \\ +\end{array}\right] +\left(\begin{array}{r} +t_{L} \\ +v_{a} \\ +\end{array}\right) +\end{align} + +\subsection{Include pictures} + +\begin{figure}[H] + \centering + \includegraphics[width=.8\textwidth]{placeholder} + \caption{Some meaningful caption} + \label{fig:placeholder:1} +\end{figure} + + +\begin{figure}[h!] + \centering + \begin{minipage}{.4\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{PLACEHOLDER} + \label{fig:placeholder:2} + \end{minipage} + \hspace{1em} + \begin{minipage}{.4\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{PLACEHOLDER} + \label{fig:placeholder:3} + \end{minipage}% +\end{figure} + + +%% Source code is stored in the listings folder and will be included from there using its relative path. +\subsection{Code Example} + +{ + \thicklines +% \thinlines +\lstinputlisting[style=bfh-c,language=C,caption={My very first C program.},label={lst:hello}]{listings/expl_hello.c} +} +I developed this very nice application writing "Hello World" to my terminal. +The implementation is shown in listing~\ref{lst:hello}. + + +%% Examples holding dummy content +\subsection{Draw boxes} +\begin{bfhBox}[BFH-DarkPurple]{Purple} + Note\\ +\end{bfhBox} + +\blindtext[1] + +\begin{bfhBox}[BFH-MediumBlue]{Blue} + Note\\ +\end{bfhBox} + +\blindtext[1] + +\begin{bfhBox}[BFH-DarkRed]{Red} + Note\\ +\end{bfhBox} + +\blindtext[2] + +\begin{bfhAlertBox} + An alert box. +\end{bfhAlertBox} + +\begin{bfhWarnBox} + A warning box. +\end{bfhWarnBox} + +\begin{bfhNoteBox} + A note box. +\end{bfhNoteBox} + +\begin{bfhRecycleBox} + A recycle box. +\end{bfhRecycleBox} + + +\begin{bfhBox}{No color set} + Some BFH box without color option set. Using default.\\ +\end{bfhBox} + + +\blindtext[3] + + +\subsection{Some Item-list} +Sometimes you explain this and that using a bullet points. +This can be done in \LaTeX\ using an item list in a item environment. + +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} + +It is also possible to nest such environment and/or enumerate. +\begin{itemize} +\item My first item +\begin{enumerate} +\item My first enumerated item +\item The second +\item $\cdots$ +\end{enumerate} +\item The second +\begin{enumerate} +\item An other enumerated item +\item $\cdots$ +\item $\cdots$ +\end{enumerate} +\end{itemize} + + +\subsection{Multi column environment} +Split a part of a document in multiple columns is not so easy with WYSIWYG tools. +Whit multicols \LaTeX\ package$\cdots$ well you may know. + +\begin{multicols}{3} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\end{multicols} + + +\blindtext[1] + +\begin{multicols}{2} + \blindtext[1] +\end{multicols} + +\begin{multicols}{3} + \blindtext[1] +\end{multicols} + +\begin{multicols}{2} + \blindtext[1] +\end{multicols} + + +\begin{multicols}{3} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\blindtext[1] +\columnbreak +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\end{multicols} + +%% forced page break +\newpage + +\subsection{Use Figures} + +\begin{figure}[h!] + \centering + \includegraphics[width=.8\textwidth]{bg-masthead} + \caption{An example of including a PDF figure.} + \label{fig:expl_master} +\end{figure} + +\begin{figure}[h!] + \centering + \includegraphics[width=.8\textwidth]{expl_bode} + \caption{An example of including a PDF figure.} + \label{fig:expl_bode} +\end{figure} +\clearpage + +\subsubsection{Use Subfigures} +These subfigures requires the package \texttt{subcaption}. + +\begin{figure}[h!] + \centering + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=x$} + \label{fig:y equals x} + \end{subfigure} + \hfill + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=3sinx$} + \label{fig:three sin x} + \end{subfigure} + \hfill + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=5/x$} + \label{fig:five over x} + \end{subfigure} + \caption{Three simple graphs} + \label{fig:three graphs} +\end{figure} + + +\section{Example Text With Indices} +In this example, several keywords\index{keywords} will be used +which are important and deserve to appear in the Index\index{Index}. + +Terms like generate\index{generate} and some\index{others} will +also show up. + +\section{Example Text With Glossary} +This \Gls{zynq} introduction summary has been written for bachelor students due to the introduction workshop in the ``Embedded Systems'' course at Bern University of Applied Sciences. The topic \Gls{soc} is introduced by using Xilinx' \Gls{apsoc} platform \Gls{zynq}. The subsequent summery is a brief introduction only. It is based on several tutorials in the field of \Gls{soc} such as the \Gls{zbook} or Xilinx' \Gls{apsoc} manual. We think the script provides a good introduction and helps getting the overall picture of the \Gls{soc} basics. In addition we reference to our wiki tutorials that provide lots of information on how to get started with the \Gls{zboard}.\\ + +Hey folks let's do an \Gls{asic} design and develop some awesome \Gls{rtos}! Yea \Gls{arm} is nice but we can do better, can we? + +\section{Example Text With Citations} +%% Text with citations + +This document is an example of \Gls{BibTeX} using in bibliography management. Three items +are cited: The \LaTeX\ Companion book \cite{latexcompanion}, the Einstein +journal paper \cite{einstein}, and the Donald Knuth's website \cite{knuthwebsite}. +The \LaTeX\ related items are \cite{latexcompanion,knuthwebsite}. + diff --git a/docs/content/glossary.tex b/docs/content/glossary.tex @@ -0,0 +1,54 @@ +\newglossaryentry{BibTeX}{ + name={BibTeX}, + description={Program for the creation of bibliographical references and directories in \TeX or \LaTeX\, documents}, + plural=BibTeXs +} + +\newglossaryentry{zynq}{ + name=Zynq, + description={\textbf{Zynq} Xilinx' AP SoC. The characteristic feature of Zynq is that it combines a dual-core ARM Cortex-A9 processor with traditional Series-7 FPGA logic fabric}, + plural=Zynqs +} + + +\newglossaryentry{soc}{ + name=SoC, + description={\textbf{System-on-Chip (SoC)} A single chip that holds all of the necessary hardware and electronic circuitry for a complete system. SoC includes on-chip memory (RAM and ROM), the microprocessor, peripheral interfaces, I/O logic control, data converters, and other components that comprise a complete computer system}, + plural=SoCs +} + +\newglossaryentry{apsoc}{ + name=AP SoC, + description={\textbf{All Programmable System-on-Chip (AP SoC)} was introduced by Xilinx. It represents a IC which comprise a hard-core processor core surrounded by an FPGA fabric. This type of ICs are highly configurable and provide algorithm partitioning capabilities. This provides high benefit for highly scale-able applications as well as fast time-to-market}, + plural=AP SoCs +} + +\newglossaryentry{zbook}{ + name=Zynq Book, + description={\textbf{Zynq Book} A book that summarizes all the important aspects when working with Zynq and provides a strong and easy understandable introduction to the topic. The book has been written by a team of University of Strathclyde Glasgow in cooperation with Xilinx}, + plural=Zynq Books +} + +\newglossaryentry{zboard}{ + name=ZedBoard, + description={\textbf{ZedBoard} A low cost development board featuring a Zynq-700 0 SoC, and a number of peripherals}, + plural=ZedBoards +} + + +\newglossaryentry{asic}{ + name=ASIC, + description={\textbf{Application-Specific Integrated Circuit (ASIC)} An integrated circuit which is designed for a specific use, rather than general-purpose use}, + plural=ASICs +} + +\newglossaryentry{rtos}{ + name=RTOS, + description={\textbf{Real-Time Operating System (RTOS)} A category of operating systems defined by their ability to respond quickly and predictably for a given task}, + plural=RTOSs +} + +\newglossaryentry{arm}{ + name=ARM, + description={\textbf{ARM} A family of processor architectures. The hard processor type which forms the basis of the Zynq processing system is an ARM Cortex-A9 version. The term ‘ARM’ may also be used to refer to the developer of the processor, i.e. a company of the same name} +} diff --git a/docs/content/implementation/exchange.tex b/docs/content/implementation/exchange.tex @@ -0,0 +1 @@ +\section*{implementing cashless2ecash docs} +\ No newline at end of file diff --git a/docs/content/implementation/wallee.tex b/docs/content/implementation/wallee.tex @@ -0,0 +1 @@ +\section*{implementing wallee docs} +\ No newline at end of file diff --git a/docs/content/introduction/goal.tex b/docs/content/introduction/goal.tex @@ -0,0 +1,10 @@ +\section*{Goal} + +The goal of this thesis is to implement a process which allows withdrawing Taler using a credit card at a terminal. + +\subsection*{cashless2ecash} + +Therefore a new component, named \textbf{cashless2ecash (or maybe nonce2ecash??)}, will be implemented as part of the Taler Exchange. Cashless2ecash allows to check that the payment was accepted by the provider and therefore can guarantee, that the money of the withdrawing user will reach the bank account owned by the Taler Exchange. + +\subsection*{Wallee} +A new app for the payment terminal provider \textbf{Wallee} must be implemented which allows to start the withdrawal using providers facilities. The provider will guarantee through its backend, that the payment was successful. This puts the liability of the payment on the provider of the terminal. diff --git a/docs/content/introduction/introduction.tex b/docs/content/introduction/introduction.tex @@ -0,0 +1,68 @@ +\section*{Motivation} + +Ever tried withdrawing Taler? It is quite hard if your bank does not implement and run the facilities supplied by Taler ecosystem or you are not able to find people controlling the respective Exchange. The second approach is somewhat prone to human errors, but it works. + +So the problem currently is that it is not possible for users to get Taler if the above options are not feasible for them. This thesis proposes a way allowing users who own a credit card and a Taler Wallet, to buy Taler at a terminal supporting the withdrawal of Taler. + +To make the withdrawal possible, various loose ends must be put together within the Taler ecosystem and the terminal provider. Also a new component called \textit{cashless2ecash} is implemented. The thesis focuses on the terminal provider called \textit{Wallee}. Therefore an application for the Wallee Terminal (PAX A50) for withdrawing Taler is implemented. + +With these components, a trustworthy relationship can be created, which makes it possible for the Exchange to issue coins to a user. Therefore the Exchange is not putting his trust on the money received but rather on the promise of a trusted third party (the terminal provider) to put the received money in a location, controlled by the Exchange eventually (e.g. a bank account owned by the Exchange). + +This enables a broader group of people to leverage Taler for their payments. Which eventually leads to wider adoption of the payment system Taler. + +\section*{Trust Relations} +Withdrawing Taler coins establishes the need for a new trust model. In order to gather a deeper understanding of the difference between the current trust model and the new model they are described here. + +\subsection*{Direct Trust - Direct-Payment-Withdrawal} +The \textit{direct trust} model is the model existing at the time. It allows the withdrawal of Taler using direct interaction between the deptor (withdrawing party) and the Taler Exchange. It allows the deptor to present credentials and values to the Exchange which it can claim and return the equivalent in coins. In case a deptor is unable to pay the amount he wants to buy coins from the Exchange, the Exchange will simply reject the request and tell the deptor that his balance is too low or the values are not legit. This is possible because he deptor gives the money directly to the Exchange. This means that the equivalent value of the withdrawn coins are immediately transferred to the Exchange and with it the trust anchor that the deptor has the money. + +The \textit{transaction} itself is the trust anchor. No trusted third party is needed. + +\subsection*{Indirect Trust - Eventual-Payment-Withdrawal} +In the \textit{indirect trust} model is the model we must facilitate to be able to withdraw coins using a credit card. This comes from how payment systems are implemented and that transactions are not immediate but rather eventually executed. This means that if a payment is made using a credit card, the amount is not immediately transferred from the deptor to the seller. Instead the credit card provider (e.g. Mastercard or Visa) guarantees the fulfillment to the seller, by lending money (giving a credit) to the deptor. The credit card provider takes the risk to not be payed by the deptor and all its consequences (reminding the deptor to pay or going to court and filing a case against the deptor if he does not pay). The system therefore relies on \textit{trusting the credit card provider} guaranteeing the payment of the seller and doing the "dirty work" if a deptor won't pay. The Exchange shall therefore trust the credit card provider and its guarantees. + +The \textit{guarantee for the transaction} of the credit card provider is the trust anchor. The provider steps in as trusted third party. + +\subsection*{Why Wallee?} +Wallee is not a credit card provider, but a payment system provider. So why should the Taler Exchange trust Wallee? +% TODO: Why can we trust the terminals of Wallee? + +\subsection*{Chain of Trust} +The above leads to a chain of trust that must be maintained in order for the system to be accountable and trustworthy. If one single link in the chain breaks our trust assumption, the chain of trust is broken and the system becomes untrustworthy and therefore not usable. + +\section*{GNU Taler} +% TODO +General introduction to GNU Taler + +\section*{Wallee} +% TODO +General introduction to Wallee + +\section*{Perspectives} +During the initial analysis of the task, two main areas of work were discovered. One is the Taler Exchange and the other is the Application for the terminal. This led to different views on the system by two different players within it. To allow a more concise view on the system and to support the readers and implementer, two perspectives shall be kept in mind. They have different views on the process but need to interact with each other seamlessly. + +\subsection*{Terminal Application} +The perspective of the terminal application includes all processes within the application which interacts with the user and its credit card allowing the withdrawal of coins. The terminal application wants to conviently allow the withdrawal of coins and charge fees to cover costs and risks. + +\subsection*{Taler Exchange (cashless2ecash)} +The perspective of the Taler Exchange includes all processes within cashless2ecash component and the interaction with the terminal application, terminal backend and the wallet of the user. The Taler Exchange wants to allow withdrawal of coins only to users who pay the equivalent value to the Exchange and stay out of legal implications. + +\section*{Fees} +Since buying Taler using a credit card leverages a third party payment system, new \textbf{fees} are introduced and must be taken care of. The fees to buy Taler are defined by the third party payment system and therefore do not lie in the control of the Taler system. The fees are retrieved by the terminal and added to the amount of money which is to be withdrawn by the user. Only after giving the confirmation to buy the specified amount of Taler with the specified amount of fees, the payment shall be processed. + +\section*{nonce2ecash} +Very simplified, the process of a withdrawal currently looks as follows: + +\begin{enumerate} + \item User pays Exchange + \item Exchange validates payment and iff successful, creates reserve + \item User can access reserve and withdraw money using his wallet +\end{enumerate} + +As long as the interaction of withdrawal is manual and the identification and verification of the payment is a human interaction, this process is ok because this makes stealing Taler as hard as manipulating the Taler Exchange (which would mean a complete compromisation of the system). + +But now we have the problem that the Exchange is not able to proof that the money was sent to the wallet it was intended for. This leaves the Exchange with liability weaknesses and makes it unattractive to operate the cashless2ecash feature for Exchange operators and therefore introduces a weakness. + +Imagine the following situation: A user gets kidnapped and is forced to buy a certain amount of Taler. But now instead of using the wallet of the kidnapped user, the kidnapper accesses Exchange with his own wallet and steals the money. This makes stealing money from someone as hard as making them pay using their credit card or reveal the credentials to do so (which is totally possible \autoref*{cc-fraud-types}). Also plain digital attacks are possible (and probably more likely) where the attacker is able to claim the reserves for himself before the user gets his hands on the money. + +This situation can be prevented by leveraging the \textbf{nonce2ecash} approach proposed by Florian Jung. This approach forces the withdrawing party to lock their withdrawal to a specific user (public key) before the actual withdrawal. This approach makes stealing money as hard as gaining control over the wallet (which is the equivalent to stealing the wallet). diff --git a/docs/content/methods.tex b/docs/content/methods.tex @@ -0,0 +1,2 @@ +\section{Methods} +What did you do? – a section which details how the research was performed. It typically features a description of the participants/subjects that were involved, the study design, the materials that were used, and the study procedure. If there were multiple experiments, then each experiment may require a separate Methods section. A rule of thumb is that the Methods section should be sufficiently detailed for another researcher to duplicate your research. diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex @@ -0,0 +1,2 @@ +\section{Discussion} +What is the significance of your results? – the final major section of text in the paper. The Discussion commonly features a summary of the results that were obtained in the study, describes how those results address the topic under investigation and/or the issues that the research was designed to address, and may expand upon the implications of those findings. Limitations and directions for future research are also commonly addressed. diff --git a/docs/content/results/results.tex b/docs/content/results/results.tex @@ -0,0 +1,2 @@ +\section{Results} +What did you find? – a section which describes the data that was collected and the results of any statistical tests that were performed. It may also be prefaced by a description of the analysis procedure that was used. If there were multiple experiments, then each experiment may require a separate Results section. diff --git a/README b/docs/figures/.gitkeep diff --git a/docs/figures/expl_bode.pdf b/docs/figures/expl_bode.pdf Binary files differ. diff --git a/README b/docs/listings/.gitkeep diff --git a/docs/listings/expl_hello.c b/docs/listings/expl_hello.c @@ -0,0 +1,8 @@ +#include <stdio.h> +#include <stdlib.h> + +int main( /* int argc, char **argv */ ) +{ + printf("Hello World!\n"); + return EXIT_SUCCESS; +} diff --git a/README b/docs/pictures/.gitkeep diff --git a/docs/pictures/bg-masthead.jpg b/docs/pictures/bg-masthead.jpg Binary files differ. diff --git a/docs/pictures/diagrams/component.png b/docs/pictures/diagrams/component.png Binary files differ. diff --git a/docs/pictures/diagrams/db_cashless2ecash_erd.png b/docs/pictures/diagrams/db_cashless2ecash_erd.png Binary files differ. diff --git a/docs/pictures/diagrams/nonce2ecash.png b/docs/pictures/diagrams/nonce2ecash.png Binary files differ. diff --git a/docs/pictures/diagrams/nonce2ecash_class_diagram.png b/docs/pictures/diagrams/nonce2ecash_class_diagram.png Binary files differ. diff --git a/docs/pictures/diagrams/provider_registration_sequence.png b/docs/pictures/diagrams/provider_registration_sequence.png Binary files differ. diff --git a/docs/pictures/diagrams/wallee_app_class_diagram.png b/docs/pictures/diagrams/wallee_app_class_diagram.png Binary files differ. diff --git a/docs/pictures/diagrams/wallee_app_sequence.png b/docs/pictures/diagrams/wallee_app_sequence.png Binary files differ. diff --git a/docs/pictures/placeholder.jpg b/docs/pictures/placeholder.jpg Binary files differ. diff --git a/docs/pictures/sig_example.png b/docs/pictures/sig_example.png Binary files differ. diff --git a/docs/pictures/sig_muster.png b/docs/pictures/sig_muster.png Binary files differ. diff --git a/docs/pictures/somePicture.jpg b/docs/pictures/somePicture.jpg Binary files differ. diff --git a/docs/project.bib b/docs/project.bib @@ -0,0 +1,23 @@ +@misc{taler-user-guide, + author = {GNU Taler}, + title = {GNU Taler User Guide}, + url = {https://docs.taler.net/taler-user-guide.html}, + howpublished = {\url{https://docs.taler.net/taler-user-guide.html}} +} + +@misc{srf-espresso-cc-fraud, + author = {Peter Fritsche}, + year = {2022}, + month = {April}, + title = {Keine Rückerstattung bei «verifizierten» Geldbezügen}, + url = {https://www.srf.ch/news/panorama/kreditkarten-betrug-keine-rueckerstattung-bei-verifizierten-geldbezuegen}, + howpublished = {\url{https://www.srf.ch/news/panorama/kreditkarten-betrug-keine-rueckerstattung-bei-verifizierten-geldbezuegen}} +} + +@misc{cc-fraud-types, + author = {Stadtpolizei Zürich, Kommissariat Prävention}, + title = {Betrugsarten}, + url = {https://www.card-security.ch/betrugsarten/}, + howpublished = {\url{https://www.card-security.ch/betrugsarten/}} + +} +\ No newline at end of file diff --git a/docs/thesis.pdf b/docs/thesis.pdf Binary files differ. diff --git a/docs/thesis.tex b/docs/thesis.tex @@ -0,0 +1,207 @@ +%============================ MAIN DOCUMENT ================================ +% define document class +\PassOptionsToPackage{table}{xcolor} +\documentclass[ + a4paper, + BCOR=15mm, % Binding correction + twoside, +% openright, +% headings=openright, + bibliography=totoc, % If enabled add bibliography to TOC + listof=totoc, % If enabled add lists to TOC + monolingual, +% bilingual, + invert-title, +]{bfhthesis} + +\LoadBFHModule{listings,terminal,boxes} +%--------------------------------------------------------------------------- +% Documents paths +%--------------------------------------------------------------------------- +\makeatletter +\def\input@path{{content/}} +%or: \def\input@path{{/path/to/folder/}{/path/to/other/folder/}} +\makeatother +%----------------- Base packages -------------------------------------- +% Include Packages +\usepackage[french,ngerman,main=english]{babel} % https://www.namsu.de/Extra/pakete/Babel.html + +\usepackage{amsmath} % various features to facilitate writing math formulas +\usepackage{amsthm} % enhanced version of latex's newtheorem +\usepackage{amsfonts} % set of miscellaneous TeX fonts that augment the standard CM +\usepackage{amssymb} % mathematical special characters + +\usepackage{siunitx} + +\usepackage{graphicx} % integration of images +\usepackage{float} % floating objects + +\usepackage{caption} % for captions of figures and tables +\usepackage{subcaption} % for subcaptions in subfigures +\usepackage{cite} % use bibtex +\usepackage{wrapfig} + +\usepackage{exscale} % mathematical size corresponds to textsize +\usepackage{multirow} % multirow emables combining rows in tables +\usepackage{multicol} + +\usepackage{longtable} + +\usepackage{parskip} + +%--------------------------------------------------------------------------- +% Graphics paths +%--------------------------------------------------------------------------- +\graphicspath{{pictures/}{figures/}} +%--------------------------------------------------------------------------- +% Blind text -> for dummy text +%--------------------------------------------------------------------------- +\usepackage{blindtext} +\usepackage{letltxmacro} +\LetLtxMacro{\blindtextblindtext}{\blindtext} + +\RenewDocumentCommand{\blindtext}{O{\value{blindtext}}}{ + \begingroup\color{BFH-Gray}\blindtextblindtext[#1]\endgroup +} +%--------------------------------------------------------------------------- +% Glossary Package +%--------------------------------------------------------------------------- +% the glossaries package uses makeindex +% if you use TeXnicCenter do the following steps: +% - Goto "Ausgabeprofile definieren" (ctrl + F7) +% - Select the profile "LaTeX => PDF" +% - Add in register "Nachbearbeitung" a new "Postprozessoren" point named Glossar +% - Select makeindex.exe in the field "Anwendung" ( ..\MiKTeX x.x\miktex\bin\makeindex.exe ) +% - Add this [ -s "%tm.ist" -t "%tmx.glg" -o "%tm.gls" "%tm.glo" ] in the field "Argumente" +% +% for futher informations go to http://ewus.de/tipp-1029.html +%--------------------------------------------------------------------------- +\usepackage[nonumberlist]{glossaries-extra} +\makeglossaries +\input{content/glossary} +%--------------------------------------------------------------------------- +% Makeindex Package +%--------------------------------------------------------------------------- +\usepackage{makeidx} +\makeindex +%\usepackage{imakeidx} % To produce index +%\makeindex[columns=2,intoc] % Index-Initialisation +%\makeindex[columns=3,columnseprule,columnsep,intoc] +%--------------------------------------------------------------------------- +% Hyperref Package (Create links in a pdf) +%--------------------------------------------------------------------------- +\usepackage[ + ,bookmarks + ,plainpages=false + ,pdfpagelabels + ,pdfusetitle + ,backref = {false} % No index backreference + ,colorlinks = {true} % Color links in a PDF + ,hypertexnames = {true} % no failures "same page(i)" + ,bookmarksopen = {true} % opens the bar on the left side + ,bookmarksopenlevel = {0} % depth of opened bookmarks + ,linkcolor=. + ,filecolor=. + ,urlcolor=. + ,citecolor=. +]{hyperref} +%--------------------------------------------------------------------------- + +%% %% Customize Footer and Headers in Document +%% \KOMAoptions{headsepline,plainheadsepline,footsepline,plainfootsepline}% +%% \setkomafont{headsepline}{\color{BFH-DarkBlue}}% BFH-DarkBlue required bfhcolors +%% \setkomafont{footsepline}{\color{BFH-DarkBlue}}% +%% \lehead*{lehead} % the * character does replace the header on the first chapter page as well +%% \cehead*{cehead} +%% \rehead*{rehead} +%% \lohead*{lohead} +%% \cohead*{cohead} +%% \rohead*{rohead} + +%% \lefoot*{lefoot} +%% \cefoot*{cefoot} +%% \refoot*{refoot} +%% \lofoot*{lofoot} +%% \cofoot*{cofoot} +%% \rofoot*{rofoot} +%--------------------------------------------------------------------------- +\begin{document} + +%------------ START FRONT PART ------------ +\frontmatter + +\title{Cashless to E-Cash} +\subtitle{Bachelor's Thesis} +\author{Joel Roman Häberli} +\institution{Bern University of Applied Sciences} +\department{Technic and Computer Science} +\institute{Institute for Cybersecurity and Engineering ICE} +\version{1.0} +\titlegraphic*{\includegraphics{somePicture}} +\advisor{Prof. Dr. Benjamin Fehrensen} +\coadvisor{Prof. Dr. Christian Grothoff} +\projectpartner{} +\expert{Dr. Alain Hiltgen, UBS} +\degreeprogram{Bachelor of Science in Computer Science} +\setupSignature{ + J. Häberli={\includegraphics[width=.5\linewidth]{sig_muster}}, +} + +%---------------- BFH tile page ----------------------------------------- +\maketitle +%------------ ABSTRACT ---------------- +\addchap{Abstract} +\input{content/abstract} + +%------------ TABLEOFCONTENTS ---------------- +\tableofcontents + +%------------ START MAIN PART ------------ +\mainmatter + +\chapter{Introduction} +\input{content/introduction/introduction} +\input{content/introduction/goal} + +\chapter{Architecture} +\input{content/architecture/bigpicture} + +\chapter{Implementation} +\input{content/implementation/exchange} +\input{content/implementation/wallee} + +\chapter{Results} +\input{content/results/discussion} +\input{content/results/results} + +%------------ Authorship declaration translated to main language ------------ +\declarationOfAuthorship + +%----------- Bibliography ---------------- +\clearpage +\bibliographystyle{unsrt} +\bibliography{project} % the project.bib file gets loaded + +%------------ List of Figures ------------ +\listoffigures + +%------------ List of Tables ------------- +\listoftables + +%------------ List of Listings ----------- +\lstlistoflistings + +%------------ Glossary ------------------- +\printglossary + +%------------ Index ---------------------- +\clearpage +\printindex +%------------ Appendix ---------------- +\appendix +\chapter{Appendix A} +\chapter{Appendix B} +\section{Meeting notes} +\input{content/appendix/meeting_notes} + +\end{document} diff --git a/specs/component.plantuml b/specs/component.plantuml @@ -0,0 +1,28 @@ +top to bottom direction +skinparam packageStyle rect + +@startuml +package "Taler" { + [Taler Wallet] as Wallet + [Exchange] as Exchange +} + +package "Terminal System" { + [Terminal] as Terminal + [Terminal Operator Backend] as Backend +} + +[Credit Card] as CC + +Wallet -> Terminal: (1) Scan QR Code (Nonce) +Wallet -> Exchange: (2) Nonce to Wallet Public Key Hash +Terminal <- Exchange: (3) Ready + +CC -> Terminal: (4) Present CreditCard +Terminal -> Backend: (5) Payment +Backend -> Terminal: (6) Response +Exchange -> Backend: (7) Verify Transaction + +Wallet -> Exchange: (8) Withdraw + +@enduml diff --git a/specs/db_cashless2ecash_erd.plantuml b/specs/db_cashless2ecash_erd.plantuml @@ -0,0 +1,34 @@ +@startuml +enum n2c_status { + n2c_ESTABLISHED + n2c_ESTABLISHMENT_FAILED + n2c_PAYED + n2c_RESERVE_CREATED + n2c_PAYMENT_FAILED +} + +entity n2c_nonce_reservepubkey { + + provider_name: string + + nonce: number + + nonce_provider_sig: blob + + reserve_pubkey: number + + state: n2cStatus + + registration_ts: timestamp +} + +enum n2c_provider_attestation_type { + NONE + WALLEE +} + +entity n2c_provider { + + name: string + + publicKey: blob + + publicKeySignature: blob + + attestationType: ProviderAttestationType +} + +n2c_provider --* n2c_provider_attestation_type +n2c_nonce_reservepubkey --* n2c_status +n2c_nonce_reservepubkey "m" --> "1" n2c_provider +@enduml diff --git a/specs/nonce2ecash.plantuml b/specs/nonce2ecash.plantuml @@ -0,0 +1,133 @@ +Flow: +1. Terminal asks to choose Exchange + +I think this might be part of the terminal *settings*, or maybe optional (to change default). +But forcing this every time seems bad UX. + -> agree, assuming exchange will seldomly be changed and be kind of static. + +2. Terminal asks to choose Denomination + +Definitively not. Each exchange defines the currency and denominations, nothing needed here. +What we do probably need is to get the fee structure here (/config, /keys) and confirm that +the exchange is currently running. + -> ok i did get that wrong about how the exchange works. I assumed an exchange is able to cashout various denominations but only allows one to be payed with. + +3. Terminal generates a Nonce +4. Terminal starts long polling activity at Exchange including the generated Nonce + +For now, this is OK. But when implementing, we probably want to distinguish the +(legacy) exchange "core" logic, and the cashless2ecash-specific extensions of the +exchange. So this part of the architecture will need a more precise look *later*. + -> sorry, I don't understand this comment + +5. Terminal creates QR code including Nonce and Exchange +6. Wallet scans QR code + +Unless user already did so, this might be the place to show the exchange Terms of Service +and have the user accept them! + -> Can we tell the user, that by scanning the QR code, the user accepts the Terms of Service (sure a link or similar is presented to the user) + or does the user actively needs to press an ok button or set a cross? + +7. Wallet creates a Reserve Key-Pair +8. Wallet sends Nonce and ReservePublicKey to specified Exchange +9. The Wallet starts long polling at Exchange to learn when payment was processed +10. Exchange creates a mapping from the Nonce to the ReservePublicKey +11. Exchange ends long polling from step 4 by sending N2C_ESTABLISHED +12. Terminal lets User enter amount to withdraw + +Why this late? I think the user has to do too much here. It would be better if +the *staff* (optionally) selected the exchange and entered the amount at the +start. Then the user _only_ has to scan the QR code and swipe the card. That's +a common process at stores (cashier provides amount, you scan/swipe). Plus QR +scan and card swipe are steps the user is familiar with. Having the user actually +do data entry seems like a usability problem and security risk. And we also don't +want the devices to be passed too much back and forth (and possibly not even have +a user-accessible keyboard). So scan + swipe should be all, and exchange-selection +and amount should be with the staff earlier. + -> ok get that, makes sense to me. User will only scan QR code and present the card. TerminalOwner will enter amount. + +13. Terminal shows summary with calculated Fees +14. User approves and presents card +15. Terminal executes Payment using the TerminalBackend +16. TerminalBackend responds if payment was successful. +16.1 If payment was successful Terminal does: +16.1.1 Send OK to Exchange (including nonce) + +Probably should send more than the OK+nonce, like the full 'proof' of payment, +so that ideally exchange doesn't even have to talk to TerminalBackend anymore. + -> so we dont double check with the TerminalBackend that the payment went through if the terminal is able to respond? Isn't this the idea of the TerminalBackend involvment, that we only trust the TerminalBackend to present payment guarantees to the exchange? + -> so this would lead to two alternative flows, depending on if the terminal provider responds to the exchange or not. + -> sub-flow one: Terminal responds inside defined timeout. we trust the response of the terminal. + -> sub-flow two: Terminal fails to respond inside defined timeout. exchange asks terminal TerminalBackend for payment information. + +16.1.2 Exchange changes Mapping table state to N2C_PAYED +16.1.3 Exchange checks TerminalBackend and asserts that the payment went through (Also setting the amount of money in the mapping table assuring the Wallet cannot trick the Exchange. Beware of the fees!!). + +We should do this automatically (independent of the 16.1.1 message that might be lost); +at least do a job in the background to check periodically in case 16.1.1 and 16.2.2 +do not happen in a timely fashion. + -> ok makes sense long polling or time based after some timeout (at the terminal backend)? + +16.1.4 Exchange ends long polling from step 9 by sending N2C_PAYED and the Nonce to the wallet +16.1.5 Wallet executes a AcceptManualWitdrawalOp (which eventually leads to Exchange signed coins in the wallet of the user) + +Eh, what do you mean by "manual" here? Wallet should probably simply "Execute withdrawal operation". + -> AcceptManualWithdrawalOp is a type in the Wallet Core implementation. I was looking up what operation could be used and this operation seemed the right op to me. + +16.2 If payment was not successful Terminal does: +16.2.1 Send NOK to Exchange (including nonce) +16.2.2 Exchange changes Mapping table state to N2C_PAYMENT_FAILED + +Is there a reason to keep the mapping table state? Why not just delete the row? + -> i was thinking about regulatory/liability reasons (that the exchange can proof payment did not went through). But if that's not needed, we can delete the entry here. + +16.2.3 Exchange ends long polling from step 9 by sending N2C_PAYMENT_FAILED and the Nonce to the wallet + +I see no need to send the nonce back to the wallet here. + -> get it -> it's a long polling. so the process on the wallet knows which nonce it is dealing with. + +16.2.4 The Wallet removes nonce and public key from internal mapping table. + +@startuml + +actor User as "User (with Credit Card)" +participant Wallet +participant Exchange +participant TerminalBackend as "Terminal Backend" +participant Terminal +actor TerminalOwner as "Terminal Owner" + +Terminal -> Terminal: configures Exchange (configured, overwritable) +User -> TerminalOwner: "Hi, I want to withdraw 20 coins with my Credit Card" +TerminalOwner -> Terminal: start Taler Withdrawal Application and enters amount +Terminal -> Terminal: Generate Nonce +Terminal -> Exchange: Start long polling (Nonce) +activate Exchange +Terminal -> Terminal: Create QR code (Nonce, Exchange, Amount) +Terminal -> Wallet: Scan QR code +activate Wallet +Wallet -> Wallet: If ToS for Exchange not yet accepted, do here. +Wallet -> Wallet: Create Reserve Key-Pair +Wallet -> Exchange: Send Nonce, ReservePublicKey +Wallet -> Exchange: Start long polling +Exchange -> Exchange: Create mapping (Nonce, ReservePublicKey, Amount) +Exchange --> Terminal: End long polling (N2C_ESTABLISHED) +deactivate Exchange +Terminal -> Terminal: Show summary with Fees +User -> Terminal: Approve and present card +Terminal -> TerminalBackend: Execute Payment +TerminalBackend --> Terminal: Payment response (success/failure) +alt Payment successful + Terminal -> Exchange: Send PaymentNotification (SUCCESS) + Exchange -> Exchange: Change Mapping state to N2C_PAYED + Exchange -> TerminalBackend: Verify payment\nSet payed amount in mapping table of Exchange + Exchange -> Exchange: Create Reserve with amount and reserve public key. + Exchange --> Wallet: End long polling (N2C_RESERVE_CREATED, Nonce) + Wallet -> Exchange: Execute Withdrawal (AcceptManualWithdrawalOp) +else Payment not successful + Terminal -> Exchange: Send PaymentNotification (UNSUCESSFUL) + Exchange -> Exchange: Remove entry in N2C mapping table. + Exchange --> Wallet: End long polling (N2C_PAYMENT_FAILED, Nonce) + Wallet -> Wallet: Remove Nonce and Public Key +end +@enduml diff --git a/specs/nonce2ecash_api_spec.yml b/specs/nonce2ecash_api_spec.yml @@ -0,0 +1,116 @@ +openapi: 3.0.3 +info: + title: nonce2ecash API + description: API managing a mapping table which links a nonce to a public key. This allows withdrawing from the exchange by the nonce. Additionally it provides facilities allowing for the Exchange operators to register new providers or delete obsolete ones. + version: 0.0.1 +paths: + /n2c/nonces/withdrawal-registration: + post: + summary: Register Nonce to Reserve Public Key + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/N2CWithdrawalRequest' + responses: + '200': + description: Message received successfully + tags: + - nonces + /n2c/nonces/withdrawal-processing: + post: + summary: Provider notifies the exchange about the payment (if it was successful or not) + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/N2CPaymentNotification' + responses: + '200': + description: Message received successfully + tags: + - nonces + /n2c/nonces/withdrawal-status: + get: + summary: Check Status + parameters: + - name: nonce + in: query + description: The nonce for which to check the status + required: true + schema: + type: string + - name: listenForStatus + in: query + description: The status to listen for the given nonce + required: true + schema: + $ref: '#/components/schemas/N2CStatus' + responses: + '200': + description: Status retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/N2CMapping' + tags: + - nonces +tags: + - name: nonces + description: managing and retrieving information about the mapping table for the nonce to reserve public key mapping. +components: + schemas: + N2CWithdrawalRequest: + description: Maps a nonce generated by the provider to a reserve public key generated by the wallet. + type: object + properties: + nonce: + type: string + reservePubKey: + type: string + format: byte + amount: + type: string + providerType: + $ref: '#/components/schemas/N2CProviderType' + N2CPaymentNotification: + description: Notifies the exchange about an executed payment. This will trigger a provider specific attestation of the payment according to the ProviderPaymentAttestationType. + type: object + properties: + nonce: + type: string + providerTransactionId: + type: string + success: + type: boolean + amount: + type: number + fees: + type: number + N2CStatus: + description: Describes the states a nonce to reserve public key mapping can be in. + type: string + enum: + - ESTABLISHED + - ESTABLISHMENT_FAILED + - PAYED + - RESERVE_CREATED + - PAYMENT_FAILED + N2CMapping: + description: Maps a nonce generated by the provider to a reserve public key generated by the wallet. + type: object + properties: + nonce: + type: string + reservePubKey: + type: string + format: byte + status: + $ref: '#/components/schemas/N2CStatus' + N2CProviderType: + description: Signals the exchange which provider is talking to him. Like this more Providers can be easily supported by adding their verfification flow to the code of nonce2ecash. + type: string + enum: + - WALLEE diff --git a/specs/nonce2ecash_class_diagram.plantuml b/specs/nonce2ecash_class_diagram.plantuml @@ -0,0 +1,90 @@ +@startuml + +interface PaymentVerifier { + verifyPayment(nonce: string): boolean +} + +enum WalleeTransactionState { + CREATE + PENDING + CONFIRMED + PROCESSING + FAILED + AUTHORIZED + VOIDED + COMPLETED + FULFILL + DECLINE +} + +interface WalleeClient { + getTransactionState(): WalleeTransactionState +} + +class PaymentVerifierProxy { + verifiers: PaymentVerifier[] + -- + getVerifierNames(): string[] + getVerifier(name: string): PaymentVerifier +} + +class WalleePaymentVerifier { + walleeClient: WalleeClient + -- + verifyPayment(nonce: string): boolean +} + +class NonePaymentVerifier { + verifyPayment(nonce: string): boolean +} + +interface NonceToReservePubkeyMappingRepository { + createMapping(nonce: string, reservePubkey: byte[]) + removeMapping(nonce: string) + getMapping(nonce: string): +} + +class NonceToReservePubkeyMappingService { + - repo: NonceToReservePubkeyMappingRepository + - paymentVerifier: PaymentVerifier +} + +enum Status { + ESTABLISHED + ESTABLISHMENT_FAILED + PAYED + RESERVE_CREATED + PAYMENT_FAILED +} + +class NonceToReservePubkey { + + providerName: string + + nonce: number + + nonce_provider_sig: byte[] + + reserve_pubkey: number + + state: Status + + established_t_s: timestamp +} + +enum ProviderAttestationType { + NONE + WALLEE +} + +class Provider { + + name: string + + publicKey: byte[] + + publicKeySignature: byte[] + + attestationType: ProviderAttestationType +} + +Provider --* ProviderAttestationType +NonceToReservePubkey --* Status +NonceToReservePubkey --* Provider + +WalleeClient ..> WalleeTransactionState : use +PaymentVerifierProxy --* PaymentVerifier : knows +WalleePaymentVerifier ..> PaymentVerifier : implements +NonePaymentVerifier ..> PaymentVerifier : implements +NonceToReservePubkeyMappingService --> NonceToReservePubkeyMappingRepository: use +@enduml +\ No newline at end of file diff --git a/specs/provider_registration_sequence.plantuml b/specs/provider_registration_sequence.plantuml @@ -0,0 +1,13 @@ +@startuml + +participant Provider +participant Exchange +actor ExchangeOperator as "Exchange Operator" + +Provider -> Provider: Generate Provider Key Pair +Provider -> Provider: Sign Provider Pubkey +Provider -> ExchangeOperator: filled out N2CRegistrationRequest +ExchangeOperator -> Exchange: N2CRegistrationRequest +Exchange -> Exchange: Verify signature and add Provider if legit + +@enduml +\ No newline at end of file diff --git a/specs/wallee_app_class_diagram.plantuml b/specs/wallee_app_class_diagram.plantuml @@ -0,0 +1,88 @@ +@startuml + +class TalerTerminalConfiguration { + - exchangeName: string + - exchangeBaseUrl: string +} + +interface TalerExchangeClient { + -- + + getConfig(): TalerTerminalConfiguration + + getKeys() + + awaitEstablishedNonce() + + notifyAboutPayment() + + getToS() +} + +interface NonceProvider { + -- + + generateNonce() +} + +class Fees { + - talerClient: TalerExchangeClient + -- + + totalFees(): number + - exchangeFees(): number + - walleeFees(): number +} + +class NonceEstablishmentActivity { + - talerExchangeClient: TalerExchangeClient + - nonceProvider: NonceProvider + -- + + displayQrCode() +} + +class WithdrawAmountActivity { + - talerExchangeClient: TalerExchangeClient + -- + + calculateFees() + + displaySummary() +} + +class ApproveConditionsActivity { + - talerExchangeClient: TalerExchangeClient + -- + + accept() + + deny() +} + +class PaymentActivity { +} + +class PaymentResultActivity { +} + + +class RegisterNonceToReservePublicKeyMessage { + - nonce: string + - reservePubKey: byte[] + -- + + RegisterNonceToReservePublicKeyMessage(nonce: string, reservePubKey: byte[]) +} + +class PaymentNotificationMessage { + - nonce: string + - success: bool + - amount: double + - fees: double + -- + + PaymentNotificationMessage(nonce: string, success: bool, amount: double, fees: double) +} + +class NonceQR { + - nonce: string + - exchangeConfiguration: TalerTerminalConfiguration +} + +TalerExchangeClient ..> TalerTerminalConfiguration : use +NonceEstablishmentActivity --> NonceQR : use +NonceEstablishmentActivity ..> TalerExchangeClient : use +NonceEstablishmentActivity ..> NonceProvider : use +WithdrawAmountActivity ..> TalerExchangeClient : use +ApproveConditionsActivity ..> TalerExchangeClient : use + +Fees ..* TalerExchangeClient : use + +@enduml +\ No newline at end of file diff --git a/specs/wallee_app_sequence.plantuml b/specs/wallee_app_sequence.plantuml @@ -0,0 +1,22 @@ +@startuml +participant User +participant Wallet +participant Terminal +participant Exchange +participant TerminalBackend as "Terminal-Backend" +participant Merchant as "Merchant (Terminal Owner)" + +activate Terminal +Terminal -> Terminal: load configuration +Wallet -> Exchange: Establish nonce2ecash mapping +Wallet -> Terminal: Generate and show QR code +Merchant -> Terminal: Enter withdrawal amount +Terminal -> User: Show withdrawal summary and ToS\n(including computed fees) +User -> Terminal: Accept fees & ToS +Terminal -> User: Prompt to show Credit Card +User -> Terminal: Show Credit Card +Terminal -> TerminalBackend: process payment +TerminalBackend -> Terminal: response +Terminal -> User: Show transaction result +deactivate Terminal +@enduml
