donau

donau.tex (12156B)

---

 \section{Donau}\label{donau}
 The Donau is written in C as it reuses parts of the codebase from the exchange
 of GNU Taler (see section \ref{taler} for more information about GNU Taler).
 The Donau has a similar architecture and uses
 crypographic blinded signatures in a similar way as the exchange does.
 
 \subsection{REST API} \label{rest_api}
 The detailed REST API specification of the Donau backend is publicly available
 under 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 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}).
 
 The following is an example response of a \lstinline{curl 127.0.0.1:8080/keys}
 command. Some parts of the following example responses are truncated (denoted by
 the three dots '\texttt{...}') to make them more readable.
 
 \begin{lstlisting}
 {
   "version": "0:0:0",
   "base_url": "http://localhost:8080/",
   "currency": "EUR",
   "signkeys": [
     {
       "stamp_start": {
         "t_s": 1717069556
       },
       "stamp_expire": {
         "t_s": 1718279156
       },
       "key": "CFV2PY8164E231XZSQK30K8R6CBQ..."
     },
     {
     ...
     }
     ],
     "donation_units": [
     {
       "donation_unit_pub": {
         "cipher": "RSA",
         "rsa_public_key": "020000YC7XK99S..."
       },
       "year": 2024,
       "lost": false,
       "value": "EUR:5"
     },
     {
       "donation_unit_pub": {
         "cipher": "CS",
         "cs_public_key": "7SKRQGBSEPBG24..."
       },
       "year": 2024,
       "lost": false,
       "value": "EUR:1"
     },
     {
     ...
     }
     ]
 }
 \end{lstlisting}
 
 \subsubsection{\texttt{/charities}}
 In order for a charity to be able to issue receipts by a specific Donau it must
 be registered by this 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}
 \caption{The tax authority registers a new charity in the Donau}\label{fig:donau_flow_register_charity}
 \end{figure}
 
 The following is an example response of a
 \lstinline{curl 127.0.0.1:8080/charities} command.
 There is only one charity named
 \texttt{example} registered with a donation limit of 10 euros.
 
 \begin{lstlisting}
 {
   "charities": [
     {
       "charity_pub": "ABETNXT9ZF606FRF3WD5...",
       "url": "example.com",
       "name": "example",
       "max_per_year": "EUR:10",
       "receipts_to_date": "EUR:0",
       "current_year": 2024
     }
   ]
 }
 \end{lstlisting}
 
 To insert a charity a \texttt{POST} request can be sent using
 \lstinline{curl -d @charity.json -X POST http://127.0.0.1:8080/charities}.
 
 \begin{lstlisting}[title=charity.json]
 {
   "charity_pub": "ABETNXT9ZF606FRF3WD5...",
   "charity_name": "mycharity",
   "charity_url": "mycharity.example.com",
   "max_per_year": "EUR:1000",
   "receipts_to_date": "EUR:0",
   "current_year": 2024
 }
 \end{lstlisting}
 
 The response consists of the charity ID generated by the database.
 \begin{lstlisting}
 {
   "charity-id": 1
 }
 \end{lstlisting}
 
 
 \subsubsection{\texttt{/batch-issue}}
 Only recognized charities are allowed to issue receipts for their donors (see
 section \ref{issuing_donation_receipts}).
 A \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 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 of the issue receipt process} \label{fig:donau_flow_issue_receipt}
 \end{figure}
 
 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 is the charity ID.
 
 \begin{lstlisting}[title=issue.json]
 {
   "budikeypairs": [
   {
     "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED...",
     "blinded_udi": {
     "cipher": "RSA",
     "rsa_blinded_identifier": "AXPTEE24W28S9XN..."
     }
   }
   ],
     "charity_sig": "JEJ0QMDXD416XKSK1SG0DETJEH...",
   "year": 2024
 }
 \end{lstlisting}
 
 \begin{lstlisting}
 {
    "blind_signatures": [
      {
       "blinded_signature": {
       "cipher": "RSA",
       "blinded_rsa_signature": "16XHNWSCDRVKHF..."
        }
      }
    ],
    "issued_amount: "EUR:15"
 }
 \end{lstlisting}
 
 \subsubsection{\texttt{/batch-submit}}
 The batch-submit route is used by the donor to summarize their 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.
 When 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 of the year, the hash of the salted tax ID and
 the year forms the donation statement. The donation statement and the receipts
 are stored in the Donau database (see section \ref{donau_database}).
 
 \subsubsection{\texttt{/donation-statement}}
 The donation statement will not be returned after a submit request, a
 donation statement get request can be made for a specified year and tax ID.
 
 \begin{figure}[ht]
 \includegraphics[width=1\textwidth]{donau_flow_submit_receipt}
 \caption{Donor requests a donation statement from the Donau} \label{fig:donau_flow_submit_receipt}
 \end{figure}
 
 The following is an example of a \\
 \lstinline{curl -d @submit.json -X POST http://127.0.0.1:8080/batch-submit}
 request. If successful, the Donau returns the \texttt{HTTP 201} status code
 with an empty response.
 
 \begin{lstlisting}[title=submit.json]
 {
   "h_donor_tax_id": "N2NYR2SFNGZSS388R2SB0VK...",
   "donation_year": 2024,
   "donation_receipts": [
   {
     "h_donaton_unit_pub": "130C2KDHTAFDQFB8X...",
     "nonce": "JEQC39G",
     "donation_unit_sig":
     {
     "cipher": "RSA",
     "rsa_signature":  "GQBXPNE4JT5W53T3CVP6E..."
     }
   }
   ]
 }
 \end{lstlisting}
 
 The following is an example response of a \\
 \lstinline{curl http://127.0.0.1:8080/donation-statement/2024/N2NYR2SFNGZSS388R2SB...} \\
 request.
 
 The last parameter of the URL is the salted hash of the donor tax ID.
 
 \begin{lstlisting}
 {
   "total": "EUR:15",
   "donation_statement": "C1JVDP25AR001W5AHMAZ...",
   "donau_pub": "63f62b7901311c2187bfcde6304d1..."
 }
 \end{lstlisting}
 \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 chapter \label{rest_api}.
 
 \subsection{Donau database}\label{donau_database}
 The Donau database contains five tables as shown in figure
 \ref{fig:db_physical_model}. 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]
 \includegraphics[width=1\textwidth]{db_physical_model}
 \caption{Donau database model (generated by \url{https://dbdiagram.io/})} \label{fig:db_physical_model}
 \end{figure}
 \subsubsection{charities}
 Each registered charity has an entry in this table. There may be a donation
 limit imposed by local law which prevents further donations if the limit is
 reached.
 
 \begin{itemize}
     \item \texttt{charity\_id:} Unique ID generated by the database.
     \item \texttt{charity\_pub:} Charity EdDSA public key
     \item \texttt{charity\_name:} Name of the charity
     \item \texttt{charity\_url:} Charity URL
     \item \texttt{max\_per\_year:} The annual donation limit according to local law.
     \item \texttt{receipts\_to\_date:} The current amount of donations in the current year. Reset to 0 when incrementing the \texttt{current\_year}.
     \item \texttt{current\_year:} Current year
 \end{itemize}
 
 \subsubsection{donation\_units}
 Table containing all the valid donation units the Donau knows about.
 \begin{itemize}
     \item \texttt{donation\_unit\_serial:} Unique ID generated by the database.
     \item \texttt{h\_donation\_unit\_pub:} Hash value of the donation unit public key \texttt{donation\_unit\_pub}
     \item \texttt{donation\_unit\_pub:} The donation unit public key. Is either an RSA or CS public key.
     \item \texttt{validity\_year:} The year, for which the donation unit is valid.
     \item \texttt{value:} The amount and currency that this donation unit represents.
 \end{itemize}
 
 \subsubsection{donau\_sign\_keys}
 Contains all Donau EdDSA signing keys.
 \begin{itemize}
     \item \texttt{dsk\_serial:} Unique ID generated by the database.
     \item \texttt{donau\_pub:} Donau EdDSA public key.
     \item \texttt{valid\_from:} Year the signing key becomes valid.
     \item \texttt{expire\_sign:} Year the signing key becomes invalid.
     \item \texttt{expire\_legal:} Year the signing key legally expires.
 \end{itemize}
 
 \subsubsection{receipts\_issued}
 Contains all issued donation receipts sent to the Donau.
 \begin{itemize}
     \item \texttt{receipt\_id:} Unique ID generated by the database.
     \item \texttt{blinded\_sig:} Array of blinded signatures. These are the \texttt{BKP}'s the Donau blind signed.
     \item \texttt{charity\_id:} The ID of the charity that received the donation.
     \item \texttt{receipt\_hash:} Hash value over all the blinded donation receipt received plus the hash of the donation units public key.
     \item \texttt{amount:} The amount and currency this donation receipt contains.
 \end{itemize}
 
 \subsubsection{receipts\_submitted}
 Contains all submitted donation receipts sent to the Donor. By storing the
 signature \texttt{donation\_unit\_sig}, the idempotentcy of the API is kept in
 case the private key is replaced.
 \begin{itemize}
     \item \texttt{receipt\_id:} Unique ID generated by the database.
     \item \texttt{h\_tax\_number:} The hash of the tax number and salt.
     \item \texttt{nonce:} The nonce used in the \texttt{Unique Donor Identifier}
     \item \texttt{donation\_unit\_pub:} Reference to public key used to sign.
     \item \texttt{donation\_unit\_sig:} The unblinded signature the Donau made.
     \item \texttt{donation\_year:} The year the donation was made.
 \end{itemize}
 
 \subsubsection{history}
 History of the yearly donations for each charity. This data provides a record
 of donations each year. It could also provide valuable information that could
 be used in statistics to analyze general donations over the year.
 \begin{itemize}
     \item \texttt{charity\_id:} Unique ID generated by the database.
     \item \texttt{final\_amount:} The final amount that was donated to the charity
     \item \texttt{donation\_year:} The year in which the donations where made.
 \end{itemize}