commit 1a08da5430dbc1f4ed90b54c84c87bf932997101
parent e36000bf3dbfe63d3877b950ae4d4e5621f1720e
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Mon, 3 Jun 2024 16:46:19 +0200
fix: enhance logging
Diffstat:
11 files changed, 31 insertions(+), 818 deletions(-)
diff --git a/c2ec/api-wire-gateway.go b/c2ec/api-wire-gateway.go
@@ -196,6 +196,7 @@ func transfer(res http.ResponseWriter, req *http.Request) {
decodedRequestUid := bytes.NewBufferString(transfer.RequestUid).Bytes()
t, err := DB.GetTransferById(decodedRequestUid)
if err != nil {
+ LogWarn("wire-gateway-api", "failed retrieving transfer for requestUid="+transfer.RequestUid)
LogError("wire-gateway-api", err)
setLastResponseCodeForLogger(HTTP_INTERNAL_SERVER_ERROR)
res.WriteHeader(HTTP_INTERNAL_SERVER_ERROR)
diff --git a/c2ec/db-postgres.go b/c2ec/db-postgres.go
@@ -517,7 +517,7 @@ func (db *C2ECPostgres) GetConfirmedWithdrawals(start int, delta int, since time
LogInfo("postgres", fmt.Sprintf("selected query=%s (for parameters delta=%d, start=%d, since=%d)", query, delta, start, since.Unix()))
limit := math.Abs(float64(delta))
- offset := start
+ offset := start - 1
if delta < 0 {
offset = start - int(limit)
}
diff --git a/docs/content/acknowledgements.tex b/docs/content/acknowledgements.tex
@@ -6,4 +6,6 @@ Also I thank my colleagues from the class who motivated me during the thesis. Es
Additionally, I would like to thank Meret Staub for her critical thoughts during the proofreading of the thesis.
-Last but not least I thank Flurina from all my heart. You were not mad at me when I had to cancel dinner, because I wanted to write some code.
+Thank you to Bruno Fauser generously providing the title picture.
+
+Last but not least I thank Flurina from all my heart. You were not mad at me when I cancelled dinner, because I wanted to write some code.
diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex
@@ -69,14 +69,14 @@ The Taler Wirewatch Gateway API \cite{taler-wire-gateway-api} must be implemente
The Wirewatch Gateway helps the Exchange communicate with the C2EC component using the API. It helps the Exchange to fetch guarantees, that a certain transaction went through and that the reserve can be created and withdrawn. This will help C2EC to capture the transaction of the Terminal Backend to the Exchange's account and therefore allow the withdrawal by the customer. The Wirewatch Gateway API is implemented as part of C2EC. When the Wirewatch Gateway can get the proof, that a transaction was successfully processed, the Exchange will create a reserve with the corresponding reserve public key.
-For C2EC not all endpoints of the Wire Gateway API are needed. Therefore the endoints which are not needed will be implemented but always return http status code 400.
+The Wire Gateway API of C2EC does not implement the testing endpoint \textit{/admin/add-incoming}. The endoint will respond with HTTP status code 501 (not implemented).
\subsection{C2EC Entities}
\label{sec-architecture-entities}
The entities of the C2EC component must track two different aspects. The first is the mapping of a nonce (the \textit{WOPID}) to a reserve public key to enable withdrawals and the second aspect is the authentication and authorization of terminals allowing withdrawals owned by terminal providers like \textit{Wallee}.
-The detailed explanation and ERD can be found in \autoref{sec-implementation-database}.
+A detailed explanation and ERD can be found in \autoref{sec-implementation-database}.
\subsubsection{Terminal Provider}
\autoref{fig-erd-terminal-provider} describes the provider entity of C2EC compliant terminals. The name of the provider is important, because it decides which flow shall be taken in order to attest the payment. For example will the name \textit{Wallee} signal the terminal provider to trigger the confirmation flow of \textit{Wallee} once the payment notification for the withdrawal reaches C2EC.
@@ -89,7 +89,7 @@ The Entity displayed in \autoref{fig-erd-withdrawal} represents the withdrawal p
\subsubsection{Relationships}
\label{sec-architecture-entities-relationships}
-The structure of the three entities form a tree which is rooted at the terminal provider. Each provider can have many terminals and each terminal can have many withdrawals. The reverse does not apply. A withdrawal does always belong to exactly one terminal and a terminal is always linked to exactly one provider. These relations are installed by using foreign keys, which link the sub-entities (Terminal and Withdrawal) to their corresponding owners (Provider and Terminal). A provider owns its terminals and a terminal owns its Withdrawals.
+The structure of the three entities form a tree which is rooted at the terminal provider. Each provider can have many terminals and each terminal can have many withdrawals. The reverse does not apply. A withdrawal does always belong to exactly one terminal and a terminal is always linked to exactly one provider. These relations are installed by using foreign keys, which link the sub-entities (terminal and withdrawal) to their corresponding owners (provider and terminal). A provider owns its terminals and a terminal owns its withdrawals.
\begin{figure}[H]
\centering
diff --git a/docs/content/expl_fragments.tex b/docs/content/expl_fragments.tex
@@ -1,440 +0,0 @@
-\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/implementation/d-security.tex b/docs/content/implementation/d-security.tex
@@ -8,7 +8,7 @@ To review and validate the security of the design two cases were reviewed. The f
The WOPID is used to link a reserve public key to a withdrawal operation. Since the registration is done through an API, an attacker could try to be first and register its own reserve public key before the customer. When the WOPID is somehow precomputable, an attacker could steal the money by registering their own reserve public key before the customer. This threat is mitigated by the request of the wallet resulting in a conflict response code when trying to add a reserve public key to an already registered withdrawal operation. The customer will see this error and not authorize the transaction and instead abort the withdrawal.
-Further a WOPID can be abused triggering a confirmation or an abort request at the Terminals API or an abort request at the Bank-Integration API. The confirmation or abort from the side of the terminal are mitigated through the authentication of the terminals. When the eavesdropping adversary (EAV) \cite{katz2020introduction} can somehow access the communication between a terminal and C2EC, the WOPID cannot be abused without also breaking the terminals credentials. What if the attacker decides to use the unauthenticated Bank-Integration API the wallet would normally use? The specification does not require some proof that the requester is the wallet. This could lead to tampering of the withdrawals in the time window of the confirmation of the payment. The problem could be mitigated by sending a signed token in the request (the request already is a POST request). The wallet could use its reserve private key to sign the token. The Bank-Integration API could then verify the token using the reserve public key assigned to the withdrawal operation. It is understandable that the risk is accepted, since a potential adversary would need to be sophisticated (needs to redirect requests of the wallet and read WOPID from the request). What about wallets run by people in countries which are politically not as stable as Switzerland and censorship is a problem? Maybe it's a good idea to add some mean of authentication to at least the abort endpoint of the Bank-Integration API. On the other hand the attacker needs access to the victims phone anyway and could possibly also use the keys.
+Further a WOPID can be abused triggering a confirmation or an abort request at the Terminals API or an abort request at the Bank-Integration API. The confirmation or abort from the side of the terminal are mitigated through the authentication of the terminals. When the eavesdropping adversary (EAV) \cite{katz2020introduction} can somehow access the communication between a terminal and C2EC, the WOPID cannot be abused without also breaking the terminals credentials. What if the attacker decides to use the unauthenticated Bank-Integration API the wallet would normally use? The specification does not require some proof that the requester is the wallet owning the private key of the reserve. This could lead to tampering of the withdrawals in the time window of the confirmation of the payment. The problem could be mitigated by sending a signed token in the request (the request already is a POST request). The wallet could use its reserve private key to sign the token. The Bank-Integration API could then verify the token using the reserve public key assigned to the withdrawal operation. It is understandable that the risk is accepted, since a potential adversary would need to be sophisticated (needs to redirect requests of the wallet and read WOPID from the request). What about wallets run by people in countries which are politically not as stable as Switzerland and censorship is a problem? Maybe it's a good idea to add some mean of authentication to at least the abort endpoint of the Bank-Integration API. On the other hand the attacker needs access to the victims phone anyway and could possibly also use the keys.
\subsubsection{Trying To Withdraw Money Without Paying}
@@ -56,17 +56,17 @@ The database user executing a database query must have enough rights to execute
\subsection{Authenticating At The Wallee ReST API}
\label{sec-security-auth-wallee}
-The Wallee API specifies four Wallee specific headers which are used to authenticate against the API. It defines its own authentication standard and flow. The flow builds on a message authentication code (MAC) which is built on a version, user identifier, and a timestamp. For the creation of the MAC the hash based message authentication code (HMAC) SHA-512 is leveraged which takes \textit{application-user-key} (which is just an access-token the user receives when creating a new API user in the management backend of Wallee) as key and the above mentioned properties plus information about the requested http method and the exactly requested path (including request parameters) as message \cite{wallee-api-authentication}. The format of the message is specified like:
+The Wallee API specifies four Wallee specific headers which are used to authenticate against the API. It defines its own authentication standard and flow. The flow builds on a message authentication code (MAC) which is built on a version, user identifier, and a timestamp. For the creation of the MAC the hash based message authentication code (HMAC) SHA-512 is leveraged which takes \textit{application-user-key} (which is just an access-token the user receives when creating a new API user in the management backend of Wallee) as key and the above mentioned properties plus information about the requested HTTP method and the exactly requested path (including request parameters) as message \cite{wallee-api-authentication}. The format of the message is specified like:
\begin{center}
- \texttt{Version|User-Id|Unix-Timestamp|Http-Method|Path}
+ \texttt{Version|User-Id|Unix-Timestamp|HTTP-Method|Path}
\end{center}
\begin{itemize}
\item Version: The version of the algorithm
\item User-Id: The user-id of the requesting user
\item Unix-Timestamp: A unix timestamp (seconds since 01.01.1970)
- \item Http-Method: one of \texttt{HEAD}, \texttt{GET}, \texttt{POST}, \texttt{PUT}, \texttt{DELETE}, \texttt{TRACE}, \texttt{CONNECT}
+ \item HTTP-Method: one of \texttt{HEAD}, \texttt{GET}, \texttt{POST}, \texttt{PUT}, \texttt{DELETE}, \texttt{TRACE}, \texttt{CONNECT}
\item Path: The path of the requested URL including the query string (if any)
\end{itemize}
diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex
@@ -1,20 +1,18 @@
\section{Discussion}
-Our work shows that withdrawals in GNU Taler are possible using the payment service provider Wallee. The C2EC implementation shows how the process can be implemented and integrated into the rest of the Taler ecosystem.
+Our work shows that withdrawals in GNU Taler are possible using the payment service provider Wallee. The C2EC implementation shows how the process can be implemented and integrated into the rest of the Taler ecosystem.
-The design of the Terminals API was a major field of work during the process. Only after several iterations, the specification was ready. The iterations were necessary to sharpen the understanding of how the terminal and C2EC must interact and integrate with the existing Taler components in order to make the withdrawals functional.
+The design of the Terminals API was a major field of work during the process. Only after several iterations, the specification was ready. The iterations were necessary to sharpen the understanding of how the terminal and C2EC must interact and integrate with the existing Taler components in order to make the withdrawals functional.
-The implementation of the existing Bank-Integration and Wire-Gateway API were a challenge because they must be implemented with great care to not violate the specification. Another challenging task was the design of C2EC. To create a useful, robust and extensible design other components of Taler must have been understood. This task was a little more time consuming than initially planned. I thought at first that I would understand how to implement C2EC and then just simply do it. In reality the process was iterative. Only after a lot of iterations I was able to find a suitable way for the implementation.
+The implementation of the existing Bank-Integration and Wire-Gateway API were a challenge because they must be implemented with great care to not violate the specification. Another challenging task was the design of C2EC. To create a useful, robust and extensible design other components of Taler must have been understood. This task was a little more time consuming than initially planned. At first I assumed that I would understand how to implement C2EC and then just simply do it. In reality the process was iterative. Only after a lot of iterations I was able to find a suitable way for the implementation.
-A challenge which was encountered during the implementation of the terminal application and the C2EC component, was the concurrency of processes. To make the withdrawal flow as easy and useful as possible to the user, a lot of tasks need to be covered in the background and run in parallel. This added the technical requirement to decouple steps and leverage retries to increase the robustness of the process.
+A challenge which was encountered during the implementation of the terminal application and the C2EC component, was the concurrency of processes. To make the withdrawal flow as easy and useful as possible to the user, a lot of tasks need to be covered in the background and run besides each other. This added the technical requirement to decouple steps and leverage retries to increase the robustness of the process.
-Towards the end of the implementation it became obvious that a simple authorization was not enough to imitate the real time feeling of the withdrawal. Other requests were necessary to do so. To findout which requests needed to be filed against the Wallee backend some investigation had to be made. The documentation does explain which states exists in Wallee's transaction scheme but does not explain, which operation must be triggered to transition states. This made the investigation somewhat cumbersome. Also the integration of the backend needed more investigation than I thought.
-
-For the analysis of the security of the system I was happy to find STRIDE which helped me to identify possible threats. I found it hard to identify real threats and not loosing time about threats which were out of scope. In the end I think the solution is quite secure in terms of money. Of course you can steal terminals and wreck the nerves of the terminal operators but you won't be able to somehow manipulate the payment process which will allow you to steal money or harm the Exchange operator.
+Towards the end of the implementation it became obvious that a simple authorization was not enough to imitate the real time feeling of the withdrawal. Other requests were necessary to do so. To findout which requests needed to be filed against the Wallee backend some investigation had to be made. The documentation does explain which states exists in Wallee's transaction scheme but does not explain, which operation must be triggered to transition states. This made the investigation somewhat cumbersome. Also the integration of the backend needed more investigation than assumed.
\section{Future Work}
-C2EC introduces new ways to access digital cash using GNU Taler. Due to the short time available during the thesis, features and integrations are missing which can make it even more valuable. Because of this I provide a list of future work. Maybe there are other students or collaborators who want to join in and add their features to the existing code. The list might not be complete and any new ideas are appreciated. I splitted the list into the list of extensions and improvements.
+Due to the short time available during the thesis, features and integrations are missing which can make it even more valuable. Because of this I provide a list of future work. Maybe there are other students or collaborators who want to join in and add their features to the existing code. The list might not be complete and any new ideas are appreciated. I splitted the list into the list of extensions and improvements.
\subsection{Extensions}
\begin{enumerate}
@@ -27,7 +25,7 @@ C2EC introduces new ways to access digital cash using GNU Taler. Due to the shor
\subsection{Improvements}
\begin{enumerate}
- \item Wallet integration: the integration of the wallet needs to be tested
+ \item Wallet integration: the integration of the wallet needs to be further tested
\item Run the existing implementation as part of the BFH Taler CHF-Exchange
\item Paydroid app: Run a Wallee terminal on behalf of the BFH.
\item C2EC: Remove doubled provider structures. Currently providers are saved to the database and must be configured in the configuration. To make the setup and management easier, the providers could only be configured inside the configuration.
diff --git a/docs/content/results/reflexion.tex b/docs/content/results/reflexion.tex
@@ -8,28 +8,30 @@ Generally I think I did an acceptable job in the implementation. I was able to i
The implementation of C2EC was the biggest part of my work during the thesis. It is the core of the framework and I had to think about API specification conformance, extensibility, correctness and database integration. I wanted to achieve an architecture, which is similar to the one of the GNU Taler Exchange. This inlcuded to decouple steps in the withdrawal process using triggers and the notify feature of postgres. I learned a lot about how postgres works and how I can write working postgres functions and triggers. First I failed to properly document the database fields, tables and functions. After a review with Prof. Dr. Christian Grothoff I learned about the comment functionality of the postgres SQL standard.
-In Go code of the C2EC component I had to implement a robust way to communicate between parallel running processes. Go's concurrency model made this possible in an easy and what I think, comprehensible way. I correctly anticipated that it would pay out to first implement the concepts for my requirements in a dummy project and then adapt this to C2EC. Additionally the implementation of the database access layer behind an interface allows to change the database easily.
+In Go code of the C2EC component I had to implement a robust way to communicate between parallel running processes. Go\'s concurrency model made this possible in an easy and what I think, comprehensible way. I correctly anticipated that it would pay out to first implement the concepts for my requirements in a dummy project and then adapt this to C2EC. Additionally the implementation of the database access layer behind an interface allows to change the database without changing the entire application.
-Concerning the extensibility of C2EC I was able to implement code level abstractions which allow an easy integration of additional payment system providers. After the feedback of Prof. Dr. Christian Grothoff I was could eliminate an unnecessary layer of abstraction, which makes it even easier.
+Concerning the extensibility of C2EC I was able to implement code level abstractions which allow an easy integration of additional payment system providers. After the feedback of Prof. Dr. Christian Grothoff I was could eliminate an unnecessary layer of abstraction, which made it even easier.
-I think I could apply a lot of knowledge I gained through the past three years. From time to time I was thinking: "ah, this is why the professor told us this". This helped me to harden my understanding of various topics.
+I think I could apply a lot of knowledge I gained through the past three years. From time to time I was thinking: "ah, this is why the prof told us this". This helped me to harden my understanding of various topics.
\subsubsection{Paydroid Terminal Application}
-The paydroid application was challenging to me since I never wrote a real Android application on my own. That's why I think I did a good job by implementing a best practice structure with the view models, composable and navigation controller. Through the feedback of Prof. Dr. Benjamin Fehrensen I was able to verify the correctness of these best practices.
+The paydroid application was challenging to me since I never wrote a real Android application on my own. That\'s why I think I did a good job by implementing a best practice structure with the view models, composable and navigation controller. Through the feedback of Prof. Dr. Benjamin Fehrensen I was able to improve the design and verify the correctness of these best practices.
-I first had problems to understand how exactly the versioning in Android works. The backward compatibility is given even when big time gaps between the feature needed and the version in use occur. In the beginning I suffered a little to understand the difference of the none compose and compose era of Android programming and mixed the patterns first. In the end I think I implemented a modern Android app.
+I first had problems to understand how exactly the versioning in Android works. The backward compatibility is given even when big time gaps between the feature needed and the version in use occur. In the beginning I suffered a little to understand the difference of the none compose and compose era of Android programming and mixed the patterns. In the end I think I implemented a modern Android app.
-Since the app needs to do requests in the background I had to understand how this could be achieved. Therefore I needed to understand how I can access other threads. I think in this area is the biggest shortcoming of my implementation. I implemented a asynchronous state-handling. Threads running detached from the UI-Thread will update the model, which will lead to the regeneration of the composables. I think it would be a better way to implement a proper pub / sub model using a library like rxjs or similar. Due to the lack of time I decided to not do this anymore.
+Since the app needs to do requests in the background I had to understand how this could be achieved. Therefore I needed to understand how I can access other threads. I think in this area is the biggest shortcoming of my implementation. I implemented an asynchronous state-handling. Threads running detached from the UI-Thread will update the model, which will lead to the regeneration of the composables. I think it would be a better way to implement a proper pub / sub model using a libraries like rxjs or Androids state flow features. Due to the lack of time I decided to not do this anymore.
-It was interesting to learn about the difference of Go's goroutines and Kotlin coroutines. While running background tasks using goroutines works perfectly fine, in Kotlin on Android I learnt it is required to start a new thread and launch coroutines on the new thread. Otherwise Android will not allow network requests, because it disallows I/O operations on its UI thread. From my point of view this shows a limitation of coroutines on top of JVM threads. They are not real parallel but just suspend work on the thread and check periodically if they can process further. If there are thread level restrictions (like the Android restrictions), they will affect the execution of the coroutines on top and like this undermine the concept of coroutines.
+It was interesting to learn about the difference of Go\'s goroutines and Kotlin\'s coroutines. While running background tasks using goroutines works perfectly fine, in Kotlin on Android I learnt it is required to start a new thread and launch coroutines on the new thread. Otherwise Android will not allow network requests, because it disallows I/O operations on its UI thread. From my point of view this shows a limitation of coroutines on top of JVM threads. They are not real parallel but just suspend work on the thread and check periodically if they can process further. If there are thread level restrictions (like the Android restrictions), they will affect the execution of the coroutines on top and like this undermine the concept of coroutines.
\subsection{Methodically}
-To organize the work I did a rough planning of the work and the artefacts. On top of this plan I did a weekly iterative planning of the work I wanted to do. This plan was presented through the weekly meeting with Prof. Dr. Christian Grothoff and Prof. Dr. Benjamin Fehrensen. Sometimes the plan needed to be sligthly adjusted due to their feedback. This led to the organization of doing my planning at thursday night so I could plan my work and adjust the plan after our weekly meeting at wednesday morning. I think I could have made the process a bit more transparent but in the end I was able to deliver the artefacts and deliverables on time. Sometimes I lost focus because there were so much loose ends to keep up with. I then did something different and ordered my thoughts. This helped sometimes but not always. When the stress level was rising this was even more difficult. In such situations taking a step back and prioritzing the work helped me.
+To organize the work I did a rough planning of the work and the artefacts in the beginning. On top of this plan I did a weekly iterative planning of the work I wanted to do. This plan was presented through the weekly meeting with Prof. Dr. Christian Grothoff and Prof. Dr. Benjamin Fehrensen. Sometimes the plan needed to be sligthly adjusted due to their feedback. This led to the organization of doing my planning at thursday night so I could plan my work and adjust the plan after our weekly meeting at wednesday morning. I think I could have made the process a bit more transparent but in the end I was able to deliver the artefacts and deliverables on time. Sometimes I lost focus because there were so much loose ends to keep up with. I then did something different and ordered my thoughts. This helped sometimes but not always. When the stress level was rising this was even more difficult. In such situations taking a step back and prioritzing the work helped me.
\subsection{Personally}
-The thesis was constrained with a lot of insecurities for me. How does the process look? How can I implement the process? How does GNU Taler even work? How does Wallee work? In the end I am proud of what I accomplished during the thesis. I was able to understand the API and write a program which fulfills the properties needed for the withdrawal. Additionally I could learn a lot about designing an API. I am thankful that the Bern University of Applied Sciences supports free software projects like GNU Taler. It was a great opportunity for me as student to gain direct insights and work on a GNU project during my thesis. I remember Prof. Dr. Christian Grothoff telling me during an onsite session: "Nicht so kurzfristig denken!" (don't think shortterm). This also shows the horizon of the project. It tries to sustainably change the payment landscape (for good I think). That is what I like the most about free software. It is built to last.
+The world of payment systems seems a bit chaotic to me. I think this is the result of a lot of different approaches for the same problem developed at the same time. Standards exist but they mainly suggest things and do not enforce them. The technical documentation is obfuscated in big documents with a lot of boiler plate text. This makes it very hard to act appropriately without finding out by hand how a process works exactly. For example to bring a Wallee transaction into the fulfill state (which allows the shipping of goods) you must settle the transaction and execeute the final balance. The documentation does not care about this. I had to write e-mails with Wallee to finally understand this. Even the people of Wallee messed up their own transaction states. All this for the profit of some payment service providers and because banks hesitate to resolve some of their issues at the roots.
-The world of payment systems seems a bit chaotic to me. I think this is the result of a lot of different approaches developed at the same time for the same problem. There are standards but they mainly suggest things and do not enforce them. The technical documentation is obfuscated in big documents with a lot of boiler plate text. This makes it very hard to handle appropriately without finding out how a process works exactly by hand. For example to bring a Wallee transaction into the fulfill state (which allows the shipping of goods) you must settle the transaction and execeute the final balance. The documentation does not care about this. I had to write e-mails with Wallee to finally understand this. Even the people of Wallee messed up their own transaction states.
+The thesis was constrained with a lot of insecurities for me. How does the process look? How can I implement the process? How does GNU Taler even work? How does Wallee work? In the end I am proud of what I accomplished during the thesis. I was able to understand the different API and write a program which fulfills the properties needed for the withdrawal. Additionally I could learn a lot about designing an API and especially parallelization in Go and Android.
+
+I am thankful that the Bern University of Applied Sciences supports free software projects like GNU Taler. It was a great opportunity for me as student and as human to gain direct insights and work on a GNU project during my thesis. I remember Prof. Dr. Christian Grothoff telling me during an onsite session: "Nicht so kurzfristig denken!" (don\'t think short-term). This also showed the horizon of the project to me. It tries to sustainably change the payment landscape for good. That is what I like the most about free software. It is built to last. The world will not get better when we keep pushing towards short-term profit benefiting individuals, global warming and war. GNU Taler and other GNU projects are making a difference and take a humanitarian perspective on technology. Providing technology supporting \textit{humans}. This was the reason I started my journey in computer science with my apprenticeship in 2015 and eventually decided to do my thesis on GNU Taler. It has not changed since. Even when my contribution is small I believe it is important. When everyone adds their ideas and work to the plate, we can achieve a better world. The title picture, generously provided by cartoonist Bruno Fauser, visualizes this attitude. Sometimes it\'s hard to not loose faith for the good but; The good wins. Always.
diff --git a/docs/listings/expl_hello.c b/docs/listings/expl_hello.c
@@ -1,8 +0,0 @@
-#include <stdio.h>
-#include <stdlib.h>
-
-int main( /* int argc, char **argv */ )
-{
- printf("Hello World!\n");
- return EXIT_SUCCESS;
-}
diff --git a/docs/listings/specs/api-c2ec.txt b/docs/listings/specs/api-c2ec.txt
@@ -1,342 +0,0 @@
-..
- This file is part of GNU TALER.
-
- Copyright (C) 2014-2024 Taler Systems SA
-
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU Affero General Public License as published by the Free Software
- Foundation; either version 2.1, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
- @author Joel Haeberli
-
-===========================
-The C2EC RESTful API
-===========================
-
-.. note::
-
- **This API is experimental and not yet implemented**
-
-This chapter describe the APIs that third party providers need to integrate to allow
-withdrawals through indirect payment channels like credit cards or ATM.
-
-.. contents:: Table of Contents
-
---------------
-Authentication
---------------
-
-Terminals which authenticate against the C2EC API must provide their respective
-access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header,
-where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and
-must begin with the RFC 8959 prefix.
-
-----------------------------
-Configuration of C2EC
-----------------------------
-
-.. http:get:: /config
-
- Return the protocol version and configuration information about the C2EC API.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The exchange responds with a `C2ECConfig` object. This request should
- virtually always be successful.
-
- **Details:**
-
- .. ts:def:: C2ECConfig
-
- interface C2ECConfig {
- // Name of the API.
- name: "taler-c2ec";
-
- // libtool-style representation of the C2EC protocol version, see
- // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
- // The format is "current:revision:age".
- version: string;
- }
-
------------------------------
-Withdrawing using C2EC
------------------------------
-
-Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier
-(nonce) at the C2EC component. The provider must first create a unique identifier for the withdrawal
-operation (the ``WOPID``) to interact with the withdrawal operation and eventually withdraw using the wallet.
-
-.. http:post:: /withdrawal-operation
-
- Register a `WOPID` belonging to a reserve public key.
-
- **Request:**
-
- .. ts:def:: C2ECWithdrawRegistration
-
- interface C2ECWithdrawRegistration {
- // Maps a nonce generated by the provider to a reserve public key generated by the wallet.
- wopid: ShortHashCode;
-
- // Reserve public key generated by the wallet.
- // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
- reserve_pub_key: EddsaPublicKey;
-
- // Optional amount for the withdrawal.
- amount?: Amount;
-
- // Id of the terminal of the provider requesting a withdrawal by nonce.
- // Assigned by the exchange.
- terminal_id: SafeUint64;
- }
-
- **Response:**
-
- :http:statuscode:`204 No content`:
- The withdrawal was successfully registered.
- :http:statuscode:`400 Bad request`:
- The ``WithdrawRegistration`` request was malformed or contained invalid parameters.
- :http:statuscode:`500 Internal Server error`:
- The registration of the withdrawal failed due to server side issues.
-
-.. http:get:: /withdrawal-operation/$WOPID
-
- Query information about a withdrawal operation, identified by the ``WOPID``.
-
- **Request:**
-
- :query long_poll_ms:
- *Optional.* If specified, the bank will wait up to ``long_poll_ms``
- milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
- response. A client must never rely on this behavior, as the bank may
- return a response immediately.
- :query old_state:
- *Optional.* Default to "pending".
-
- **Response:**
-
- :http:statuscode:`200 Ok`:
- The withdrawal was found and is returned in the response body as ``C2ECWithdrawalStatus``.
- :http:statuscode:`404 Not found`:
- C2EC does not have a withdrawal registered with the specified ``WOPID``.
-
- **Details**
-
- .. ts:def:: C2ECWithdrawalStatus
-
- interface C2ECWithdrawalStatus {
- // Current status of the operation
- // pending: the operation is pending parameters selection (exchange and reserve public key)
- // selected: the operations has been selected and is pending confirmation
- // aborted: the operation has been aborted
- // confirmed: the transfer has been confirmed and registered by the bank
- // Since protocol v1.
- status: "pending" | "selected" | "aborted" | "confirmed";
-
- // Amount that will be withdrawn with this operation
- // (raw amount without fee considerations).
- amount: Amount;
-
- // A refund address as ``payto`` URI. This address shall be used
- // in case a refund must be done. Only not-null if the status
- // is "confirmed" or "aborted"
- sender_wire?: string;
-
- // Reserve public key selected by the exchange,
- // only non-null if ``status`` is ``selected`` or ``confirmed``.
- // Since protocol v1.
- selected_reserve_pub?: string;
- }
-
-
-.. http:post:: /withdrawal-operation/$WOPID
-
- Notifies C2EC about an executed payment for a specific withdrawal.
-
- **Request:**
-
- .. ts:def:: C2ECPaymentNotification
-
- interface C2ECPaymentNotification {
-
- // Unique identifier of the provider transaction.
- provider_transaction_id: string;
-
- // Specifies the amount which was payed to the provider (without fees).
- // This amount shall be put into the reserve linked to by the withdrawal id.
- amount: Amount;
-
- // Fees associated with the payment.
- fees: Amount;
- }
-
- **Response:**
-
- :http:statuscode:`204 No content`:
- C2EC received the ``C2ECPaymentNotification`` successfully and will further process
- the withdrawal.
- :http:statuscode:`400 Bad request`:
- The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters.
- :http:statuscode:`404 Not found`:
- C2EC does not have a withdrawal registered with the specified ``WOPID``.
- :http:statuscode:`500 Internal Server error`:
- The ``C2ECPaymentNotification`` could not be processed due to server side issues.
-
-
---------------
-Taler Wire Gateway
---------------
-
-C2EC implements the wire gateway API in order to check for incoming transactions and
-let the exchange get proofs of payments. This will allow the C2EC componente to add reserves
-and therefore allow the withdrawal of the digital cash. C2EC does not entirely implement all endpoints,
-because the it is not needed for the case of C2EC. The endpoints not implemented are not described
-further. They will be available but respond with 400 http error code.
-
-.. http:get:: /config
-
- Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **0**.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The exchange responds with a `WireConfig` object. This request should
- virtually always be successful.
-
- **Details:**
-
- .. ts:def:: WireConfig
-
- interface WireConfig {
- // Name of the API.
- name: "taler-wire-gateway";
-
- // libtool-style representation of the Bank protocol version, see
- // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
- // The format is "current:revision:age".
- version: string;
-
- // Currency used by this gateway.
- currency: string;
-
- // URN of the implementation (needed to interpret 'revision' in version).
- // @since v0, may become mandatory in the future.
- implementation?: string;
- }
-
-.. http:post:: /transfer
-
- This API allows the exchange to make a transaction, typically to a merchant. The bank account
- of the exchange is not included in the request, but instead derived from the user name in the
- authentication header and/or the request base URL.
-
- To make the API idempotent, the client must include a nonce. Requests with the same nonce
- are rejected unless the request is the same.
-
- **Request:**
-
- .. ts:def:: TransferRequest
-
- interface TransferRequest {
- // Nonce to make the request idempotent. Requests with the same
- // ``request_uid`` that differ in any of the other fields
- // are rejected.
- request_uid: HashCode;
-
- // Amount to transfer.
- amount: Amount;
-
- // Base URL of the exchange. Shall be included by the bank gateway
- // in the appropriate section of the wire transfer details.
- exchange_base_url: string;
-
- // Wire transfer identifier chosen by the exchange,
- // used by the merchant to identify the Taler order(s)
- // associated with this wire transfer.
- wtid: ShortHashCode;
-
- // The recipient's account identifier as a payto URI.
- credit_account: string;
- }
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The request has been correctly handled, so the funds have been transferred to
- the recipient's account. The body is a `TransferResponse`.
- :http:statuscode:`400 Bad request`:
- Request malformed. The bank replies with an `ErrorDetail` object.
- :http:statuscode:`401 Unauthorized`:
- Authentication failed, likely the credentials are wrong.
- :http:statuscode:`404 Not found`:
- The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
- :http:statuscode:`409 Conflict`:
- A transaction with the same ``request_uid`` but different transaction details
- has been submitted before.
-
- **Details:**
-
- .. ts:def:: TransferResponse
-
- interface TransferResponse {
- // Timestamp that indicates when the wire transfer will be executed.
- // In cases where the wire transfer gateway is unable to know when
- // the wire transfer will be executed, the time at which the request
- // has been received and stored will be returned.
- // The purpose of this field is for debugging (humans trying to find
- // the transaction) as well as for taxation (determining which
- // time period a transaction belongs to).
- timestamp: Timestamp;
-
- // Opaque ID of the transaction that the bank has made.
- row_id: SafeUint64;
- }
-
-.. http:get:: /history/incoming
-
- **Request:**
-
- :query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
-
- **Response:**
-
- .. ts:def:: IncomingReserveTransaction
-
- interface IncomingReserveTransaction {
- type: "RESERVE";
-
- // Opaque identifier of the returned record.
- row_id: SafeUint64;
-
- // Date of the transaction.
- date: Timestamp;
-
- // Amount transferred.
- amount: Amount;
-
- // Payto URI to identify the sender of funds.
- debit_account: string;
-
- // The reserve public key extracted from the transaction details.
- reserve_pub: EddsaPublicKey;
-
- }
-
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
