commit bd0dc46e7eb9c72aa7a6e8dae1e5fb05e3b04322
parent 349fa10bb5cf2f9d827127868b2406b324c31de1
Author: Matyja Lukas Adam <lukas.matyja@students.bfh.ch>
Date: Fri, 7 Jun 2024 12:10:10 +0200
merge
Diffstat:
3 files changed, 18 insertions(+), 14 deletions(-)
diff --git a/doc/thesis/chapters/implementation/arch.tex b/doc/thesis/chapters/implementation/arch.tex
@@ -1,11 +1,10 @@
-\section{System Architecture}
-As the charity backend and donor wallet implementation are not yet developed the following architecture is reduced to the Donau backend, the client API calls and the API tests.
-% The android app
+\section{System Architecture}\label{system_architecture}
+As the charity backend and donor wallet implementation are not yet developed the following architecture is reduced to the Donau backend.
\begin{figure}[ht]
\includegraphics[width=1\textwidth]{donau_system_arch}
\caption{Donau system architecture} \label{fig:donau_system_arch}
\end{figure}
-The Donau backend implements the REST API and HTTP handler which communicates with the database plugin. The postgresql database is further described in section ?? of the thesis.
+The Donau backend implements the REST API and HTTP handler which communicates with the database plugin. The postgresql database is further described in section \ref{donau_database} of the thesis.
The HTTP handler includes a key handler that interacts with the three secmod processes. The secmod processes generate the keys. Only they have access to the private keys.
diff --git a/doc/thesis/chapters/implementation/donau.tex b/doc/thesis/chapters/implementation/donau.tex
@@ -1,12 +1,11 @@
-
-\section{Donau}
-The Donau is written in C as it reuses parts of the codebase from the exchange of GNU Taler[xx]. The Donau has a similar architecture and uses crypographic blinded signatures in a similar way as the exchange does.
+\section{Donau}\label{donau}
+The Donau is written in C as it reuses parts of the codebase from the exchange of GNU Taler \ref{taler}. The Donau has a similar architecture and uses crypographic blinded signatures in a similar way as the exchange does.
\subsection{REST API}
The detailed REST API specificatoin of the Donau backend is publicy available at the following url: \url{https://docs.taler.net/core/api-donau.html}. The following are the main API endpoints:
\subsubsection{\texttt{/keys}}
-The \texttt{GET /keys} request returns all valid donation unit public keys offered by the Donau, as well as the Donau's current EdDSA public signing key. Donation units unit keys are used by the Donau to sign blinded messages for an issue receipt request. The signing key is primarily used to create the donation statement signature for the donor (see section xx).
+The \texttt{GET /keys} request returns all valid donation unit public keys offered by the Donau, as well as the Donau's current EdDSA public signing key. Donation unit keys are used by the Donau to sign blinded messages for an issue receipt request. The signing key is primarily used to create the donation statement signature for the donor (see section \ref{donor_requests_a_donation_statement_from_the_donau}).
%TODO
The following is an example response of a \lstinline{curl 127.0.0.1:8080/keys} command.
@@ -58,7 +57,9 @@ The following is an example response of a \lstinline{curl 127.0.0.1:8080/keys} c
\end{lstlisting}
\subsubsection{\texttt{/charities}}
-In order for a charity to be able to issue receipts it must be registered by the Donau. To do so the Donau provides an API to manage charities. It is recommended that only the Donau admin can update charities while the charity itself should be able to request their issued donation receipt state to keep track of the set donation limit. The state includes the maximum donation amount and the current donated amount for the charity of the current year.
+In order for a charity to be able to issue receipts it must be registered in the Donau. To do so the Donau provides an API to manage charities. It is expected that only the Donau administrator can manage the registered charities.
+The charity itself should be able to request their issued donation receipt to keep track of the set donation limit.
+The response includes the maximum donation amount and the current donated amount for the charity of the current year.
\begin{figure}[ht]
\includegraphics[width=1\textwidth]{donau_flow_register_charity}
@@ -104,14 +105,16 @@ The response consists of the charity ID generated by the database.
\subsubsection{\texttt{/batch-issue}}
-Only recognized charities are allowed to request issue receipts for their donors (see section \ref{validation}). An post issue receipt request includes an array of BUDI-Key-Pairs. A BUDI-Key-Pair consists of a BUDI and a hash of a public donation unit key. The charity also signs the request with an EdDSA private key. The corresponding public key was given to the Donau at the registration of the charity. After the Donau checked the signature from the charity it signs the BUDIs with the corresponding donation unit private key. Before the signatures are returned to the charity the Donau saves a hash of the request and all donation unit signatures to make the request idempotent (see database section).
+Only recognized charities are allowed to issue receipts for their donors (see section \ref{validation}).
+An \texttt{POST} issue receipt request includes an array of \texttt{BKP}s. A \texttt{BKP} consists of a \texttt{BUDI} and a hash of a public donation unit key (see section \ref{notation_and_definitions}).
+The charity also signs the request with its own EdDSA private key. The corresponding public key was given to the Donau in the registration process of the charity.
+After the Donau checked the signature from the charity it signs the \texttt{BUDI}s with the corresponding donation unit private key. Before the signatures are returned to the charity the Donau saves a hash of the request and all donation unit signatures to make the request idempotent (see section \ref{donau_database}).
\begin{figure}[ht]
\includegraphics[width=1\textwidth]{donau_flow_issue_receipt}
%\caption{flow chart issue receipt} \label{fig:donau_flow_issue_receipt}
\end{figure}
-%TODO
The following is an example response of a \lstinline{curl -d @issue.json -X POST http://127.0.0.1:8080/batch-issue/1} request. The number at the end of the URL stands for the charity id.
\begin{lstlisting}[title=issue.json]
{
@@ -144,8 +147,10 @@ The following is an example response of a \lstinline{curl -d @issue.json -X POST
\end{lstlisting}
\subsubsection{\texttt{/batch-submit}}
-%TODO describe donation receipt -> glossary?
-The post submit route is used by the donor to summarize his or her donation receipts into one donation statement EdDSA signature. The request is composed of the donation receipt, the corresponding year and the hash of the salted tax id. Processing the request the Donau checks the validity of the donation receipts and searches after more saved donation receipts made in the requested year. The EdDSA signature over the total amount of the value of the donation units of all donation receipts, the hash of the salted tax id and the year forms the donation statement. The donation statement and the receipts are stored in the database (see database).
+The post submit route is used by the donor to summarize his or her donation receipts into one donation statement EdDSA signature.
+The request is composed of the donation receipt (see section \ref{notation_and_definitions}), the corresponding year and the hash of the salted tax ID.
+Processing the request the Donau checks the validity of the donation receipts and searches after more saved donation receipts made in the requested year.
+The EdDSA signature over the total amount of the value of the donation units of all donation receipts, the hash of the salted tax id and the year forms the donation statement. The donation statement and the receipts are stored in the database (see section \ref{donau_database}).
\subsubsection{\texttt{/donation-statement}}
Even the donation statement will not be returned after a submit request, a donation statement get request can be made for a specified year and a salted and hashed tax id.
@@ -187,7 +192,7 @@ The following is an example response of a \lstinline{curl http://127.0.0.1:8080/
\subsection{Donau Client}
The REST client removes some of the complexity of sending requests to the Donau Server. It converts request parameters into JSON and parses JSON responses into a usable C format. What the exact queries are and how they look like is already described in the chapter xx Donau REST API.
-\subsection{Donau Database}
+\subsection{Donau Database}\label{donau_database}
The Donau database contains five tables as shown in the figure below. The \texttt{donation\_units} and \texttt{donau\_sign\_keys} table store the keys necessary for signing and creating donation receipts. Donation receipts that are issued to be signed by the donau are stored in the \texttt{receipts\_issued} table while the receipts that are already signed are stored in the \texttt{receipts\_submitted} table. The \texttt{history} table keeps the donation records of the past years.
\begin{figure}[ht]
diff --git a/doc/thesis/thesis.pdf b/doc/thesis/thesis.pdf
Binary files differ.
