commit 01e0c4c299617ceb9224430a7a1c5570dc92727e parent b44d71d4ec23b1349a394f5321584b5bf1ce7e00 Author: Joel-Haeberli <haebu@rubigen.ch> Date: Wed, 6 Mar 2024 07:37:29 +0100 docs: fix docs Diffstat:
20 files changed, 348 insertions(+), 226 deletions(-)
diff --git a/docs/content/abstract.tex b/docs/content/abstract.tex @@ -2,6 +2,6 @@ In order to buy Taler, the Taler Exchange needs guarantees to legally secure the 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 establishes a trust relationship between the terminal manufacturer Wallee -and the Taler Exchange through a newly created component called 'cashless2ecash'. This enables a trust relationship +and the Taler Exchange through a newly created component called \textit{nonce2ecash}. This enables a trust relationship between the Taler Exchange and the terminal operator which allows withdrawing Taler without using cash. The liability for the money is on the side of the terminal operator and therefore establishes the guarantees for the Taler Exchange. diff --git a/docs/content/appendix/meeting_notes.tex b/docs/content/appendix/meeting_notes.tex @@ -87,28 +87,52 @@ \begin{itemize} \item Task description \item Deeper understanding of the topic established? - \item I contacted Florian Jung (alias Windfisch) and we bespoke his work on cash2ecash. - \begin{itemize} - \item Where do we draw the line (scope)? - \item Florian wants to hand in a "Förderantrag" to integrate the scan-before-withdraw feature into Taler Wallet. - \item Can I for the sake of my bachelor rely on his work, he is planning to do (therefore only adhere to a specified contract)? - \end{itemize} + \item I contacted Florian Jung (alias Windfisch) and we bespoke his work on cash2ecash. \end{itemize} \textbf{Questions} \begin{itemize} - \item Repository of Wallee Application will be different than 'cashless2ecash' (bfh gitlab)? - \item Wallee: Master Password? (Password received by Ben) + \item Repository of Wallee Application will be different than 'cashless2ecash'? No + \item Wallee: Master Password? Password received by Ben \item Wallee: Which SDK to use? Till-SDK (API to Wallee-Backend) + \item How do we want to handle different currencies? How about currencies like Bitcoin? Currency is determined by the currency of the exchange. +\end{itemize} + +\textbf{Action points} +\begin{itemize} + \item +\end{itemize} + +\textbf{Decisions} +\begin{itemize} + \item +\end{itemize} + +\subsection*{06.03.2024} + +\textbf{Participants} + +\begin{itemize} + \item Fehrensen Benjamin + \item Grothoff Christian + \item H\"aberli Joel +\end{itemize} + +\textbf{Topics} +\begin{itemize} + \item API Spec +\end{itemize} + +\textbf{Questions} +\begin{itemize} + \item How can I create a reserve from the mapping table? \item Taler / Wallee : Which nonce to use? How to generate the nonce? Is there a preferred kind to generate nonces within taler? \item Do we add a maximal limit amount for a withdrawal on the side of the Taler Exchange? - \item How do we want to handle different currencies? How about currencies like Bitcoin? - \item How can I create a reserve from the mapping table? \end{itemize} \textbf{Action points} \begin{itemize} - \item + \item \end{itemize} \textbf{Decisions} diff --git a/docs/content/architecture/bigpicture.tex b/docs/content/architecture/bigpicture.tex @@ -1,81 +0,0 @@ -\section*{Big Picture} - -\subsection*{Components} - -\begin{figure}[h] - \centering - \includegraphics[width=0.7\textwidth]{pictures/diagrams/component.png} - \caption{Diagram of included components} - \label{fig:diagram-all-components} -\end{figure} - -The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card owned by the user, two systems are involved and within each system two components are required to fulfill the task. We have the Taler system which represents the ecosystem for the Taler payment system with the Taler Wallet and the Taler Exchange involved in the withdrawal of Taler coins. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process. - -\begin{figure}[h] - \centering - \includegraphics[width=0.7\textwidth]{pictures/diagrams/nonce2ecash.png} - \caption{Diagram of high level flow} - \label{fig:diagram-all-sequence} -\end{figure} - -The diagram in \autoref*{fig:diagram-sequence} shows the high level flow to withdraw Taler using the credit card terminal. It shows when the components of \autoref*{fig:diagram-components} interact with each other. It shows the implementation of the \textbf{nonce2ecash} flow. Terminal, Wallet and Exchange are linked leveraging a nonce initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a public key. - -\subsection*{The three parts} - -The process requires three parties. The Terminal, the Wallet and the Exchange must therefore interact with each other. - -\subsubsection*{The Terminal} - -The Terminal initiates the withdrawal leveraging an application which works as follows: - -\begin{enumerate} - \item At startup of the application, the terminal loads the Exchange configuration - \item When a user wishes to do a withdrawal, the owner of the terminal opens the application and initiates a new withdrawal. - \begin{enumerate} - \item Application creates a nonce - \item The application starts long polling at the Exchange and awaits the establishment of the nonce (by the Exchange). - \item Nonce is packed into a QR code (with Exchange and amount) - \item QR code is displayed - \end{enumerate} - \item The user now scans the QR Code using his wallet. - \item The application receives the establishment notification of the Exchange. - \item The owner of the terminal enters the amount the user likes to withdraw. - \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 and pays using his Credit Card. - \item The Terminal executes the payment and presents the result to the user. -\end{enumerate} - -\subsubsection*{The Exchange} - -The Exchange manages the withdrawal using a third party and seeks guarantees of the third party in order to provide a reserve containing Taler which can be withdrawn by the wallet. - -\begin{enumerate} - \item The Exchange retrieves a long polling request for a nonce (from the Terminal). - \item The Exchange creates a mapping entry with the nonce and an empty reserve public key field - \item The Exchange retrieves a request including a nonce and a reserve public key. - \item The Exchange validates the request and adds the key to the mapping. This establishes the nonce to reserve public key mapping. - \item The Exchange ends the long polling from the terminal (by sending back the reserve public key). - \item The Exchange receives payment notification of the terminal. - \item The Exchange verifies the notification by asking the terminal backend for confirmation. - \item The Exchange, upon successfully checking the notification, creates the reserve with the verified amount -\end{enumerate} - -\subsubsection*{The Wallet} - -The Wallet must attest its presence to the terminal by registering a nonce and belonging reserve public key which will hold the Taler that can eventually be withdrawn by the wallet. - -\begin{enumerate} - \item The Wallet scans the QR Code (nonce, Exchange information) on the Terminal - \item It creates a reserve key pair - \item The Wallet sends the reserve public key and the scanned nonce to the Exchange - \item The Wallet can withdraw money from the created reserve. -\end{enumerate} - -\subsection*{Taler system} -\subsubsection*{Taler Wallet} -\subsubsection*{Taler Exchange} - -\subsection*{Terminal system} -\subsubsection*{Terminal} -\subsubsection*{Terminal Manufacturer Backend} -\subsubsection*{Terminal Fulfillment } -\ No newline at end of file diff --git a/docs/content/architecture/cashless2ecash.tex b/docs/content/architecture/cashless2ecash.tex @@ -1,5 +0,0 @@ -\section*{nonce2ecash} - -\subsection*{Model} - -\subsubsection*{Database} diff --git a/docs/content/architecture/nonce2ecash.tex b/docs/content/architecture/nonce2ecash.tex @@ -0,0 +1,43 @@ +\section*{nonce2ecash} + +\subsection*{REST API} + +The API of the nonce2ecash component mirrors the flow from the creation of a nonce2ecash mapping to the creation of the reserve. Therefore three endpoints are implemented. + +An openapi specification of the API in yaml format can be found in \autoref*{appendix-api-spec}. + +\subsubsection*{Withdrawal Registration} +\label{section-api-withdrawal-registration} + +With the \textit{withdrawal-registration} endpoint a nonce is registered at the nonce2ecash component of the Exchange. The \textit{N2CWithdrawalRequest} contains not only the nonce but also a reserve public key generated by the Wallet, the amount to withdraw and the provider type (e.g. \textit{WALLEE}). The provider type shall make the nonce2ecash component provider agnostic. Like this other providers can be added in the future. + +\subsubsection*{Withdrawal Processing} + +With the \textit{withdrawal-processing} endpoint, the provider can notify the Exchange about the payment. Therefore the provider sends a \textit{N2CPaymentNotification} message to the API. The message contains the nonce to identify which withdrawal is processed, a provider specific transaction identifier which allows the nonce2ecash component to verify the payment at the providers backend and a flag indicating the success or failure of the payment. + +\subsubsection*{Withdrawal Status} + +With the \textit{withdrawal-status} endpoint, the status of a mapping can be retrieved. With a parameter called listenForStatus the consumer can initiate the a long-polling which will only end if the mapping comes to the requested state. + +\subsubsection*{Database} + +The database of the nonce2ecash component is small and only has one table and two enumerations, which are presented as separate tables themself. + +\textbf{n2c\_status} + +The \textit{n2c\_status} table represents the enumeration of all possible states a mapping of a nonce to a reserve public key can be in. + +\textbf{n2c\_provider\_type} + +The \textit{n2c\_provider\_type} table represents the enumeration of all accepted providers for the nonce2ecash process. For this thesis, the only supported provider will be \textit{WALLEE}. In the future more providers might be implemented. + +\textbf{n2c\_nonce\_reservepubkey} + +The \textit{n2c\_nonce\_reservepubkey} table represents the mapping of a nonce to a reserve public key. The table holds the nonce, the reserve public key, the \textit{n2c\_status}, the \textit{n2c\_provider\_type} and a timestamp which represents the time of registration of the withdrawal (The time when the \autoref*{section-api-withdrawal-registration}). + +\begin{figure}[h] + \centering + \includegraphics[width=0.7\textwidth]{pictures/diagrams/db_nonce2ecash_erd.png} + \caption{Entity Relation Diagram of the nonce2ecash component} + \label{fig-diagram-erd-nonce2ecash} +\end{figure} diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex @@ -0,0 +1,80 @@ +\section*{Overview} + +\subsection*{Components} + +\begin{figure}[h] + \centering + \includegraphics[width=0.7\textwidth]{pictures/diagrams/component.png} + \caption{Diagram of included components} + \label{fig-diagram-all-components} +\end{figure} + +The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card owned by the user, two systems are involved and within each system two components are required to fulfill the task. We have the Taler system which represents the ecosystem for the Taler payment system with the Taler Wallet and the Taler Exchange involved in the withdrawal of Taler coins. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process. + +\begin{figure}[h] + \centering + \includegraphics[width=0.7\textwidth]{pictures/diagrams/nonce2ecash.png} + \caption{Diagram of high level flow} + \label{fig-diagram-all-sequence} +\end{figure} + +The diagram in \autoref*{fig-diagram-all-sequence} shows the high level flow to withdraw Taler using the credit card terminal. It shows when the components of \autoref*{fig-diagram-all-components} interact with each other. It shows the implementation of the \textbf{nonce2ecash} flow. Terminal, Wallet and Exchange are linked leveraging a nonce initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a public key. + +\subsection*{The three parts} + +The process requires three parties. The Terminal, the Wallet and the Exchange must therefore interact with each other. + +\subsubsection*{The Terminal} + +The Terminal initiates the withdrawal leveraging an application which works as follows: + +\begin{enumerate} + \item At startup of the application, the terminal loads the Exchange configuration + \item When a user wishes to do a withdrawal, the owner of the terminal opens the application and initiates a new withdrawal. + \begin{enumerate} + \item Application creates a nonce + \item The application starts long polling at the Exchange and awaits the establishment of the nonce (by the Exchange). + \item Nonce is packed into a QR code (with Exchange and amount entered by the terminal owner) + \item QR code is displayed + \end{enumerate} + \item The user now scans the QR Code using his wallet. + \item The application receives the establishment notification of the Exchange. + \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 and pays using his Credit Card. + \item The Terminal executes the payment and presents the result to the user. +\end{enumerate} + +\subsubsection*{The Exchange} + +The Exchange manages the withdrawal using a third party and seeks guarantees of the third party in order to provide a reserve containing Taler which can be withdrawn by the wallet. + +\begin{enumerate} + \item The Exchange retrieves a long polling request for a nonce (from the Terminal). + \item The Exchange creates a mapping entry with the nonce and an empty reserve public key field + \item The Exchange retrieves a request including a nonce and a reserve public key. + \item The Exchange validates the request and adds the key to the mapping. This establishes the nonce to reserve public key mapping. + \item The Exchange ends the long polling from the terminal (by sending back the reserve public key). + \item The Exchange receives payment notification of the terminal. + \item The Exchange verifies the notification by asking the terminal backend for confirmation. + \item The Exchange, upon successfully checking the notification, creates the reserve with the verified amount +\end{enumerate} + +\subsubsection*{The Wallet} + +The Wallet must attest its presence to the terminal by registering a nonce and belonging reserve public key which will hold the Taler that can eventually be withdrawn by the wallet. + +\begin{enumerate} + \item The Wallet scans the QR Code (nonce, 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 nonce to the Exchange + \item The Wallet can withdraw money from the created reserve. +\end{enumerate} + +\subsection*{Taler system} +\subsubsection*{Taler Wallet} +\subsubsection*{Taler Exchange} + +\subsection*{Terminal system} +\subsubsection*{Terminal} +\subsubsection*{Terminal Manufacturer Backend} +\subsubsection*{Terminal Fulfillment } +\ No newline at end of file diff --git a/docs/content/glossary.tex b/docs/content/glossary.tex @@ -1,54 +1,5 @@ -\newglossaryentry{BibTeX}{ - name={BibTeX}, - description={Program for the creation of bibliographical references and directories in \TeX or \LaTeX\, documents}, - plural=BibTeXs -} - -\newglossaryentry{zynq}{ - name=Zynq, - description={\textbf{Zynq} Xilinx' AP SoC. The characteristic feature of Zynq is that it combines a dual-core ARM Cortex-A9 processor with traditional Series-7 FPGA logic fabric}, - plural=Zynqs -} - - -\newglossaryentry{soc}{ - name=SoC, - description={\textbf{System-on-Chip (SoC)} A single chip that holds all of the necessary hardware and electronic circuitry for a complete system. SoC includes on-chip memory (RAM and ROM), the microprocessor, peripheral interfaces, I/O logic control, data converters, and other components that comprise a complete computer system}, - plural=SoCs -} - -\newglossaryentry{apsoc}{ - name=AP SoC, - description={\textbf{All Programmable System-on-Chip (AP SoC)} was introduced by Xilinx. It represents a IC which comprise a hard-core processor core surrounded by an FPGA fabric. This type of ICs are highly configurable and provide algorithm partitioning capabilities. This provides high benefit for highly scale-able applications as well as fast time-to-market}, - plural=AP SoCs -} - -\newglossaryentry{zbook}{ - name=Zynq Book, - description={\textbf{Zynq Book} A book that summarizes all the important aspects when working with Zynq and provides a strong and easy understandable introduction to the topic. The book has been written by a team of University of Strathclyde Glasgow in cooperation with Xilinx}, - plural=Zynq Books -} - -\newglossaryentry{zboard}{ - name=ZedBoard, - description={\textbf{ZedBoard} A low cost development board featuring a Zynq-700 0 SoC, and a number of peripherals}, - plural=ZedBoards -} - - -\newglossaryentry{asic}{ - name=ASIC, - description={\textbf{Application-Specific Integrated Circuit (ASIC)} An integrated circuit which is designed for a specific use, rather than general-purpose use}, - plural=ASICs -} - -\newglossaryentry{rtos}{ - name=RTOS, - description={\textbf{Real-Time Operating System (RTOS)} A category of operating systems defined by their ability to respond quickly and predictably for a given task}, - plural=RTOSs -} - -\newglossaryentry{arm}{ - name=ARM, - description={\textbf{ARM} A family of processor architectures. The hard processor type which forms the basis of the Zynq processing system is an ARM Cortex-A9 version. The term ‘ARM’ may also be used to refer to the developer of the processor, i.e. a company of the same name} +\newglossaryentry{TEST}{ + name={TEST}, + description={TEST}, + plural=TESTS } diff --git a/docs/content/implementation/exchange.tex b/docs/content/implementation/exchange.tex @@ -1 +1 @@ -\section*{implementing cashless2ecash docs} -\ No newline at end of file +\section*{implementing nonce2ecash docs} +\ No newline at end of file diff --git a/docs/content/implementation/terminal.tex b/docs/content/implementation/terminal.tex @@ -0,0 +1 @@ +\section*{implementing terminal docs} +\ No newline at end of file diff --git a/docs/content/introduction/introduction.tex b/docs/content/introduction/introduction.tex @@ -63,6 +63,6 @@ As long as the interaction of withdrawal is manual and the identification and ve But now we have the problem that the Exchange is not able to proof that the money was sent to the wallet it was intended for. This leaves the Exchange with liability weaknesses and makes it unattractive to operate the cashless2ecash feature for Exchange operators and therefore introduces a weakness. -Imagine the following situation: A user gets kidnapped and is forced to buy a certain amount of Taler. But now instead of using the wallet of the kidnapped user, the kidnapper accesses Exchange with his own wallet and steals the money. This makes stealing money from someone as hard as making them pay using their credit card or reveal the credentials to do so (which is totally possible \autoref*{cc-fraud-types}). Also plain digital attacks are possible (and probably more likely) where the attacker is able to claim the reserves for himself before the user gets his hands on the money. +Imagine the following situation: A user gets kidnapped and is forced to buy a certain amount of Taler. But now instead of using the wallet of the kidnapped user, the kidnapper accesses Exchange with his own wallet and steals the money. This makes stealing money from someone as hard as making them pay using their credit card or reveal the credentials to do so (which is totally possible \cite{cc-fraud-types}). Also plain digital attacks are possible (and probably more likely) where the attacker is able to claim the reserves for himself before the user gets his hands on the money. This situation can be prevented by leveraging the \textbf{nonce2ecash} approach proposed by Florian Jung. This approach forces the withdrawing party to lock their withdrawal to a specific user (public key) before the actual withdrawal. This approach makes stealing money as hard as gaining control over the wallet (which is the equivalent to stealing the wallet). diff --git a/docs/listings/specs/nonce2ecash_api_spec.yml b/docs/listings/specs/nonce2ecash_api_spec.yml @@ -0,0 +1,115 @@ +openapi: 3.0.3 +info: + title: nonce2ecash API + description: API managing a mapping table which links a nonce to a public key. This allows withdrawing from the exchange by the nonce. Additionally it provides facilities allowing for the Exchange operators to register new providers or delete obsolete ones. + version: 0.0.1 +paths: + /n2c/nonces/withdrawal-registration: + post: + summary: Register Nonce to Reserve Public Key + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/N2CWithdrawalRequest' + responses: + '200': + description: Message received successfully + tags: + - nonces + /n2c/nonces/withdrawal-processing: + post: + summary: Provider notifies the exchange about the payment (if it was successful or not) + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/N2CPaymentNotification' + responses: + '200': + description: Message received successfully + tags: + - nonces + /n2c/nonces/withdrawal-status: + get: + summary: Check Status + parameters: + - name: nonce + in: query + description: The nonce for which to check the status + required: true + schema: + type: string + - name: listenForStatus + in: query + description: The status to listen for the given nonce + required: false + schema: + $ref: '#/components/schemas/N2CStatus' + responses: + '200': + description: Status retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/N2CMapping' + '404': + description: Mapping not found + '' + tags: + - nonces +tags: + - name: nonces + description: managing and retrieving information about the mapping table for the nonce to reserve public key mapping. +components: + schemas: + N2CWithdrawalRequest: + description: Maps a nonce generated by the provider to a reserve public key generated by the wallet. + type: object + properties: + nonce: + type: string + reservePubKey: + type: string + format: byte + amount: + type: string + providerType: + $ref: '#/components/schemas/N2CProviderType' + N2CPaymentNotification: + description: Notifies the exchange about an executed payment. This will trigger a provider specific attestation of the payment according to the ProviderPaymentAttestationType. + type: object + properties: + nonce: + type: string + providerTransactionId: + type: string + success: + type: boolean + fees: + type: number + N2CStatus: + description: Describes the states a nonce to reserve public key mapping can be in. + type: string + enum: + - ESTABLISHED + - PAYED + - RESERVE_CREATED + N2CMapping: + description: Maps a nonce generated by the provider to a reserve public key generated by the wallet. + type: object + properties: + nonce: + type: string + reservePubKey: + type: string + format: byte + status: + $ref: '#/components/schemas/N2CStatus' + N2CProviderType: + description: Signals the exchange which provider is talking to him. Like this more Providers can be easily supported by adding their verfification flow to the code of nonce2ecash. This allows to extend the system with various providers. + type: string + enum: + - WALLEE diff --git a/docs/pictures/diagrams/db_cashless2ecash_erd.png b/docs/pictures/diagrams/db_cashless2ecash_erd.png Binary files differ. diff --git a/docs/pictures/diagrams/db_nonce2ecash_erd.png b/docs/pictures/diagrams/db_nonce2ecash_erd.png Binary files differ. diff --git a/docs/pictures/diagrams/nonce2ecash_class_diagram.png b/docs/pictures/diagrams/nonce2ecash_class_diagram.png Binary files differ. diff --git a/docs/thesis.pdf b/docs/thesis.pdf Binary files differ. diff --git a/docs/thesis.tex b/docs/thesis.tex @@ -54,16 +54,6 @@ %--------------------------------------------------------------------------- \graphicspath{{pictures/}{figures/}} %--------------------------------------------------------------------------- -% Blind text -> for dummy text -%--------------------------------------------------------------------------- -\usepackage{blindtext} -\usepackage{letltxmacro} -\LetLtxMacro{\blindtextblindtext}{\blindtext} - -\RenewDocumentCommand{\blindtext}{O{\value{blindtext}}}{ - \begingroup\color{BFH-Gray}\blindtextblindtext[#1]\endgroup -} -%--------------------------------------------------------------------------- % Glossary Package %--------------------------------------------------------------------------- % the glossaries package uses makeindex @@ -107,6 +97,30 @@ ]{hyperref} %--------------------------------------------------------------------------- +%% yaml style definition +\lstdefinestyle{yaml}{ + keywords={true,false,null,y,n}, % ,... all the keyword you want + keywordstyle=\color{blue}\bfseries, + moredelim=[is][commentstyle]{||}{££}, % invisible custom delimiters + identifierstyle=\color{darkgray}, + sensitive=false, + comment=[l]{\#}, + morecomment=[s]{/*}{*/}, + commentstyle=\color{gray}\ttfamily, + stringstyle=\color{teal}\ttfamily, + moredelim=[l][\color{orange}]{\&}, + moredelim=[l][\color{magenta}]{*}, + moredelim=**[il][\color{darkgray}{:}\color{teal}]{:}, + morestring=[b]', + morestring=[b]", + numbers=left, + numberstyle=\color{gray}, + numbersep=10pt, + frame=single, + backgroundcolor=\color{gray!5} +} +%--------------------------------------------------------------------------- + %% %% Customize Footer and Headers in Document %% \KOMAoptions{headsepline,plainheadsepline,footsepline,plainfootsepline}% %% \setkomafont{headsepline}{\color{BFH-DarkBlue}}% BFH-DarkBlue required bfhcolors @@ -125,8 +139,8 @@ %% \cofoot*{cofoot} %% \rofoot*{rofoot} %--------------------------------------------------------------------------- -\begin{document} +\begin{document} %------------ START FRONT PART ------------ \frontmatter @@ -164,10 +178,12 @@ \input{content/introduction/goal} \chapter{Architecture} -\input{content/architecture/bigpicture} +\input{content/architecture/overview} +\input{content/architecture/nonce2ecash} \chapter{Implementation} \input{content/implementation/exchange} +\input{content/implementation/terminal} \input{content/implementation/wallee} \chapter{Results} @@ -200,6 +216,10 @@ %------------ Appendix ---------------- \appendix \chapter{Appendix A} +\section*{API} +\label{appendix-api-spec} +\lstinputlisting[style=yaml,caption={nonce2ecash API specification}]{listings/specs/nonce2ecash_api_spec.yml} + \chapter{Appendix B} \section{Meeting notes} \input{content/appendix/meeting_notes} diff --git a/specs/db_cashless2ecash_erd.plantuml b/specs/db_cashless2ecash_erd.plantuml @@ -1,34 +0,0 @@ -@startuml -enum n2c_status { - n2c_ESTABLISHED - n2c_ESTABLISHMENT_FAILED - n2c_PAYED - n2c_RESERVE_CREATED - n2c_PAYMENT_FAILED -} - -entity n2c_nonce_reservepubkey { - + provider_name: string - + nonce: number - + nonce_provider_sig: blob - + reserve_pubkey: number - + state: n2cStatus - + registration_ts: timestamp -} - -enum n2c_provider_attestation_type { - NONE - WALLEE -} - -entity n2c_provider { - + name: string - + publicKey: blob - + publicKeySignature: blob - + attestationType: ProviderAttestationType -} - -n2c_provider --* n2c_provider_attestation_type -n2c_nonce_reservepubkey --* n2c_status -n2c_nonce_reservepubkey "m" --> "1" n2c_provider -@enduml diff --git a/specs/db_nonce2ecash_erd.plantuml b/specs/db_nonce2ecash_erd.plantuml @@ -0,0 +1,22 @@ +@startuml +entity n2c_status { + id: number + name: string +} + +entity n2c_provider_type { + id: number + name: string +} + +entity n2c_nonce_reservepubkey { + nonce: number + provider_type_id: n2c_provider_type + reserve_pubkey: number + n2c_status_id: n2c_status + registration_ts: timestamp +} + +n2c_nonce_reservepubkey --* n2c_status +n2c_nonce_reservepubkey --* n2c_provider_type +@enduml diff --git a/specs/nonce2ecash_api_spec.yml b/specs/nonce2ecash_api_spec.yml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: nonce2ecash API - description: API managing a mapping table which links a nonce to a public key. This allows withdrawing from the exchange by the nonce. Additionally it provides facilities allowing for the Exchange operators to register new providers or delete obsolete ones. + description: API managing a mapping table which links a nonce to a reserve public key. This allows withdrawing from the exchange by a given nonce. version: 0.0.1 paths: /n2c/nonces/withdrawal-registration: @@ -76,13 +76,14 @@ components: providerType: $ref: '#/components/schemas/N2CProviderType' N2CPaymentNotification: - description: Notifies the exchange about an executed payment. This will trigger a provider specific attestation of the payment according to the ProviderPaymentAttestationType. + description: Notifies the exchange about an executed payment. This will trigger a provider specific attestation of the payment according to the N2CProviderType. This allows to define the attestation process for each supported provider individually. type: object properties: nonce: type: string providerTransactionId: type: string + description: a unique identifier of the provider which identifies the transaction in the providers system. success: type: boolean amount: @@ -94,10 +95,9 @@ components: type: string enum: - ESTABLISHED - - ESTABLISHMENT_FAILED - PAYED - RESERVE_CREATED - - PAYMENT_FAILED + - RESERVE_CREATION_FAILED N2CMapping: description: Maps a nonce generated by the provider to a reserve public key generated by the wallet. type: object @@ -110,7 +110,7 @@ components: status: $ref: '#/components/schemas/N2CStatus' N2CProviderType: - description: Signals the exchange which provider is talking to him. Like this more Providers can be easily supported by adding their verfification flow to the code of nonce2ecash. + description: Signals the exchange which provider is talking to him. Like this more Providers can be easily supported by adding their verfification flow to the code of nonce2ecash. This allows to extend the system with various providers. type: string enum: - WALLEE diff --git a/specs/nonce2ecash_class_diagram.plantuml b/specs/nonce2ecash_class_diagram.plantuml @@ -18,7 +18,7 @@ enum WalleeTransactionState { } interface WalleeClient { - getTransactionState(): WalleeTransactionState + getTransactionState(transactionId: string): WalleeTransactionState } class PaymentVerifierProxy { @@ -34,10 +34,6 @@ class WalleePaymentVerifier { verifyPayment(nonce: string): boolean } -class NonePaymentVerifier { - verifyPayment(nonce: string): boolean -} - interface NonceToReservePubkeyMappingRepository { createMapping(nonce: string, reservePubkey: byte[]) removeMapping(nonce: string) @@ -51,39 +47,28 @@ class NonceToReservePubkeyMappingService { enum Status { ESTABLISHED - ESTABLISHMENT_FAILED PAYED RESERVE_CREATED - PAYMENT_FAILED } class NonceToReservePubkey { - + providerName: string + nonce: number - + nonce_provider_sig: byte[] + + provider_type: ProviderType + reserve_pubkey: number + state: Status + established_t_s: timestamp } -enum ProviderAttestationType { - NONE +enum ProviderType { WALLEE } -class Provider { - + name: string - + publicKey: byte[] - + publicKeySignature: byte[] - + attestationType: ProviderAttestationType -} - -Provider --* ProviderAttestationType +NonceToReservePubkey --* ProviderType NonceToReservePubkey --* Status -NonceToReservePubkey --* Provider WalleeClient ..> WalleeTransactionState : use PaymentVerifierProxy --* PaymentVerifier : knows +WalleePaymentVerifier --o WalleeClient: needs WalleePaymentVerifier ..> PaymentVerifier : implements NonePaymentVerifier ..> PaymentVerifier : implements NonceToReservePubkeyMappingService --> NonceToReservePubkeyMappingRepository: use
