commit a5a3f4c27761a3551986a5fe265b221259b32995
parent 4afb7375e791ad8c1a43ab35af69251ffea78897
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Fri, 31 May 2024 14:53:53 +0200
docs: enhance testing and deployment sections
Diffstat:
7 files changed, 27 insertions(+), 13 deletions(-)
diff --git a/docs/content/implementation/a-fees.tex b/docs/content/implementation/a-fees.tex
@@ -12,7 +12,7 @@ The provider advertises the fees beforehand. The withdrawing terminal adds the f
\subsubsection{Model 3 - Payment Service Provider and Exchange Operator Fees}
-The combination of the first two models. The Exchange operator decides to add fees to withdrawals and the payment service provider adds fees as well. The model must combine the checks of model one and two.
+The combination of the first two models. The Exchange operator decides to add fees to withdrawals and the payment service provider adds fees as well. The implementation must combine the checks of model one and two.
\subsubsection{Model 4 - Payment Service Provider "Late Fees"}
diff --git a/docs/content/implementation/c-database.tex b/docs/content/implementation/c-database.tex
@@ -15,7 +15,7 @@ For the C2EC component the schema c2ec is created. It holds tables to store the
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 confirmation endpoint. Namely the base url and the credentials to authenticate the confirmation 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 hashed.
-\begin{figure}[h]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
\caption{Terminal Provider Table}
@@ -26,7 +26,7 @@ The \textit{terminal provider} table holds information about the provider. It co
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 hashed 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]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
\caption{Terminal Table}
@@ -38,7 +38,7 @@ Each Terminal must register before withdrawals are possible using the terminal.
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]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
\caption{Withdrawal Table}
@@ -49,7 +49,7 @@ The \textit{withdrawal\_status} holds the current state of the withdrawal and is
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]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_transfer.png}
\caption{Transfer Table}
@@ -60,7 +60,7 @@ The transfer table is maintained through the transfer endpoint as described in \
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]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/relationships.png}
\caption{Relationships of the entities.}
diff --git a/docs/content/implementation/d-security.tex b/docs/content/implementation/d-security.tex
@@ -2,13 +2,13 @@
\subsection{General Security Considerations}
-To review and validate the threat model, two cases were reviewed. The first mirrors the easiest attack (EAV eavesdropping and abusing WOPID). The second case reviews where the most harm can be possibly be done to the system.
+To review and validate the security of the design two cases were reviewed. The first mirrors the easiest attack (EAV eavesdropping and trying to abuse WOPID). The second case reviews where the most harm can possibly be done to the system.
\subsubsection{EAV abusing WOPID}
-A WOPID can be abused triggering a confirmation or an abort request at the Terminals API or an abort request at the Bank-Integration API.
+The WOPID is used to link a reserve public key to a withdrawal operation. Since the registration is done through an API, an attacker could try to be first and register its own reserve public key before the customer. When the WOPID is somehow precomputable, an attacker could steal the money by registering their own reserve public key before the customer. This threat is mitigated by the request of the wallet resulting in a conflict response code when trying to add a reserve public key to an already registered withdrawal operation. The customer will see this error and not authorize the transaction and instead abort the withdrawal.
-The confirmation or abort from the side of the terminal are mitigated through the authentication of the terminals. When the eavesdropping adversary (EAV) \cite{katz2020introduction} can somehow access the communication between a terminal and C2EC, the WOPID cannot be abused without also breaking the terminals credentials. What if the attacker decides to use the unauthenticated Bank-Integration API the wallet would normally use? The specification does not require some proof that the requester is the wallet. This could lead to tampering of the withdrawals in the time window of the confirmation of the payment. The problem could be mitigated by sending a signed token in the request (the request already is a POST request). The wallet could use its reserve private key to sign the token. The Bank-Integration API could then verify the token using the reserve public key assigned to the withdrawal operation. It is understandable that the risk is accepted, since a potential adversary would need to be sophisticated (needs to redirect requests of the wallet and read WOPID from the request). What about wallets run by people in countries which are politically not as stable as Switzerland and censorship is a problem? Maybe it's a good idea to add some mean of authentication to at least the abort endpoint of the Bank-Integration API. On the other hand the attacker needs access to the victims phone anyway and could possibly also use the keys.
+Further a WOPID can be abused triggering a confirmation or an abort request at the Terminals API or an abort request at the Bank-Integration API. The confirmation or abort from the side of the terminal are mitigated through the authentication of the terminals. When the eavesdropping adversary (EAV) \cite{katz2020introduction} can somehow access the communication between a terminal and C2EC, the WOPID cannot be abused without also breaking the terminals credentials. What if the attacker decides to use the unauthenticated Bank-Integration API the wallet would normally use? The specification does not require some proof that the requester is the wallet. This could lead to tampering of the withdrawals in the time window of the confirmation of the payment. The problem could be mitigated by sending a signed token in the request (the request already is a POST request). The wallet could use its reserve private key to sign the token. The Bank-Integration API could then verify the token using the reserve public key assigned to the withdrawal operation. It is understandable that the risk is accepted, since a potential adversary would need to be sophisticated (needs to redirect requests of the wallet and read WOPID from the request). What about wallets run by people in countries which are politically not as stable as Switzerland and censorship is a problem? Maybe it's a good idea to add some mean of authentication to at least the abort endpoint of the Bank-Integration API. On the other hand the attacker needs access to the victims phone anyway and could possibly also use the keys.
\subsubsection{Trying to withdraw money without paying}
@@ -16,7 +16,7 @@ This case is possible, when an attacker can trick the C2EC to have confirmed wit
\subsubsection{Developer issues}
-Another problem could be developers introducing confirmation bugs. The confirmation process of a transaction must be considered as the holy grail from the perspective of the developers. If they do not take biggest care implementing the confirmation process, this could lead to loss of money on the side of the Exchange operator. The program should strictly disallow withdrawals, if it is not 100 percent guaranteed by the payment system provider that the state a transaction is in means that the payment effectively went through and is settled. Otherwise the finality is harmed and the system no longer secure.
+Another problem could be developers introducing confirmation bugs. The confirmation process of a transaction must be considered as the holy grail from the perspective of the developers. If they do not take biggest care implementing the confirmation process, this could lead to loss of money on the side of the Exchange operator. The program should strictly disallow withdrawals, if the transaction is not guaranteed to be final by the payment system provider. Otherwise the finality is harmed and the system no longer secure. When adding new integrations, this section of the code needs great care and review before going to production.
\subsection{Withdrawal Operation Identifier (WOPID)}
\label{sec-security-wopid}
diff --git a/docs/content/implementation/e-testing.tex b/docs/content/implementation/e-testing.tex
@@ -1,7 +1,7 @@
\section{Testing}
-Since the program leverages concurrency and operates in a distributed way, it is difficult to test besides unit testing. Therefore a simulation client and simulation program was implemented which allows to test the C2EC component while simulating the different involved parties like the terminal, wallet and the providers backend system. This setup allows to test and therefore proof the functionality of the system.
+Since the program leverages concurrency and parallizes work a simulation client and simulation program was implemented. The simulation allows to test the C2EC component while simulating the different involved parties like the terminal, wallet and the providers backend system. This setup allows to test and proof the functionality of the core functionality.
The Simulation can be used for regression testing and therefore can be run before introducing new features in order to check, that existing functionality will not be broken.
-Besides the automated tests, using the above mentioned simulation, unit tests were implemented for parsing, formatting and encoding functions. Additionally nanual test were fulfilled to ensure the system behaves correctly and without problems. To test the wire-gateway API, the \textit{taler-exchange-wire-gateway-client} facility was used supplied by GNU Taler to verify the correct functioning of the API.
+Besides the automated tests, using the above mentioned simulation, unit tests were implemented for parsing, formatting and encoding functions. Additionally manual test were fulfilled to ensure the system behaves correctly. To test the wire-gateway API, the \textit{taler-exchange-wire-gateway-client} \cite{} facility was used supplied by GNU Taler to verify the correct functioning of the API.
diff --git a/docs/content/implementation/f-deployment.tex b/docs/content/implementation/f-deployment.tex
@@ -30,15 +30,22 @@ Once the steps from the preparation were succesfully done, the \textit{setup}-sc
To allow withdrawals using Wallee as provider, the correct access tokens must be created at the Wallee backend. Therefore a new application user must be created and the \textit{application user key} must be saved to a password manager. Then Wallee must be registered at C2EC using the cli (described in \autoref{sec-implementation-cli}) and the \textit{rp} command. There the space-id, user-id of the application user and the \textit{application user key} must be provided. The cli will register the provider using these values.
+\subsubsection{Registering a Wallee terminal}
+\label{sec-implementation-deployment-wallee-terminal}
+
When Wallee was registered as provider, one must register a terminal to allow access to the Taler Terminals API of C2EC. Therefore also the cli with its \textit{rt} command can be used. It will generate the terminal user id and the access token. Both these values should be stored in a save location like the password manager
+\subsubsection{Setting up the terminal}
+
+To setup the Wallee terminal, the Android app must be configured and built with the credentials gained by the terminal registration process described in \autoref{sec-implementation-deployment-wallee-terminal}. The resulting APK must be submitted to Wallee who will install the APK to the desired terminal.
+
\subsubsection{Setting up the simulation}
When the simulation shall be installed the \textit{prod}-flag in the C2EC configuration should be disabled, in order to allow the simulation provider to be registered at startup. This is a security measure, that testing facilities are not reachable in productive use of the system.
\subsection{Deploy}
-When the provider and the terminal was successfully registered, the configuration located inside the \texttt{C2EC\_HOME} must be adjusted to the correct values. Once this is done, the C2EC process can be started using \texttt{./c2ec [PATH-TO-CONFIGFILE]}.
+When the provider and the terminal was successfully registered, the configuration located inside the \texttt{C2EC\_HOME} must be adjusted to the correct values. Once this is done, the C2EC process can be started using \texttt{./c2ec -c [PATH-TO-CONFIGFILE]}.
\subsection{Migration and releases}
diff --git a/docs/project.bib b/docs/project.bib
@@ -301,6 +301,13 @@
abstract = {This document defines the 'taler' Uniform Resource Identifier (URI) scheme for triggering interactions with a GNU Taler wallet. This URI scheme allows applications to trigger interactions with the GNU Taler wallet, such as withdrawing money, making payments, receiving refunds and restoring a wallet from a backup. Applications may receive such URIs in many ways (including via NFC, QR codes, Web links or messaging applications), or might generate them internally to interact with a wallet. By having a Taler wallet handle the respective URIs, applications can integrate Taler payments without having to support the Taler protocol directly. Furthermore, by passing control to a Taler wallet process, the wallet's database with its financial data might be better protected from application failures.},
}
+@misc{taler-exchange-wire-gateway-client,
+ author = {Taler},
+ title = {taler-exchange-wire-gateway-client},
+ url = { https://docs.taler.net/manpages/taler-exchange-wire-gateway-client.1.html},
+ howpublished = {\url{https://docs.taler.net/manpages/taler-exchange-wire-gateway-client.1.html}}
+}
+
@misc{postgres-notify,
author = {PostgreSQL},
title = {NOTIFY},
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
