commit 44c8e946064a20030f12899d71de25bc6edea65e parent 1c35155952cbac5d9f9c3203bc44fd80996ae6d1 Author: Joel-Haeberli <haebu@rubigen.ch> Date: Sat, 11 May 2024 12:22:29 +0200 chore: save commit Diffstat:
24 files changed, 285 insertions(+), 129 deletions(-)
diff --git 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 created which establishes a trust relationship between the terminal manufacturer Wallee and the \textit{Taler Exchange} through a newly created component called \textit{C2EC}. This enables a trust relationship between the \textit{Taler Exchange} and the terminal operator which allows withdrawing Taler without using cash. The liability for the digital cash is on the side of the terminal operator and therefore establishes the guarantees for the \textit{Taler Exchange}. +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 a framework allowing cashless withdrawals using GNU Taler. A reference implementation is created which establishes a trust relationship between the terminal manufacturer Wallee and the \textit{Taler Exchange} through a newly created component called \textit{C2EC}. This enables a trust relationship between the \textit{Taler Exchange} and the terminal operator which allows withdrawing Taler without using cash. The liability for the transaction is on the side of the terminal operator and therefore establishes the guarantees for the \textit{Taler Exchange}. diff --git 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 diff --git 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 successfully processed (or not). So if a transaction was successfully processed by the provider, the final state is the success case \textit{confirmed}, where the \textit{Exchange} will create a reserve and allow the withdrawal. If the attestation fails, thus the provider could not process the transaction successfully, the failure case \textit{aborted}, is reached as final state. @@ -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 third party is causing costs to the merchant, which it does not want to cover on their own and therefore charge a fee to cover their costs. For example cashback is causing a lot of fees to the merchants supporting it. + +\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 API} \cite{taler-bank-integration-api}. \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 its terminals and a terminal owns its Withdrawals. +\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 its terminals and a terminal owns its Withdrawals. \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 @@ -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 @@ -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/a-security.tex b/docs/content/implementation/a-security.tex @@ -1,49 +0,0 @@ -\subsection{Security} - -\subsubsection{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. - -\subsubsection{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 receives when creating a new API user) 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} -\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 Path: The path of the requested URL including the query string (if any) -\end{itemize} - -The resulting string must then be UTF-8 encoded according to RFC-3629 \cite{rfc3629}. - -\subsubsection{API access} - -\textbf{Terminals API} -\label{sec-terminal-api-auth} - -The terminal API is accessed by terminals and the authentication mechanism is based on a basic auth scheme as specified by RFC-7617 \cite{rfc7617} an specified in the terminals API specification \cite{taler-terminal-api}. Therefore a generated access-token used as password and a username which is generated registering the terminal using the cli explained in \autoref{sec-security-registering-providers} are leveraged. Currently the terminal id and the provider name of the requesting terminal is included in the username part of the basic auth scheme. - -\textbf{Bank-Integration API} - -The Bank-Integration API is accessed by Wallets and specified to be unauthenticated. - -\textbf{Wire-Gateway API} - -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} -\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 easily read by an attacker. - -\subsubsection{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 for each request of a terminal, the check can be centralized and is implemented as part of the authentication flow. A Wallee terminal can be deactivated using the cli mentioned in \autoref{sec-security-registering-providers}. diff --git 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 @@ -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, the credentials are formatted in the correct way and also encrypted. + +\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{provider\_id} as foreign key to its provider. The \textit{description} field can hold any information about the terminal which might be useful to the operator and help identify the device (location, device identifier, etc.). The operator will be asked for the respective values, when using the cli for the registration of the terminal. + +\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 withdrawal. The \textit{registration\_ts} indicates, when the parameters of a withdrawal were registered. The field is mainly thought for manual problem analysis and has no direct functional impact. +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\_status} and \textit{retries} are stored which allow retry behavior and help to make the system more robust. The \textit{credit\_account} is the refund payto URI which allows the refund process to be provider specific through a custom payto target type. + +\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-implementation-bank-integration-api}. By specifically listening to the withdrawal status to be changed for a \textit{WOPID} the API can directly return, when a status change is received through the withdrawals channel. + +\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 @@ -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 when reading the documentation from a hard copy. Also diagrams might be hard to decipher when reading the documentation from a hard copy, where no zooming features are available (except, of course, the reader has a magnifying glass at their hand). -\ 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 when reading the documentation from a hard copy. +\ No newline at end of file diff --git a/docs/content/implementation/wallet.tex b/docs/content/implementation/d-wallet.tex diff --git a/docs/content/implementation/database.tex b/docs/content/implementation/database.tex @@ -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/e-security.tex b/docs/content/implementation/e-security.tex @@ -0,0 +1,49 @@ +\section{Security} + +\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. 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 sources of the device running the application (in case of linux it is \textit{getrandom(2)} which takes its entropy from \textit{/dev/urandom}, according to the documentation \cite{golang-crypto-rand}). + +\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 receives when creating a new API user) 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} +\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 Path: The path of the requested URL including the query string (if any) +\end{itemize} + +The resulting string must then be UTF-8 encoded according to RFC-3629 \cite{rfc3629}. + +\subsection{API access} + +\textbf{Terminals API} +\label{sec-terminal-api-auth} + +The terminal API is accessed by terminals and the authentication mechanism is based on a basic auth scheme as specified by RFC-7617 \cite{rfc7617} an specified in the terminals API specification \cite{taler-terminal-api}. Therefore a generated access-token used as password and a username which is generated registering the terminal using the cli explained in \autoref{sec-security-registering-providers} are leveraged. Currently the terminal id and the provider name of the requesting terminal is included in the username part of the basic auth scheme. + +\textbf{Bank-Integration API} + +The Bank-Integration API is accessed by Wallets and specified to be unauthenticated. + +\textbf{Wire-Gateway API} + +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. + +\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 (\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 leaks, the credentials cannot be easily read by an attacker. + +\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 for each request of a terminal, the check can be centralized and is implemented as part of the authentication flow. A Wallee terminal can be deactivated using the cli mentioned in \autoref{sec-security-registering-providers}. diff --git a/docs/content/implementation/f-cli.tex 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 simulation terminal and provider which can be used for testing. Before commands can be executed, the user must connect the tool to the database which can be done throught the \textit{db} command. With the aim to not introduce security risks by storing configuration state of the cli, the credentials must be entered after each startup of the cli. This can be surpassed by specifying postgres specific environment variables \texttt{PGHOST}, \texttt{PGPORT}, \texttt{PGUSER} and \texttt{PGPASSWORD} but remember that these environment variables might leak database credentials to others if not cleaned properly or set for the wrong users shell. + +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 generates those access tokens for their API user, this can be assumed to be the case. + +\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 @@ -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 Binary files differ. diff --git a/docs/pictures/database/relationships.png b/docs/pictures/database/relationships.png Binary files differ. diff --git a/docs/pictures/database/table_terminal.png b/docs/pictures/database/table_terminal.png Binary files differ. diff --git a/docs/pictures/database/table_terminal_provider.png b/docs/pictures/database/table_terminal_provider.png Binary files differ. diff --git a/docs/pictures/database/table_transfer.png b/docs/pictures/database/table_transfer.png Binary files differ. diff --git a/docs/pictures/database/table_withdrawal.png b/docs/pictures/database/table_withdrawal.png Binary files differ. diff --git 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 Binary files differ. diff --git 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}
