commit f840c891ca0235637225bf5349348fe768aa048a parent 676830530256e89674419a2d1555b5483fed2c52 Author: Joel-Haeberli <haebu@rubigen.ch> Date: Sun, 2 Jun 2024 17:49:26 +0200 docs: enhance Diffstat:
22 files changed, 87 insertions(+), 42 deletions(-)
diff --git a/cli/cli.go b/cli/cli.go @@ -74,14 +74,14 @@ func main() { connstr = optionalPgConnStr } - fmt.Println("What do you want to do?") - showHelp() if connstr != "" { err := connectDbUsingString(connstr) if err != nil { - fmt.Println("error while connecting to database, using connection string from PGHOST. error:", err.Error()) + fmt.Println("error while connecting to database, using connection string from config. error:", err.Error()) } } + fmt.Println("What do you want to do?") + showHelp() for { err := dispatchCommand(read("Type command (term in brackets): ")) if err != nil { @@ -523,7 +523,9 @@ func showHelp() error { fmt.Println("setup simulation (", ACTION_SETUP_SIMULATION, ")") fmt.Println("withdrawal information by wopid (", ACTION_WITHDRAWAL_INFOMRATION, ")") fmt.Println("witdhrawal information by provider transaction id (", ACTION_WITHDRAWAL_INFOMRATION_BY_PTID, ")") - fmt.Println("connect database (", ACTION_CONNECT_DB, ")") + if DB == nil { + fmt.Println("connect database (", ACTION_CONNECT_DB, ")") + } fmt.Println("show help (", ACTION_HELP, ")") fmt.Println("quit (", ACTION_QUIT, ")") return nil diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex @@ -16,7 +16,7 @@ From the perspective of C2EC, the system looks as follows: \item The C2EC component runs the Taler Wire Gateway API that the respective Taler Exchange can retrieve fresh transactions and create reserves. This reserves are eventually withdrawn by the customer using their Taler wallet. \end{itemize} -\subsection{Withdrawal-Operation state transitions} +\subsection{Withdrawal-Operation State Transitions} \label{sec-architecture-state-transitions} The C2EC component mediates between the stakeholders of a withdrawal in order to maintain the correct state of the withdrawal. 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 confirmation 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 Exchange will create a reserve and allow the withdrawal. If the confirmation fails, indicating the provider could not process the transaction successfully, the failure case is \textit{aborted}. \textit{confirmed} and \textit{aborted} are the final states. diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex @@ -51,7 +51,7 @@ The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to w 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. -\subsection{The terminal} +\subsection{The Terminal} The terminal initiates the withdrawal leveraging an application which works as follows: diff --git a/docs/content/implementation/b-terminal.tex b/docs/content/implementation/b-terminal.tex @@ -1,15 +1,13 @@ \section{Wallee POS Terminal} -\subsection{Withdrawal flow} +\subsection{Withdrawal Flow} \label{sec-wallee-withdrawal-flow} The process (\autoref{fig-diagram-terminal-flow}) starts by first selecting the exchange and loading the configuration of the respective terminals-api. When this is successful, we will switch to the amount screen. Otherwise the withdrawal will be terminated. On the amount screen the terminal operator enters the amount to withdraw and clicks on the "withdraw" button. If the operator clicks on the abort button, the withdrawal is terminated. When the user clicks the "withdraw" button, the terminal sets up the withdrawal at the exchanges terminals api and retrieves the wopid. When this step is unsuccessful, the withdrawal operation is aborted and terminated. Otherwise the terminal navigates to the register parameters screen. -In the register parameters screen, a QR code is displayed, which must be scanned by the withdrawer using their wallet app. The Terminal starts a long polling the terminals api to be notified, when the withdrawal operation is in state 'selected' which means, the wallet has successfully registered its withdrawal parameters. In this case the terminal application changes to the authorize payment screen in which the withdrawing person must authorize the transaction using their credit card. In any other case, the withdrawal operation is aborted and terminated. When the terminals backend sends the response of authorization, it sends the terminals api the check notification which tells the terminals api, that it can verify the payment at the providers backend now. - -If this request is successful, the terminals shows a summary of the transaction and a button to leave the withdrawal activity. The wallet of the user should eventually be able to withdraw the amount authorized from the exchange. +In the register parameters screen, a QR code is displayed, which must be scanned by the withdrawer using their wallet app. When the user scanned the QR Code and the terminal gets the withdrawal operation in state 'selected' from C2EC, the wallet has successfully registered its withdrawal parameters. In this case the terminal application changes to the authorization screen in which the withdrawing person must authorize the transaction using their credit card (or another supported payment mean). In any other case, the withdrawal operation is aborted and terminated. When the terminals backend sends the response of the authorization to the terminal, it sends the Terminals API of C2EC the confirmation request. This will start the confirmation process of the withdrawal immediately. If the confirmation request is successful, the terminal shows a summary of the transaction. \begin{figure}[H] \centering @@ -20,64 +18,109 @@ If this request is successful, the terminals shows a summary of the transaction \subsection{Screens} -The Application is implemented using jetpack compose \cite{app-jetpack-compose} and each of the screens described in \autoref{sec-wallee-withdrawal-flow} is implemented as composable screen. This allows to handle the entire withdrawal flow in one single activity and therefore makes state handling easier. The state is bound to the activity and compose will make sure to rebuild the UI if values change. It also prevents illegal states and that different withdrawals interfere each other. The state is maintained in a view model as described by Android's documentation \cite{app-viewmodel}. The withdrawal activity handles the lifecycle of the view model instance and initializes the routing of the screens using Android's navigation controller as documented \cite{app-navigation}. The navigation integration of Android allows the declarative definition of the in-app routing and is defined at the creation of the withdrawal activity. +The Application is implemented using jetpack compose \cite{app-jetpack-compose} and each of the screens described in \autoref{sec-wallee-withdrawal-flow} is implemented as composable screen. This allows to handle the entire withdrawal flow in one single activity and therefore makes state handling easier. For the summary a standalone activity is used. The state is bound to the activity and compose will make sure to rebuild the UI if values change. It also prevents illegal states and that different withdrawals interfere each other. The state is maintained in a view model as described by Android's documentation \cite{app-viewmodel}. The withdrawal activity handles the lifecycle of the view model instance and initializes the routing of the screens using Android's navigation controller as documented \cite{app-navigation}. The navigation integration of Android allows the declarative definition of the in-app routing and is defined at the creation of the withdrawal activity. + +\subsubsection{Start Screen} + +When the app is started there will be two options for the user. The first option is to start a withdrawal and the second option is to go to the manage screen. + +\begin{figure}[H] + \centering + \includegraphics[width=0.7\textwidth]{pictures/wallee/0_start_screen.jpg} + \caption{Terminal: Start withdrawal or go to manage section} + \label{fig-terminal-screen-start} +\end{figure} + +\subsubsection{Manage Screen} + +There are options and special functionalities which can be configured by the terminal operator. These operations are implemented in the manage screen of the app. The app allows to execute the final balance actions which will settle all authorized transactions of this specific terminal. The test transaction was used during the development to learn how the transaction is triggered. In the newest release it won't be part of the manage screen. The operator might want to test the implementation without having a wallet at hand. This can be done by enabling the wallet simulation. It will lead to the creation of a mocked reserve public key which will not be withdrawable by a wallet. Triggering a payment using the wallet simulation will lead to temporary loss of money (it will eventually be bounced and refunded through the Exchange when the reserve is closed). However, the fees charged will be gone. The wallet simulation should therefore only be used in a test environment. The last option allows the activation of instant settlement. This means that the final balance action will be triggered after each payment authorization. This is not enabled by default, because at the time of writing this document it was not clear if executing the final balance can cause additional costs to the operator. + +\begin{figure}[H] + \centering + \includegraphics[width=0.7\textwidth]{pictures/wallee/1_manage_screen.jpg} + \caption{Terminal: Manage activities} + \label{fig-terminal-screen-manage} +\end{figure} \subsubsection{Choose Exchange Screen} -On the screen \autoref{fig-terminal-screen-choose-exchange} the user chooses the exchange to withdraw from. This allows the terminal to support withdrawals from various exchanges and therefore enhances the flexibility. When the user selected the exchange, the configuration of the exchange is loaded. This will define the currency of the withdrawal and tell the terminal where to reach the Terminals API of the C2EC server. +When a new withdrawal is started, the user chooses the exchange to withdraw from. This allows the terminal to support withdrawals from various exchanges and therefore enhances the flexibility. When the user selected the exchange, the configuration of the exchange is loaded. This will define the currency of the withdrawal and tell the terminal where to reach the Terminals API of the C2EC server. \begin{figure}[H] \centering - \includegraphics[width=0.7\textwidth]{pictures/wallee/choose_exchange_screen.png} + \includegraphics[width=0.7\textwidth]{pictures/wallee/2_choose_exchange.jpg} \caption{Terminal: Select the exchange to withdraw from} \label{fig-terminal-screen-choose-exchange} \end{figure} \subsubsection{Amount Screen} -The amount screen in \autoref{fig-terminal-screen-amount} is used to ask the user what amount they would like to withdraw. When the amount was entered and the \textit{withdraw}-button was clicked, the terminal sets up the withdrawal using the Terminal API. The Terminals API will send the \textit{WOPID} to the terminal, which allows the terminal to generate the taler withdraw URI according to \cite{taler-uri-scheme-rfc}. +The amount screen in \autoref{fig-terminal-screen-amount} is used to ask the user what amount they would like to withdraw. When the amount was entered and the \textit{withdraw}-button was clicked, the terminal sets up the withdrawal using the Terminal API. The Terminals API will send the \textit{WOPID} to the terminal, which allows the terminal to generate the taler withdraw URI according to \cite{taler-uri-scheme-rfc}. Also the fees are shown to the customer on this screen and made transparent in advance. \begin{figure}[H] \centering - \includegraphics[width=0.7\textwidth]{pictures/wallee/amount_screen.png} + \includegraphics[width=0.7\textwidth]{pictures/wallee/3_amount_valid.jpg} \caption{Terminal: Enter the desired amount to withdraw} \label{fig-terminal-screen-amount} \end{figure} +In case the withdrawal amount is invalid, the withdrawal is not possible and an error shown to the customer. + +\begin{figure}[H] + \centering + \includegraphics[width=0.7\textwidth]{pictures/wallee/4_amount_invalid.jpg} + \caption{Terminal: Fix the amount} + \label{fig-terminal-screen-amount-invalid} +\end{figure} + \subsubsection{Parameter Registration Screen} -This screen in \autoref{fig-terminal-screen-register-parameters} displays a QR code which contains the taler withdraw URI of the withdrawal. This allows the customer to scan it using their Taler Wallet app and register the parameters for the withdrawal (namely the reserve public key). The withdrawal can be aborted on the screen. This step is important to make sure, that the customer has a working Taler Wallet installed and allows them to accept the terms of service for the respective exchange, if they did not yet registered the exchange on their wallet. +After entering the amount, a QR code containing the taler withdraw URI is displayed. The customers scan it using their Taler wallet app and register the parameters for the withdrawal (namely the reserve public key). The withdrawal can be aborted on the screen. This step is important to make sure, that the customer has a working Taler wallet installed and allows them to accept the terms of service for the respective exchange if they did not yet registered the exchange on their wallet. Once this is done the authorization can be started by clicking on the \textit{authorize} button. When clicking on the \textit{abort} button the withdrawal is aborted. \begin{figure}[H] \centering - \includegraphics[width=0.7\textwidth]{pictures/wallee/register_parameters_screen.png} + \includegraphics[width=0.7\textwidth]{pictures/wallee/5_register_params.jpg} \caption{Terminal: Register withdrawal parameters} \label{fig-terminal-screen-register-parameters} \end{figure} \subsubsection{Authorization Screen} -The authorization screen will use Wallee's \textit{Android Till SDK} \cite{wallee-till-sdk} to authorize the amount at the Wallee backend. The response handler of the SDK will delegate the response to the implementation of the terminal, which allows triggering the confirmation of the payment by C2EC using the Terminals API. When the authorization process is not started and the transaction therefore is created at the backend system of Wallee, the screen \autoref{fig-terminal-screen-authorizing} will be displayed. This signals the user, that the payment authorization must still be done and is about to be started. The user can abort the transaction at this point. +The authorization uses the \textit{Android Till SDK} \cite{wallee-till-sdk} to authorize the amount at the Wallee backend. It covers reading and verifiying the payment mean of the customer. The response handler of the SDK will delegate the response to the implementation of the terminal, which allows triggering the confirmation request using the Terminals API of C2EC. When the authorization process is not started and the transaction therefore is created at the backend system of Wallee, the screen \autoref{fig-terminal-screen-authorizing} will be displayed. This signals the user, that the payment authorization must still be done and is about to be started. The user can abort the transaction at this point. \begin{figure}[H] \centering - \includegraphics[width=0.7\textwidth]{pictures/wallee/authorize_transaction_screen_1.png} - \caption{Terminal: Waiting to start the authorization of the Android Till SDK} + \includegraphics[width=0.7\textwidth]{pictures/wallee/6_authorize_screen.jpg} + \caption{Terminal: Authorization using the Android Till SDK} \label{fig-terminal-screen-authorizing} \end{figure} -When the transaction was processed successfully, the summary of the transaction will be displayed on this screen as can be seen in \autoref{fig-terminal-screen-authorized}. +\subsubsection{Summary Screen} + +When the transaction was processed a summary of the transaction is displayed to the customer. \begin{figure}[H] \centering - \includegraphics[width=0.7\textwidth]{pictures/wallee/authorize_transaction_screen_2.png} + \includegraphics[width=0.7\textwidth]{pictures/wallee/8_authorized.jpg} \caption{Terminal: Payment authorized} \label{fig-terminal-screen-authorized} \end{figure} +\subsubsection{Failure Screen} + +To give the customer a feedback when anything goes wrong or when the withdrawal is aborted, the terminal will always show the rudimentary abort screen. This gives the users feedback what happened. What can go wrong and how the terminal acts upon these failures is described in \autoref{sec-implementation-abort-handling}. + +\begin{figure}[H] + \centering + \includegraphics[width=0.7\textwidth]{pictures/wallee/7_abort.jpg} + \caption{Terminal: Payment authorized} + \label{fig-terminal-screen-abort} +\end{figure} + \subsection{Abort Handling} +\label{sec-implementation-abort-handling} -During the flow various steps can fail or lead to the abort of the withdrawal. These edge cases must be considered and handled the right way. Generally we can split the abort handling on the terminal side into two different phases. The implementation of the Wallee POS Terminal follows a strict \textit{abort on failure} strategy. This means that if anything goes wrong the withdrawal is aborted and must be started again. Generally the abort handling strategy is to abort the withdrawal when in doubt and values security (of the money) over user-experience. The idea behind this strategy is, that even when a nice user-experience is implemented, nobody will use the technology if security of the money cannot be guaranteed +During the flow various steps can fail or lead to the abort of the withdrawal. These edge cases must be considered and handled the right way. Generally we can split the abort handling on the terminal side into two different phases. The implementation of the Wallee POS Terminal follows a strict \textit{abort on failure} strategy. This means that if anything goes wrong the withdrawal is aborted and a new withdrawal might be started. Generally the abort handling strategy is to abort the withdrawal when in doubt and values security (of the money) over the user-experience. The idea behind this strategy is that even when a nice user-experience is implemented, nobody will operate or use a withdrawal process if security of the money cannot be guaranteed. \subsubsection{Abort before authorization} @@ -95,7 +138,7 @@ Depending on the operator of the Taler Exchange it might be possible to somehow \subsection{Fulfilling Transactions} -To achieve finality and real-time behaviour of the withdrawal flow, the transaction must be forcefully transitioned to the \textit{fulfill} state in the Wallee backend. For this reason, the payments are not only authorized but also automatically completed in the background. After the successful completion, the payment can be directly settled and with this guarantee the finality by executing the final balance. +To achieve finality and real-time behaviour of the withdrawal flow, the transaction must be forcefully transitioned to the \textit{fulfill} state in the Wallee backend. For this reason, the payments are not only authorized but also automatically completed in the background. After the successful completion, the payment can be directly settled and with this guarantee the finality property. If the completion fails, the withdrawal will be aborted. % TODO Wallee Feedback einbauen \newpage \ No newline at end of file diff --git a/docs/content/implementation/d-security.tex b/docs/content/implementation/d-security.tex @@ -4,17 +4,17 @@ 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} +\subsubsection{EAV Abusing WOPID} The WOPID is used to link a reserve public key to a withdrawal operation. Since the registration is done through an API, an attacker could try to be first and register its own reserve public key before the customer. When the WOPID is somehow precomputable, an attacker could steal the money by registering their own reserve public key before the customer. This threat is mitigated by the request of the wallet resulting in a conflict response code when trying to add a reserve public key to an already registered withdrawal operation. The customer will see this error and not authorize the transaction and instead abort the withdrawal. Further a WOPID can be abused triggering a confirmation or an abort request at the Terminals API or an abort request at the Bank-Integration API. The confirmation or abort from the side of the terminal are mitigated through the authentication of the terminals. When the eavesdropping adversary (EAV) \cite{katz2020introduction} can somehow access the communication between a terminal and C2EC, the WOPID cannot be abused without also breaking the terminals credentials. What if the attacker decides to use the unauthenticated Bank-Integration API the wallet would normally use? The specification does not require some proof that the requester is the wallet. This could lead to tampering of the withdrawals in the time window of the confirmation of the payment. The problem could be mitigated by sending a signed token in the request (the request already is a POST request). The wallet could use its reserve private key to sign the token. The Bank-Integration API could then verify the token using the reserve public key assigned to the withdrawal operation. It is understandable that the risk is accepted, since a potential adversary would need to be sophisticated (needs to redirect requests of the wallet and read WOPID from the request). What about wallets run by people in countries which are politically not as stable as Switzerland and censorship is a problem? Maybe it's a good idea to add some mean of authentication to at least the abort endpoint of the Bank-Integration API. On the other hand the attacker needs access to the victims phone anyway and could possibly also use the keys. -\subsubsection{Trying to withdraw money without paying} +\subsubsection{Trying To Withdraw Money Without Paying} This case is possible, when an attacker can trick the C2EC to have confirmed withdrawals in its withdrawal table, without having a real confirmation of the payment service provider. This means the attacker can steal money from the exchange. For this an attacker would need to have the possibility to somehow trick the confirmation process of C2EC to issue confirmation requestes against a backend controlled by the attacker. This backend would then confirm the withdrawal. This will lead to the creation of the reserve on the side of the Exchange. -\subsubsection{Developer issues} +\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 the transaction is not guaranteed to be final by the payment system provider. Otherwise the property of the guarantees concerning the finality is harmed and the system no longer secure (in terms of money). When adding new integrations, this section of the code needs great care and review before going to production. @@ -27,11 +27,11 @@ The \textit{WOPID} needs great care when generated. When the \textit{WOPID} beco The database is very important as it decides wether to allow a withdrawal or not and it manages terminals and providers which hold sensitive credentials. Therefore two important aspects need to be considered. -\subsubsection{Storing credentials} +\subsubsection{Storing Credentials} Even if a database leak occurs, it shall be very hard for the attacker to access the API using the credentials stored in the database. This is why credentials are stored using the PBKDF \textit{argon2} \cite{password-competition-argon2}. \textit{Argon2} is the winner of the password hashing competition initiated by the cryptographer Jean-Philippe Aumasson \cite{password-competition-argon2}. It is a widely adopted best practice approach for hashing passwords. Storing the hash of the credentials makes abusing stolen credentials very hard and therefore prevents the abuse of credentials gathered through a database leak. The CLI described in \autoref{sec-implementation-cli} implements operations which will register providers and terminals also hashing the credentials using \textit{argon2}. -\subsubsection{Access data through correct user} +\subsubsection{Access Data Through Correct User} \label{sec-security-db-users} The database user executing a database query must have enough rights to execute its duties but not more. Therefore different database users are created for different tasks within the database. The described setup and installation process in \autoref{sec-deployment} will automatically generate the users and grant them the correct rights, when the respective variables are specified. @@ -53,10 +53,10 @@ The database user executing a database query must have enough rights to execute \end{tabularx} \end{table} -\subsection{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 message authentication code (MAC) which is built on a version, user identifier, and a timestamp. For the creation of the MAC the hash based message authentication code (HMAC) SHA-512 is leveraged which takes 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: +The Wallee API specifies four Wallee specific headers which are used to authenticate against the API. It defines its own authentication standard and flow. The flow builds on a message authentication code (MAC) which is built on a version, user identifier, and a timestamp. For the creation of the MAC the hash based message authentication code (HMAC) SHA-512 is leveraged which takes \textit{application-user-key} (which is just an access-token the user receives when creating a new API user in the management backend of Wallee) as key and the above mentioned properties plus information about the requested http method and the exactly requested path (including request parameters) as message \cite{wallee-api-authentication}. The format of the message is specified like: \begin{center} \texttt{Version|User-Id|Unix-Timestamp|Http-Method|Path} @@ -83,7 +83,7 @@ In order for Wallee to successfully authorize the user's requests, the API user These rights can be assigned on Wallee's management interface by creating a role and assigning the rights to it. The role must then be added to the API user. The assignment of the roles must be done for the space context (Three different contexts are available. The relevant context is the space context, since requests are scoped to a space). -\subsection{API access} +\subsection{API Access} \textbf{Terminals API} \label{sec-terminal-api-auth} @@ -98,7 +98,7 @@ 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. -\subsection{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 (\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. diff --git a/docs/content/implementation/e-cli.tex b/docs/content/implementation/e-cli.tex @@ -5,18 +5,18 @@ The management of providers and terminals is not part of the thesis but since wr 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 and to allow an easy management of the terminals. 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. -\subsection{Adding a Wallee provider} +\subsection{Adding 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 (generated by Wallee). Since the payto target type in case of Wallee will always be \textit{wallee-transaction}, this is hard coded. The credentials supplied are hashed using argon2 \cite{rfc9106}. If the database leaks for some reason, the passwords cannot be abused easily. -\subsection{Adding a terminal} +\subsection{Adding Wallee 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} +\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. To detect suspicious activity in production appropriate montioring tools could be installed to automatically trigger alarms. -\subsection{Setting up the Simulation} +\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 and supplied to the operator through a secure channel. These credentials allow to test the Terminals API using the simulation terminal. The simulation client will not be available in productive environments to reduce the attack surface due to unnecessaty features. diff --git a/docs/content/implementation/f-deployment.tex b/docs/content/implementation/f-deployment.tex @@ -26,20 +26,20 @@ For the deployment of the Wallee POS Terminal app, the following steps are neces Once the steps from the preparation were succesfully done, the \textit{setup}-script can now be run. It will initiate the database and setup the users (as described in \autoref{sec-security-db-users}) with the correct permissions. It will further generate the executables for C2EC, the cli and the simulation inside the specified \texttt{C2EC\_HOME}. The setup script contains sensitive credentials and shall be deleted after using it. Maybe it can be stored in a save location like a password manager. Like this it will be still available in the future but will not lie around on the filesystem unhashed. -\subsubsection{Setting up Wallee as provider} +\subsubsection{Setting Up Wallee As Provider} 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} +\subsubsection{Registering 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} +\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} +\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. @@ -47,6 +47,6 @@ When the simulation shall be installed the \textit{prod}-flag in the C2EC config 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} +\subsection{Migration And Releases} When a new version of the system shall be installed, the new executable can be built by issueing \texttt{make build}. After migrating the database using \texttt{make migrate} the newly built executable can be started. diff --git a/docs/pictures/wallee/0_start_screen.jpg b/docs/pictures/wallee/0_start_screen.jpg Binary files differ. diff --git a/docs/pictures/wallee/1_manage_screen.jpg b/docs/pictures/wallee/1_manage_screen.jpg Binary files differ. diff --git a/docs/pictures/wallee/2_choose_exchange.jpg b/docs/pictures/wallee/2_choose_exchange.jpg Binary files differ. diff --git a/docs/pictures/wallee/3_amount_valid.jpg b/docs/pictures/wallee/3_amount_valid.jpg Binary files differ. diff --git a/docs/pictures/wallee/4_amount_invalid.jpg b/docs/pictures/wallee/4_amount_invalid.jpg Binary files differ. diff --git a/docs/pictures/wallee/5_register_params.jpg b/docs/pictures/wallee/5_register_params.jpg Binary files differ. diff --git a/docs/pictures/wallee/6_authorize_screen.jpg b/docs/pictures/wallee/6_authorize_screen.jpg Binary files differ. diff --git a/docs/pictures/wallee/7_abort.jpg b/docs/pictures/wallee/7_abort.jpg Binary files differ. diff --git a/docs/pictures/wallee/8_authorized.jpg b/docs/pictures/wallee/8_authorized.jpg Binary files differ. diff --git a/docs/pictures/wallee/amount_screen.png b/docs/pictures/wallee/amount_screen.png Binary files differ. diff --git a/docs/pictures/wallee/authorize_transaction_screen_1.png b/docs/pictures/wallee/authorize_transaction_screen_1.png Binary files differ. diff --git a/docs/pictures/wallee/authorize_transaction_screen_2.png b/docs/pictures/wallee/authorize_transaction_screen_2.png Binary files differ. diff --git a/docs/pictures/wallee/choose_exchange_screen.png b/docs/pictures/wallee/choose_exchange_screen.png Binary files differ. diff --git a/docs/pictures/wallee/register_parameters_screen.png b/docs/pictures/wallee/register_parameters_screen.png Binary files differ. diff --git a/docs/thesis.pdf b/docs/thesis.pdf Binary files differ.
