implementation2.tex (5313B)
1 \section{Implementation}\label{implementation} 2 3 This section describes the current implementation of the Donau 4 \ifanonymous 5 server, 6 \else 7 server (available from \url{https://git.taler.net/donau.git}), 8 \fi 9 which 10 primarily consists of an HTTP server with a REST API 11 \ifanonymous 12 \else 13 (\url{https://docs.taler.net/core/api-donau.html}) 14 \fi 15 and a Postgresql 16 database (Figure~\ref{fig:donau_system_arch}). The Donau backend is 17 written in C, as it reuses parts of the codebase from GNU Taler 18 exchange component. The Donau has a similar architecture and uses 19 cryptographic blinded signatures in a similar way as the GNU Taler 20 exchange does, including encapsulating its private keys in separate 21 ``security module'' helper processes. 22 23 \begin{figure}[ht] 24 \begin{center} 25 \includegraphics[width=0.5\textwidth]{donau_system_arch} 26 \end{center} 27 \caption{Donau server architecture} \label{fig:donau_system_arch} 28 \end{figure} 29 30 \subsection{REST API Overview} \label{rest_api} 31 32 The main endpoints of the REST API are briefly summarized 33 in the following sections. 34 \ifanonymous 35 For examples see Appendix~\ref{app-impl}. 36 \fi 37 38 \subsubsection{\texttt{/keys}} 39 40 The \texttt{GET /keys} request returns all valid donation unit public keys 41 offered by the Donau, as well as the Donau's current EdDSA public signing key. 42 43 \subsubsection{\texttt{/charities}} 44 45 In order for a charity to be able to issue receipts by a specific 46 Donau it must be registered by this Donau. The Donau provides an API 47 to manage charities. By default only the Donau administrator can 48 change the list of registered charities. The charity itself is able 49 to request a donation report to keep track of their total donations in 50 the current year. The response includes the maximum donation amount 51 and the current donated amount for the charity of the current year. 52 53 \begin{figure*}[h] 54 \includegraphics[width=0.7\textwidth]{donau_flow_issue_receipt} 55 \caption{Flow of the issue receipt process, incl. an optional check on donation limits 56 per charity} \label{fig:donau_flow_issue_receipt} % XXX: this diagram mentions the "check donation limit" function which was removed from the text. -JL 57 \end{figure*} 58 59 \subsubsection{\texttt{/batch-issue}} 60 61 Only recognized charities are allowed to issue receipts for their donors. 62 A \texttt{POST} issue receipt request includes an array of \texttt{BKP}s. A 63 \texttt{BKP} consists of a \texttt{BUDI} and a hash of a public donation unit 64 key (see section~\ref{notation_and_definitions}). 65 The charity signs the request with its own EdDSA private key. The 66 corresponding public key was given to the Donau in the registration process of 67 the charity. 68 After the Donau checks the signature from the charity it signs the 69 \texttt{BUDI}s with the corresponding donation unit private key. Before the 70 signatures are returned to the charity the Donau saves a hash of the request 71 and all donation unit signatures to detect replays (see section~\ref{donau_database}). 72 73 \subsubsection{\texttt{/batch-submit}} 74 75 The batch-submit route is used by the donor to summarize their donation 76 receipts into one donation statement, which then gets signed by the Donau with 77 their EdDSA signature. 78 The request is composed of the donation receipts (see section~\ref{donau_creates_donation_receipt}), 79 the corresponding year and the Donor Identification \DI, which is the salted hash of the donor's taxpayer ID. 80 When processing the request, the Donau checks the validity of the donation 81 receipts and searches its database for other saved donation receipts made in the requested 82 year. 83 The Donau computes 84 a donation statement, consisting of a signature over 85 the total value of the donation units of all donation receipts of the year, 86 the salted hash of the taxpayer ID, and the current year, 87 and stores this in its database along with the submitted receipts (see section~\ref{donau_database}). 88 89 In our implementation the Donau does not return this donation statement under 90 this call but under the {\tt /donation-statement} endpoint, which returns 91 a signature over the cummulative amount under the same \DI. 92 93 \subsection{Donau database}\label{donau_database} 94 95 The Donau database contains five tables. The \texttt{donation\_units} 96 and \texttt{donau\_sign\_keys} table store the keys necessary for 97 signing and creating donation receipts. Donation receipts that are 98 issued to be signed by the Donau are stored in the 99 \texttt{receipts\_issued} table while the receipts that are already 100 signed are stored in the \texttt{receipts\_submitted} table. The 101 \texttt{history} table keeps the donation records of the past years. 102 103 \subsection{Verification URL syntax} 104 105 The verification process used by the tax authority to check the 106 donation statement (see 107 section~\ref{donor_sends_final_statement_to_a_validator}). A 108 verification app is expected to scan a QR code that encodes the 109 donation statement, verifies the signature and displays the signed 110 values of the donation statement. The verification URL 111 encodes all binary values in base64 and has the following syntax: 112 113 \begin{verbatim} 114 donau://DOMAIN/YEAR/TAXID:SALT/AMOUNT/EDSIG 115 \end{verbatim} 116 117 118 \subsection{Other components} 119 120 For the charities, support for donations is being integrated into 121 the GNU Taler merchant backend. Similarly, GNU Taler wallets 122 will store donation receipts and export donation statements.