[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-cashless2ecash] branch master updated: chore: save commit
|
From: |
gnunet |
|
Subject: |
[taler-cashless2ecash] branch master updated: chore: save commit |
|
Date: |
Sat, 11 May 2024 12:22:41 +0200 |
This is an automated email from the git hooks/post-receive script.
joel-haeberli pushed a commit to branch master
in repository cashless2ecash.
The following commit(s) were added to refs/heads/master by this push:
new 44c8e94 chore: save commit
44c8e94 is described below
commit 44c8e946064a20030f12899d71de25bc6edea65e
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Sat May 11 12:22:29 2024 +0200
chore: save commit
---
docs/content/abstract.tex | 2 +-
docs/content/appendix/meeting_notes.tex | 22 +++++
docs/content/appendix/project_managment.tex | 0
docs/content/architecture/c2ec.tex | 65 +++++++--------
docs/content/architecture/overview.tex | 32 ++++----
docs/content/implementation/a-c2ec.tex | 16 +++-
docs/content/implementation/b-terminal.tex | 5 +-
docs/content/implementation/c-database.tex | 90 +++++++++++++++++++++
docs/content/implementation/concepts.tex | 4 +-
.../implementation/{wallet.tex => d-wallet.tex} | 0
docs/content/implementation/database.tex | 17 ----
.../{a-security.tex => e-security.tex} | 16 ++--
docs/content/implementation/f-cli.tex | 22 +++++
docs/content/results/results.tex | 7 ++
docs/pictures/database/logical_model_relations.png | Bin 0 -> 22860 bytes
docs/pictures/database/relationships.png | Bin 39397 -> 44482 bytes
docs/pictures/database/table_terminal.png | Bin 31455 -> 31194 bytes
docs/pictures/database/table_terminal_provider.png | Bin 22439 -> 28037 bytes
docs/pictures/database/table_transfer.png | Bin 0 -> 27773 bytes
docs/pictures/database/table_withdrawal.png | Bin 44391 -> 57697 bytes
docs/project.bib | 19 +++++
docs/thesis.pdf | Bin 1971697 -> 2086801
bytes
docs/thesis.tex | 10 ++-
23 files changed, 241 insertions(+), 86 deletions(-)
diff --git a/docs/content/abstract.tex b/docs/content/abstract.tex
index 1d39de6..e6405e1 100644
--- a/docs/content/abstract.tex
+++ b/docs/content/abstract.tex
@@ -1 +1 @@
-In order to buy Taler, the \textit{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
proposes a framework allowing cashless withdrawals using Taler. A reference
implementation is create [...]
+In order to withdraw digital cash in GNU Taler, the \textit{Taler Exchange}
needs guarantees to legally secure the transaction. Withdrawing digital cash
using Taler physically establishes direct trust, since cash can be used in
order to withdraw digital cash and the transaction is completed. If you want to
withdraw digital cash using cashless systems like credit cards, the
\textit{Taler Exchange} has no proof that the payment has succeeded. In order
to fill this cap, this thesis proposes [...]
diff --git a/docs/content/appendix/meeting_notes.tex
b/docs/content/appendix/meeting_notes.tex
index 47cd9f3..e5cfc39 100644
--- a/docs/content/appendix/meeting_notes.tex
+++ b/docs/content/appendix/meeting_notes.tex
@@ -310,6 +310,28 @@
\item Use Version 0.9.20 (not 0.9.12)
\end{itemize}
+\subsection*{08.05.2024}
+
+\textbf{Participants}
+
+\begin{itemize}
+ \item Fehrensen Benjamin
+ \item H\"aberli Joel
+\end{itemize}
+
+\textbf{Topics}
+\begin{itemize}
+ \item Submit APK to Wallee
+ \item Server is online running C2EC
+ \item The Book entry
+\end{itemize}
+
+\textbf{Action points}
+\begin{itemize}
+ \item Supply Wallee and APK (as soon as possible)
+ \item Poster
+\end{itemize}
+
% TEMPLATE %
\subsection*{TEMPLATE}
diff --git a/docs/content/appendix/project_managment.tex
b/docs/content/appendix/project_managment.tex
new file mode 100644
index 0000000..e69de29
diff --git a/docs/content/architecture/c2ec.tex
b/docs/content/architecture/c2ec.tex
index 2b6b566..b2ea4cc 100644
--- a/docs/content/architecture/c2ec.tex
+++ b/docs/content/architecture/c2ec.tex
@@ -11,12 +11,13 @@ From the perspective of C2EC, the system looks as follows:
\begin{itemize}
\item Is requested by the \textit{Taler Wallet} to register a new
\textit{wopid} to reserve public key mapping.
- \item Is notified by the \textit{Wallee Terminal} about a payment.
- \item Attests a payment by requesting the payment proof at the
\textit{Wallee Backend}
- \item Supplies the Taler Wire Gateway API that the respective
\textit{Exchange} can retrieve new transactions and create reserves which are
then created and can be withdrawn by the \textit{Taler Wallet}.
+ \item Is notified by the \textit{Terminal} (e.g. a Wallee terminal) about
a payment.
+ \item Attests a payment by requesting the payment proof at the
\textit{Provider Backend} (e.g. Wallee backend)
+ \item Supplies the Taler Wire Gateway API that the respective
\textit{Taler Exchange} can retrieve fresh transactions and create reserves
which are then created and can be withdrawn by the \textit{Taler Wallet}.
\end{itemize}
\subsection{Withdrawal-Operation state transitions}
+\label{sec-architecture-state-transitions}
Basically C2EC mediates between the stakeholders of a withdrawal in order to
maintain the correct state of the withdrawal. Therefore it decides when a
withdrawal's status can be transitioned. The diagram in
\autoref{fig-withdrawal-operation-state-transition-diagram} shows the
transitions of states in which a withdrawal operation can be and which events
will trigger a transition. The term attestation in this context means, that the
backend of the provider was asked and the transaction was [...]
@@ -29,11 +30,11 @@ Basically C2EC mediates between the stakeholders of a
withdrawal in order to mai
\subsection{Authentication}
-Terminals and the Exchange Wire Watch which authenticate against the C2EC API
using Basic-Auth \cite{rfc7617} must provide their respective access token.
Therefore, they provide a \texttt{Authorization: Basic \$ACCESS\_TOKEN} header,
where \texttt{\$ACCESS\_TOKEN} is a secret authentication token configured by
the operator of the exchange. The header value must begin with the prefix
specified in RFC 7617 \cite{rfc7617}: \textit{Basic}.
+Terminals and the Exchange Wire Watch which authenticate against the C2EC API
using Basic-Auth \cite{rfc7617} must provide their respective access token.
Therefore, they provide a \texttt{Authorization: Basic \$ACCESS\_TOKEN} header,
where \texttt{\$ACCESS\_TOKEN} is a basic-auth value configured by the operator
of the exchange consisting of the terminal username and password. The header
value must begin with the prefix specified in RFC 7617 \cite{rfc7617}:
\textit{Basic}.
\subsection{The C2EC RESTful API}
-This section describes the various API implemented in the C2EC component. The
description contains a short list of the consumers of the respective API.
Consumer in this context does not necessarily mean that data is consumed but
rather that the consumer uses the API to either gather data or send reqeusts or
data to C2EC.
+All components involved in the withdrawal process must interact with the C2EC
component. Therefore this section describes the various API implemented in the
C2EC component. The description contains a short list of the consumers of the
respective API. Consumer in this context does not necessarily mean that data is
consumed but rather that the consumer uses the API to either gather data or
send reqeusts or data to C2EC.
\subsubsection{Terminals API}
@@ -49,6 +50,7 @@ That terminal can initiate and serve withdrawals in Taler,
the Terminals API \ci
\end{itemize}
\textbf{Withdrawals}
+\label{sec-architecture-c2ec-setup-wopid}
\begin{itemize}
\item \textbf{Method:} POST
\item \textbf{Endpoint:} /withdrawals
@@ -76,6 +78,16 @@ That terminal can initiate and serve withdrawals in Taler,
the Terminals API \ci
\item \textbf{Consumers:} The API is used by the \textit{Terminal} to notify
the C2EC component that a payment was made and to give the C2EC component
information about the payment itself (e.g. the provider specific transaction
identifier or optional fees).
\end{itemize}
+\textbf{Fees}
+
+An important aspect of the withdrawal flow using third party providers are the
fees. When the withdrawal operation is not supplied by some exchanges as
standard service, the provider possibly wants to charge fees to the customer in
order to make a profit. The provider might decide to delegate those fees to the
customer and therefore fees can be sent to the C2EC component through the
\textit{check} API specified above. It's also possible that the service of
withdrawing cash through a thir [...]
+
+\begin{quote}
+ Die Händler zahlen jedoch für den Cashback-Service bereits Gebühren an
+ die Banken. Aktuell sind es laut EHI im Schnitt 0,14 Prozent, insgesamt
+ waren das 2023 rund 17,2 Millionen Euro. \cite[Crefeld, ZEIT]{zeit-cashback}
+\end{quote}
+
\textbf{Terminal abortion}
\begin{itemize}
\item \textbf{Method:} DELETE
@@ -88,7 +100,7 @@ That terminal can initiate and serve withdrawals in Taler,
the Terminals API \ci
\subsubsection{Taler Bank Integration API}
-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 \texttt{WOPID}) to
interact with the withdrawal operation and eventually withdraw using the
wallet. The withdrawal operation API is an implementation of the \textit{Bank
Integration API} \cite{taler-bank-integration-api}.
+Withdrawals by the \textit{Wallet} with a C2EC are based on withdrawal
operations which register a reserve public key at the C2EC component. The
provider must first create a unique identifier for the withdrawal operation
(the \texttt{WOPID}) to interact with the withdrawal operation (as described in
\autoref{sec-architecture-c2ec-setup-wopid}) and eventually withdraw digital
cash using the \textit{Wallet}. The withdrawal operation API is an
implementation of the \textit{Bank Integration [...]
\textbf{Config}
\begin{itemize}
@@ -144,48 +156,31 @@ For C2EC not all endpoints of the Wire Gateway API are
needed. Therefore the end
\item \textbf{Consumers:} The \textit{Exchange Wirewatch} who will create
the reserve which then can be withdrawn by the \textit{Taler Wallet}.
\end{itemize}
-\subsection{The C2EC database}
+\subsection{C2EC Entities}
+\label{sec-architecture-entities}
-The database of the C2EC component must track two different aspects. The first
is the mapping of a nonce (the \texttt{WOPID}) to a reserve public key to
enable withdrawals and the second aspect is the authentication of terminals
allowing withdrawals owned by terminal providers like \textit{Wallee}.
+The entities of the C2EC component must track two different aspects. The first
is the mapping of a nonce (the \texttt{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}.
-\subsubsection{Terminal Provider}
-Table in \autoref{fig-erd-terminal-provider} describing providers 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 attestation
flow of \textit{Wallee} once the payment notification for the withdrawal
reaches C2EC.
+The detailed explanation and ERD can be found in
\autoref{sec-implementation-database}.
-\begin{figure}[h]
- \centering
-
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
- \caption{Terminal Provider Table}
- \label{fig-erd-terminal-provider}
-\end{figure}
+\subsubsection{Terminal Provider}
+Entity displayed in \autoref{fig-erd-terminal-provider} describing providers
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
attestation flow of \textit{Wallee} once the payment notification for the
withdrawal reaches C2EC.
\subsubsection{Terminal}
-Table in \autoref{fig-erd-terminal} contains information about terminals of
providers. This includes the provider they belong to and an authentication
token, which is generated by the Exchange and allows authenticating the
terminal. A terminal belongs to one terminal provider.
-
-\begin{figure}[h]
- \centering
- \includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
- \caption{Terminal Table}
- \label{fig-erd-terminal}
-\end{figure}
+Entity displayed in \autoref{fig-erd-terminal} contains information about
terminals of providers. This includes the provider they belong to and an
access-token, which is generated by the operator of the C2EC component. It
allows authenticating the terminal. A terminal belongs to one terminal provider.
\subsubsection{Withdrawal}
-Table in \autoref{fig-erd-withdrawal} represents the withdrawal processes
initiated by terminals. This table therefore contains information about the
withdrawal like the amount, which terminal the withdrawal was initiated from
and which reserve public key is used to create a reserve in the Exchange.
-
-\begin{figure}[h]
- \centering
- \includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
- \caption{Withdrawal Table}
- \label{fig-erd-withdrawal}
-\end{figure}
+Entity displayed in \autoref{fig-erd-withdrawal} represents the withdrawal
processes initiated by terminals. This table therefore contains information
about the withdrawal like the amount, which terminal the withdrawal was
initiated from and which reserve public key is used to create a reserve in the
Exchange.
\subsubsection{Relationships}
-The structure of the three tables forms 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 i [...]
+\label{sec-architecture-entities-relationships}
+The structure of the three entities forms 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 [...]
\begin{figure}[h]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/database/relationships.png}
+
\includegraphics[width=0.7\textwidth]{pictures/database/logical_model_relations.png}
\caption{Relationships of the entities.}
- \label{fig-erd-relationships}
+ \label{fig-logical-model-relations}
\end{figure}
\section{Payto wallee-transaction extension}
diff --git a/docs/content/architecture/overview.tex
b/docs/content/architecture/overview.tex
index 0ef4393..5a9577a 100644
--- a/docs/content/architecture/overview.tex
+++ b/docs/content/architecture/overview.tex
@@ -24,7 +24,7 @@ The \autoref{fig-diagram-all-components} shows a high level
overview of the comp
\begin{enumerate}
\item Wallee Terminal requests to be notified when parameters are
\textit{selected} by C2EC.
\item The Wallet scans the QR code at the Terminal.
- \item The Wallet registers a reserve public key and the \textit{wopid}.
+ \item The Wallet registers a reserve public key and the \textit{WOPID}.
\item The Bank-Integration API of C2EC notifies the Terminal, that the
parameters were selected.
\item The POS initiates a payment to the account of the GNU Taler
Exchange. For the payment the POS terminal requests a payment card and a PIN
for authorizing the payment.
\item The Terminal triggers the payment at the Wallee Backend.
@@ -48,7 +48,7 @@ The \autoref{fig-diagram-all-components} shows a high level
overview of the comp
\label{fig-diagram-all-sequence}
\end{figure}
-The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to
withdraw digital cash using the credit card terminal and Taler. It shows when
the components of \autoref{fig-diagram-all-components} interact with each
other. It shows the implementation of the flow. Terminal, Wallet and Exchange
are linked leveraging a \textit{wopid} initially generated by the terminal and
presented to the Exchange by the withdrawing Wallet accompanied by a reserve
public key.
+The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to
withdraw digital cash using the credit card terminal and Taler. It shows when
the components of \autoref{fig-diagram-all-components} interact with each
other. It shows the implementation of the flow. Terminal, Wallet and Exchange
are linked leveraging a \textit{WOPID} initially generated by the terminal and
presented to the Exchange by the withdrawing Wallet accompanied by a reserve
public key.
The process requires the Terminal, the Wallet, the C2EC component and the
Exchange which interact with each other. In this section the highlevel process
as showed in \autoref{fig-diagram-all-sequence} is explained.
@@ -60,9 +60,9 @@ The Terminal initiates the withdrawal leveraging an
application which works as f
\item At startup of the application, the terminal loads the C2EC
configuration
\item When a user wishes to do a withdrawal, the owner of the terminal
opens the application and initiates a new withdrawal. A withdrawal is basically
a funds transfer to the IBAN account of the \textit{Exchange}.
\begin{enumerate}
- \item Application creates a \textit{wopid}
- \item The application starts long polling at the C2EC and awaits the
selection of the reserve parameters mapped to the \textit{wopid}. The
parameters are sent by the Wallet to C2EC.
- \item \textit{Wopid} is packed into a QR code (with Exchange and
amount entered by the terminal owner)
+ \item Terminal sets up a withdrawal by aksing C2EC to setup a
\textit{WOPID}
+ \item The application starts long polling at the C2EC and awaits the
selection of the reserve parameters mapped to the \textit{WOPID}. The
parameters are sent by the Wallet to C2EC.
+ \item \textit{WOPID} is packed into a QR code (with Exchange and
amount entered by the terminal owner)
\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
\item QR code is displayed
@@ -82,23 +82,23 @@ The Terminal initiates the withdrawal leveraging an
application which works as f
The C2EC component manages the withdrawal using a third party provider (e.g.
Wallee) and seeks guarantees in order to create a reserve containing digital
cash which can be withdrawn by the Wallet.
\begin{enumerate}
- \item C2EC retrieves a long polling request for a \textit{wopid} (from the
Terminal).
- \item C2EC creates a mapping entry with the \textit{wopid} and an empty
reserve public key field
- \item C2EC retrieves a request including a \textit{wopid} and a reserve
public key.
- \item C2EC validates the request and adds the key to the mapping. This
establishes the \textit{wopid} to reserve public key mapping.
- \item C2EC ends the long polling from the terminal (by sending back the
reserve public key).
- \item C2EC receives payment notification of the terminal.
- \item C2EC verifies the notification by asking the terminal backend for
confirmation.
- \item C2EC, upon successfully checking the notification, checks that the
transaction went through and therefore a reserve is created by the wirewatch
gateway (using the public key in the payment purpose field).
+ \item C2EC retrieves setup request for withdrawal which will lead to
generation of the \textit{WOPID}.
+ \item C2EC retrieves a long polling request for a \textit{WOPID} (from the
Terminal).
+ \item C2EC retrieves a request including a \textit{WOPID} and a reserve
public key.
+ \item C2EC validates the request and adds the key to the mapping. This
establishes the \textit{WOPID} to reserve public key mapping.
+ \item C2EC ends the long polling from the terminal.
+ \item C2EC receives confirmation request of the terminal.
+ \item C2EC verifies the notification by asking the provider backend for
confirmation.
+ \item C2EC responds to an incoming transaction request of the Taler
Wirewatch of the Exchange with the reserve public key of the withdrawal (which
will eventually create a withdrawable reserve).
\end{enumerate}
\subsection{The Wallet}
-The Wallet must attest its presence to the terminal by registering a
\textit{wopid} and belonging reserve public key which will holds the digital
currency that can eventually be withdrawn by the Wallet.
+The Wallet must attest its presence to the terminal by registering a
\textit{WOPID} and belonging reserve public key which will hold the digital
cash that can eventually be withdrawn by the Wallet.
\begin{enumerate}
- \item The Wallet scans the QR Code (\textit{wopid}, Exchange information
and amount) on the Terminal
+ \item The Wallet scans the QR Code (\textit{WOPID}, Exchange information
and amount) on the Terminal
\item It creates a reserve key pair
- \item The Wallet sends the reserve public key and the scanned
\textit{wopid} to the C2EC
+ \item The Wallet sends the reserve public key and the scanned
\textit{WOPID} to the C2EC
\item The Wallet can withdraw digital cash from the created reserve.
\end{enumerate}
diff --git a/docs/content/implementation/a-c2ec.tex
b/docs/content/implementation/a-c2ec.tex
index 4d83373..33d6db1 100644
--- a/docs/content/implementation/a-c2ec.tex
+++ b/docs/content/implementation/a-c2ec.tex
@@ -9,6 +9,13 @@ The diagram in \autoref{fig-diagram-c2ec-apis-sequence} shows
the perspective of
The implementation of the terminals API can be found in
\autoref{sec-implementation-terminal-api}, the bank integration API is
documented in \autoref{sec-implementation-bank-integration-api} and the wire
gateway API implementation is documented in
\autoref{sec-implementation-wire-gateway-api}
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/diagrams/c2ec_apis.png}
+ \caption{C2EC and its interactions with various components}
+ \label{fig-diagram-c2ec-apis-sequence}
+ \end{figure}
+
\subsubsection{Decoupling steps using Events}
The concept of publishers and subscribers is used heavily in the
implementation. It allows decoupling different steps of the process and allows
different steps to be handled and executed in their own processes. Publishers
can also be called notifiers or similar, while the subscriber can also be
called listener or similar.
@@ -49,14 +56,17 @@ Following a short list of events and from whom they are
triggered and who listen
\end{itemize}
\end{itemize}
+\newpage
\include{content/implementation/a-terminal-api}
+\newpage
\include{content/implementation/a-bank-integration-api}
+\newpage
\include{content/implementation/a-wire-gateway-api}
+\newpage
\include{content/implementation/a-processes}
-\include{content/implementation/a-providers}
-
-\include{content/implementation/a-security}
+\newpage
+\include{content/implementation/a-providers}
\ No newline at end of file
diff --git a/docs/content/implementation/b-terminal.tex
b/docs/content/implementation/b-terminal.tex
index 1ec4b72..ed0de06 100644
--- a/docs/content/implementation/b-terminal.tex
+++ b/docs/content/implementation/b-terminal.tex
@@ -73,4 +73,7 @@ When the transaction was processed successfully, the summary
of the transaction
\includegraphics[width=0.7\textwidth]{pictures/wallee/authorize_transaction_screen_2.png}
\caption{Terminal: Payment authorized}
\label{fig-terminal-screen-authorized}
-\end{figure}
\ No newline at end of file
+\end{figure}
+
+
+\newpage
\ No newline at end of file
diff --git a/docs/content/implementation/c-database.tex
b/docs/content/implementation/c-database.tex
new file mode 100644
index 0000000..e181468
--- /dev/null
+++ b/docs/content/implementation/c-database.tex
@@ -0,0 +1,90 @@
+\section{Database}
+\label{sec-implementation-database}
+
+The Database is implemented using Postgresql. This database is also used by
other Taler components and therefore is a good fit.
+
+Besides the standard SQL features to insert, update and select data, Postgres
also comes with handy features like LISTEN and NOTIFY.
+
+This allows the implementation of neat pub/sub models allowing better
performance, separation of concerns and loose coupling.
+
+\subsection{Schema}
+
+For the C2EC component the schema c2ec is created. It holds tables to store
the entities described in \autoref{sec-architecture-entities}. Additionally it
contains the table for transfers which is used to capture refunds requested by
the \textit{Exchange}.
+
+\subsubsection{Terminal Provider}
+
+The \textit{terminal provider} table holds information about the provider. It
contains the information, which payto target type is used to make transactions
by the provider. This information is needed in the refund case where the
\textit{Exchange} sends a transfer request. It also holds information about the
attestation endpoint. Namely the base url and the credentials to authenticate
the attestation process against the API of the providers backend. When adding
the provider using the cli [...]
+
+\begin{figure}[h]
+ \centering
+
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
+ \caption{Terminal Provider Table}
+ \label{fig-erd-terminal-provider}
+\end{figure}
+
+\subsubsection{Terminal}
+
+Each Terminal must register before withdrawals are possible using the
terminal. Therefore this table holds the information needed for withdrawals. A
terminal can be deactivated by setting the \textit{active} field accordingly.
The terminals are authenticated using an access token generated during the
registration process. Like adding the provider through the cli also the
terminal access tokens will be encrypted using a PBKDF (namely argon2). The
terminal is linked through the \textit{pro [...]
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
+ \caption{Terminal Table}
+ \label{fig-erd-terminal}
+\end{figure}
+
+\subsubsection{Withdrawal}
+
+The withdrawal table is the heart of the application as it captures the
information and state for each withdrawal. besides the obvious fields like
\textit{amount}, \textit{wopid}, \textit{reserve\_pub\_key} or
\textit{terminal\_fees} (which all are directly related to one of the API calls
described in \autoref{sec-implementation-terminal-api} or
\autoref{sec-implementation-bank-integration-api}), the table also holds the
\textit{terminal\_id} which identifies the terminal which initiated [...]
+The \textit{withdrawal\_status} holds the current state of the withdrawal and
is transitioned as described in \autoref{sec-architecture-state-transitions}.
The \textit{request\_uid} is a unqiue identifier supplied by the terminal
setting up a withdrawal. It is used to support idempotence of the API.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
+ \caption{Withdrawal Table}
+ \label{fig-erd-withdrawal}
+\end{figure}
+
+\subsubsection{Transfers}
+
+The transfer table is maintained through the transfer endpoint as described in
\autoref{sec-implementation-wire-gateway-api}. A transfer in case of C2EC is
constrained with a refund activity. The besides the fields indicated by the
Wire Gateway API \textit{request\_uid}, \textit{row\_id}, \textit{amount},
\textit{exchange\_base\_url}, \textit{wtid}, \textit{credit\_account} and
\textit{transfer\_ts} which are all used to store information about the
transfer, the fields \textit{transfer\_ [...]
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/table_transfer.png}
+ \caption{Transfer Table}
+ \label{fig-erd-transfer}
+\end{figure}
+
+\subsubsection{Relationships}
+
+The relationships of the tables are created as described in
\autoref{sec-architecture-entities-relationships}. A withdrawal belongs to a
terminal and a terminal belongs to a provider. These relationships are
implemented using foreign keys. The are specified to be non-null and therefore
make sure, the chain of provider, terminal and withdrawal is always complete.
The \textit{transfer} table is unattached and lives by himself.
+
+\begin{figure}[h]
+ \centering
+ \includegraphics[width=0.7\textwidth]{pictures/database/relationships.png}
+ \caption{Relationships of the entities.}
+ \label{fig-erd-relationships}
+ \end{figure}
+
+\subsection{Triggers}
+
+Triggers are used to decouple the different sub processes in the withdrawal
flow from one another.
+
+The trigger runs a Postgres function which will execute a NOTIFY statement
using Postgres built-in function \textit{pg\_notify}. Listeners in the
application will capture those notifications and process them.
+
+\subsubsection{Withdrawal Status Trigger}
+
+The withdrawal status trigger emits the status of a withdrawal when the status
is changed or the withdrawal is generated (inserted). The notification is sent
through a channel which is named after the withdrawal using the \textit{WOPID}
in base64 encoded format. This allows a listener to specifically be notified
about one specific withdrawal. This feature is used by the long poll feature of
the status reqeuests described in \autoref{sec-implementation-terminal-api} or
\autoref{sec-implem [...]
+
+\subsubsection{Payment Trigger}
+
+The payment trigger is triggered through the withdrawal confirmation request
of the Terminals API (described in \autoref{sec-implementation-terminal-api}).
It will start the attestation of the transaction at the providers backend,
through the provider specific attestation process.
+
+\subsubsection{Attestation Retry Trigger}
+
+If the attestation for a withdrawal fails, this trigger is responsible to
notify the retry listener of the application to retry the attestation.
Therefore the trigger calls the \textit{emit\_retry\_notification} function
which will notify its listener and the retry will eventually be executed.
+
+\subsubsection{Transfer Trigger}
+
+The transfer trigger is responsible triggering the transfer process by the
application emiting the \textit{request\_uid} of the respective transfer,
through the \textit{emit\_transfer\_notification}.
diff --git a/docs/content/implementation/concepts.tex
b/docs/content/implementation/concepts.tex
index bb119bf..d7174dc 100644
--- a/docs/content/implementation/concepts.tex
+++ b/docs/content/implementation/concepts.tex
@@ -1,3 +1 @@
-\section{How to read this section}
-
-The implementation is documented per component (C2EC, Terminal, Database).
This means that each feature is documented from the perspective of the
respective component in another section. Remarkable interactions with other
components are linked with and shall support the reader to jump between the
different components explanations interacting with each other. The reader is
therefore advised to read the document on a digital device for easier reading.
Also diagrams might be hard to see whe [...]
\ No newline at end of file
+The implementation is documented per component (C2EC, Terminal, Database).
This means that each feature is documented from the perspective of the
respective component in another section. Remarkable interactions with other
components are linked with and shall support the reader to jump between the
different components explanations interacting with each other. The reader is
therefore advised to read the document on a digital device for easier reading.
Also diagrams might be hard to see whe [...]
\ No newline at end of file
diff --git a/docs/content/implementation/wallet.tex
b/docs/content/implementation/d-wallet.tex
similarity index 100%
rename from docs/content/implementation/wallet.tex
rename to docs/content/implementation/d-wallet.tex
diff --git a/docs/content/implementation/database.tex
b/docs/content/implementation/database.tex
deleted file mode 100644
index 38806d6..0000000
--- a/docs/content/implementation/database.tex
+++ /dev/null
@@ -1,17 +0,0 @@
-\section{Database}
-
-The Database is implemented using Postgresql. This database is also used by
other Taler components and therefore is a good fit.
-
-Besides the standard SQL features to insert and select data, Postgres also
comes with handy features like LISTEN and NOTIFY.
-
-This allows the implementation of neat pub/sub models allowing better
performance, separation of concerns and loose coupling.
-
-\subsection{Schema}
-
-For the C2EC component the schema c2ec is created. It holds three tables,
custom types and triggers.
-
-\subsection{Triggers}
-
-Triggers are used to decouple the different sub processes in the withdrawal
flow from one another.
-
-The trigger runs a Postgres function which will execute a NOTIFY statement
using Postgres built-in function \textit{pg\_notify}, which wraps the statement
in a Postgres function allowing to be used more easy.
diff --git a/docs/content/implementation/a-security.tex
b/docs/content/implementation/e-security.tex
similarity index 80%
rename from docs/content/implementation/a-security.tex
rename to docs/content/implementation/e-security.tex
index e1b0417..8f21423 100644
--- a/docs/content/implementation/a-security.tex
+++ b/docs/content/implementation/e-security.tex
@@ -1,11 +1,11 @@
-\subsection{Security}
+\section{Security}
-\subsubsection{Withdrawal Operation Identifier (WOPID)}
+\subsection{Withdrawal Operation Identifier (WOPID)}
\label{sec-security-wopid}
-The \textit{WOPID} is the achiles heel of the withdrawal operation and
therefore needs great care when generated. When the \textit{WOPID} becomes
somehow foreseeable, it opens the door for attackers allowing them to hijack
the withdrawal from a remote location. Therefore the \textit{WOPID} needs to
leverage high entropy sources to be generated.
+The \textit{WOPID} is the achiles heel of the withdrawal operation and
therefore needs great care when generated. When the \textit{WOPID} becomes
somehow foreseeable, it opens the door for attackers allowing them to hijack
the withdrawal from a remote location. Therefore the \textit{WOPID} needs to
leverage high entropy sources to be generated. This is achieved by using the
crypto random library of Go. The library is part of the standard library and
gains entropy through the entropy sour [...]
-\subsubsection{Authenticating at the Wallee ReST API}
+\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 MAC (message authentication code) which is built on
a version, user identifier, and a timestamp. For the creation of the MAC the
HMAC (hash based message authentication code) SHA-512 is leveraged which takes
the so called \textit{application-user-key} (which is basically just an
access-token, which the user receive [...]
@@ -24,7 +24,7 @@ The Wallee API specifies four Wallee specific headers which
are used to authenti
The resulting string must then be UTF-8 encoded according to RFC-3629
\cite{rfc3629}.
-\subsubsection{API access}
+\subsection{API access}
\textbf{Terminals API}
\label{sec-terminal-api-auth}
@@ -39,11 +39,11 @@ The Bank-Integration API is accessed by Wallets and
specified to be unauthentica
The wire gateway specifies a basic authentication scheme
\cite{taler-wire-gateway-api-authentication} as described in RFC-7617
\cite{rfc7617}. Therefore the C2EC component allows the configuration of a
username and password for the exchange. During the request of the exchange at
the wire gateway API, the credentials are checked.
-\subsubsection{Registering Providers and Terminals}
+\subsection{Registering Providers and Terminals}
\label{sec-security-registering-providers}
-A provider may want to register a new Terminal or maybe even a new provider
shall be registered for the exchange. To make this step easier for the exchange
operators, a simple cli program (command line interface) was implemented. The
cli will either ask for a password or generate an access token in case of the
terminal registration. The credentials are stored has hashes using a PBKDF
(password based key derivation function) so that even if the database leaks,
the credentials cannot be ea [...]
+A provider may want to register a new Terminal or maybe even a new provider
shall be registered for the exchange. To make this step easier for the exchange
operators, a simple cli program (command line interface) was implemented
(\autoref{sec-implementation-cli}). The cli will either ask for a password or
generate an access token in case of the terminal registration. The credentials
are stored has hashes using a PBKDF (password based key derivation function) so
that even if the database [...]
-\subsubsection{Deactivating Terminals}
+\subsection{Deactivating Terminals}
A Terminal can be stolen, hijacked or hacked by malicious actors. Therefore it
must be possible to disable a terminal immediately and no longer allow
withdrawals using this terminal. Therefore the \textit{active} flag can be set
to \textit{false} for a registered terminal. The Terminals-API which processes
withdrawals and authenticates terminals, checks that the requesting terminal is
active and is allowed to initiate withdrawals. Since the check for the
\textit{active} flag must be done [...]
diff --git a/docs/content/implementation/f-cli.tex
b/docs/content/implementation/f-cli.tex
new file mode 100644
index 0000000..87a7914
--- /dev/null
+++ b/docs/content/implementation/f-cli.tex
@@ -0,0 +1,22 @@
+\section{C2EC CLI}
+\label{sec-implementation-cli}
+
+The management of providers and terminals is not part of the thesis but since
writing and issueing SQL statements is cumbersome and error-prone a small cli
was implemented to abstract managment tasks. The cli tool was also shows the
concepts a future implementation of the provider managment can use to integrate
seamlessly with the present features. The cli can be extended with more actions
to allow the management of other providers and its terminals. Also the cli
allows to setup the simu [...]
+
+The cli was implemented to be usable and as it was out of scope of the thesis,
the focus was on the functionality and tasks needed for the thesis. This
included features to manage wallee provider and terminals and the simulation.
Additionally the tool implements commands to activate and deactivate a
terminal, which makes the task much easier than writing and executing SQL by
hand. Also it eliminates mistakes by reducing problems to bugs in the
implementation of the cli.
+
+\subsection{Adding a Wallee provider}
+
+Adding the Wallee provider is as easy as calling \textit{rp}
(register-provider). It will then ask for properties like the base url and the
credentials of the API user. Since the payto target type in case of Wallee will
always be \textit{wallee-transaction}, this is hard coded. The credentials
supplied are encrypted using argon2 and stored as hash. Like this if the
database leaks for some reason the credentials are still not easy to crack,
when no standard password was used. Since Wallee [...]
+
+\subsection{Adding a terminal}
+
+Adding a Wallee terminal can be achieved by using the \textit{rt}
(register-terminal) command. It will ask the user to enter the description of
the terminal and will then generate a 32-byte access token using Go's crypto
random library which must be supplied to the owner of the terminal through a
secure channel with the \textit{terminal-user-id} (which is just the name of
the operator and the id of the terminal separated by a dash '-')
+
+\subsection(Deactivating the terminal)
+
+To deactivate the terminal, the command \textit{dt} must be issued. It will
ask for the \textit{terminal-user-id} of the terminal and then deactivate the
specified terminal. The deactivation will be immediately and therefore helps to
increase the security by allowing immediate action, when a terminal is come to
be knwon hijacked, stolen or other fraud is detected specific to the terminal.
+
+\subsection(Setting up the Simulation)
+
+The Simulation provider and terminal allow to simulate transactions and
interactions of the terminal with the API of C2EC. Therefore the command
\textit{sim} will setup the needed provider and terminal including the
credentials of the simulation terminal, which must be saved to the operator in
order to test API using the simulation terminal.
diff --git a/docs/content/results/results.tex b/docs/content/results/results.tex
index f9a51f4..b2ebc47 100644
--- a/docs/content/results/results.tex
+++ b/docs/content/results/results.tex
@@ -1,2 +1,9 @@
\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.
+
+
+\section{Future Work}
+
+- Integrate other providers
+- Management interface for Terminals and Operators
+- Automate registration of Terminals
diff --git a/docs/pictures/database/logical_model_relations.png
b/docs/pictures/database/logical_model_relations.png
new file mode 100644
index 0000000..f35a904
Binary files /dev/null and b/docs/pictures/database/logical_model_relations.png
differ
diff --git a/docs/pictures/database/relationships.png
b/docs/pictures/database/relationships.png
index c106b39..0635b19 100644
Binary files a/docs/pictures/database/relationships.png and
b/docs/pictures/database/relationships.png differ
diff --git a/docs/pictures/database/table_terminal.png
b/docs/pictures/database/table_terminal.png
index 5b73568..1d6bb28 100644
Binary files a/docs/pictures/database/table_terminal.png and
b/docs/pictures/database/table_terminal.png differ
diff --git a/docs/pictures/database/table_terminal_provider.png
b/docs/pictures/database/table_terminal_provider.png
index 7ee2c66..bd1306e 100644
Binary files a/docs/pictures/database/table_terminal_provider.png and
b/docs/pictures/database/table_terminal_provider.png differ
diff --git a/docs/pictures/database/table_transfer.png
b/docs/pictures/database/table_transfer.png
new file mode 100644
index 0000000..e6febad
Binary files /dev/null and b/docs/pictures/database/table_transfer.png differ
diff --git a/docs/pictures/database/table_withdrawal.png
b/docs/pictures/database/table_withdrawal.png
index 3d448cc..30bbc37 100644
Binary files a/docs/pictures/database/table_withdrawal.png and
b/docs/pictures/database/table_withdrawal.png differ
diff --git a/docs/project.bib b/docs/project.bib
index 2de67f3..8b73750 100644
--- a/docs/project.bib
+++ b/docs/project.bib
@@ -99,6 +99,18 @@
howpublished =
{\url{https://app-wallee.com/en-us/doc/api/web-service#_authentication}}
}
+@article{zeit-cashback,
+ author = {Crefeld, Sven},
+ year = {2024},
+ month = {04},
+ day = {17},
+ date = {2024-04-17},
+ title = {Supermärkte zahlen immer mehr Geld an Kunden aus},
+ journal = {Zeit},
+ url =
{https://www.zeit.de/wirtschaft/2024-04/bargeld-abheben-einkauf-supermarkt-cashback},
+ urldate = {2024-05-11}
+}
+
@misc{rfc8959,
series = {Request for Comments},
number = 8959,
@@ -278,6 +290,13 @@
howpublished =
{\url{https://www.postgresql.org/docs/current/sql-listen.html}}
}
+@misc{golang-crypto-rand,
+ author = {Golang Doc},
+ title = {rand},
+ url = {https://pkg.go.dev/crypto/rand},
+ howpublished = {\url{https://pkg.go.dev/crypto/rand}}
+}
+
@misc{golang-contexts-and-structs,
author = {Jean de Klerk, Matt T. Proud},
title = {Contexts and structs},
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
index 161abf6..66496e5 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ
diff --git a/docs/thesis.tex b/docs/thesis.tex
index c83bece..70520e6 100644
--- a/docs/thesis.tex
+++ b/docs/thesis.tex
@@ -196,10 +196,12 @@
\chapter{Implementation}
\input{content/implementation/concepts}
-\input{content/implementation/database}
\input{content/implementation/a-c2ec}
\input{content/implementation/b-terminal}
-\input{content/implementation/wallet}
+\input{content/implementation/c-database}
+\input{content/implementation/d-wallet}
+\input{content/implementation/e-security}
+\input{content/implementation/f-cli}
\chapter{Results}
\input{content/results/discussion}
@@ -236,6 +238,10 @@
\lstinputlisting[style=rst,caption={C2EC API
specification}]{listings/specs/api-c2ec.txt}
\chapter{Appendix B}
+\section{Project Management}
+\input{content/appendix/project_managment}
+
+\chapter{Appendix C}
\section{Meeting notes}
\input{content/appendix/meeting_notes}
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.