donau

implementation.tex (13260B)

---

 \section{Implementation}\label{implementation}
 
 This section describes the current implementation of the Donau, which
 consists of a REST API, an Android verification app, and the Donau
 database.  The Donau is written in C, as it reuses parts of the
 codebase from GNU Taler exchange component.  The Donau has a similar
 architecture and uses cryptographic blinded signatures in a similar
 way as the GNU Taler exchange does.
 
 On the user side, donation receipts are collected in a wallet; the
 wallet takes the users taxpayer ID and picks its own salt to create
 the Donor Identifier \DI.
 
 \subsection{REST API} \label{rest_api}
 
 The detailed REST API specification of the Donau back-end 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.
 The following is an example response of a \texttt{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{verbatim}
 {
   "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{verbatim}
 
 \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.  The Donau provides an API
 to manage charities.  By default only the Donau administrator can
 change the list of registered charities.  The charity itself is able
 to request a donation report to keep track of their total donations in
 the current year.  The response includes the maximum donation amount
 and the current donated amount for the charity of the current year.
 
 \begin{figure}[ht]
 \includegraphics[width=0.5\textwidth]{donau_flow_register_charity}
 \caption{The tax authority registers a new charity in the Donau.
   A charity first requests to be added to the Donau, including its Charity EdDSA public key in its request.
   The tax authority them adds the charity by sending a POST request to the {\tt
 /charities} endpoint with the relevant data on the charity
 }\label{fig:donau_flow_register_charity}
 \end{figure}
 
 The following is an example response of a \texttt{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{verbatim}
 {
   "charities": [
     {
       "charity_pub": "ABETNXT9ZF606FRF3WD5...",
       "url": "example.com",
       "name": "example",
       "max_per_year": "EUR:10",
       "receipts_to_date": "EUR:0",
       "current_year": 2024
     }
   ]
 }
 \end{verbatim}
 
 To insert a charity a \texttt{POST} request can be sent using
 \texttt{curl -d @charity.json -X POST http://127.0.0.1:8080/charities}.
 
 The following is an example of a
 \texttt{charity.json} entry
 
 \begin{verbatim}
 {
   "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{verbatim}
 
 The response consists of the charity ID generated by the database.
 \begin{verbatim}
 {
   "charity-id": 1
 }
 \end{verbatim}
 
 
 \subsubsection{\texttt{/batch-issue}}
 Only recognized charities are allowed to issue receipts for their donors.
 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 checks 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 detect replays (see section~\ref{donau_database}).
 
 \begin{figure}[ht]
 \includegraphics[width=0.5\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 \\
 \texttt{curl -d @issue.json -X POST http://127.0.0.1:8080/batch-issue/1}
 request showing a \texttt{issue.json} entry.
 The number at the end of the URL is the charity ID.
 
 
 
 \begin{verbatim}
 {
   "budikeypairs": [
   {
     "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED...",
     "blinded_udi": {
     "cipher": "RSA",
     "rsa_blinded_identifier": "AXPTEE24W28S9XN..."
     }
   }
   ],
     "charity_sig": "JEJ0QMDXD416XKSK1SG0DETJEH...",
   "year": 2024
 }
 \end{verbatim}
 
 \begin{verbatim}
 {
    "blind_signatures": [
      {
       "blinded_signature": {
       "cipher": "RSA",
       "blinded_rsa_signature": "16XHNWSCDRVKHF..."
        }
      }
    ],
    "issued_amount: "EUR:15"
 }
 \end{verbatim}
 
 \subsubsection{\texttt{/batch-submit}}
 The batch-submit route is used by the donor to summarize their donation
 receipts into one donation statement, which then gets signed by the Donau with
 their EdDSA signature.
 The request is composed of the donation receipts (see section~\ref{donau_creates_donation_receipt}),
 the corresponding year and the Donor Identification \DI, which is the salted hash of the donor's taxpayer ID.
 When processing the request, the Donau checks the validity of the donation
 receipts and searches its database for other saved donation receipts made in the requested
 year.
 The Donau computes
 a donation statement, consisting of a signature over
 the total value of the donation units of all donation receipts of the year,
 the salted hash of the taxpayer ID, and the current year,
 and stores this in its database along with the submitted receipts (see section~\ref{donau_database}).
 
 In our implementation the Donau does not return this donation statement under
 this call but under the {\tt donation-statement} request, see below.
 
 The following is an example of a \\
 \texttt{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.
 The following record would be stored.
 
 \begin{verbatim}
 {
   "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{verbatim}
 
 \subsubsection{\texttt{/donation-statement}}
 To obtain the donation statement, the donor submits a GET request for a specified year and taxpayer ID.
 
 The following is an example response of a \\
 \texttt{curl http://127.0.0.1:8080/donation-statement/2024/N2NYR2SFNGZSS388R2SB...} \\
 request.
 
 The last parameter of the URL is the \DI.
 
 \begin{verbatim}
 {
   "total": "EUR:15",
   "donation_statement": "C1JVDP25AR001W5AHMAZ...",
   "donau_pub": "63f62b7901311c2187bfcde6304d1..."
 }
 \end{verbatim}
 
 \begin{figure}[ht]
 \includegraphics[width=0.5\textwidth]{donau_flow_submit_receipt}
 \caption{Donor requests a donation statement from the Donau} \label{fig:donau_flow_submit_receipt}
 \end{figure}
 
 \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 format.
 
 \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=0.5\textwidth]{db_physical_model}
 \caption{Donau database model (generated by \url{https://dbdiagram.io/})} \label{fig:db_physical_model}
 \end{figure}
 \subsubsection{\tt 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{\tt 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 Schnorr 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{\tt 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{\tt 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{\tt receipts\_submitted}
 Contains all submitted donation receipts sent to the Donor. By storing the
 signature \texttt{donation\_unit\_sig}, the idempotence 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 (called
 $\DI$ in Section~\ref{technical}).
     \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{\tt 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}
 
 \subsection{Android Verification App}\label{android_verification_app}
 The Android app is part of the verification process used by the tax authority
 to check the donation statement (see
 section~\ref{donor_sends_final_statement_to_a_validator}).
 The app decodes the submitted QR code from the donor,
 parses the signed values and the signature,
 and uses them to verify the signature.
 The arguments of the QR code are defined in section~\ref{donor_sends_final_statement_to_a_validator}
 and encoded as colon-delimited base64 values:
 
 \begin{verbatim}
     YEAR:TOTALAMOUNT:TAXID:TAXIDSALT:ED25519SIGNATURE
 \end{verbatim}
 
 Finally, the values and the verification result are displayed.