donau

Donation authority for GNU Taler (experimental)
Log | Files | Refs | Submodules | README | LICENSE

app-impl.tex (4005B)

      1 \section{Additional Details -- Implementation}\label{app-impl}
      2 
      3 This appendix describes the remaining implementation details such as APIs.
      4 
      5 \subsection{REST API}
      6 
      7 The detailed REST API specification of the Donau back-end is publicly
      8 available and will be submitted as artifact.
      9 The following are
     10 the main API endpoints:
     11 
     12 \subsubsection{\texttt{/keys}}
     13 The \texttt{GET /keys} request returns all valid donation unit public keys
     14 offered by the Donau, as well as the Donau's current EdDSA public signing key.
     15 The following is an example response of a \texttt{curl 127.0.0.1:8080/keys}
     16 command. Some parts of the following example responses are truncated (denoted by
     17 the three dots '\texttt{...}') to make them more readable.
     18 
     19 \begin{verbatim}
     20 {
     21 "version": "0:0:0",
     22 "base_url": "http://localhost:8080/",
     23 "currency": "EUR",
     24 "signkeys": [
     25   {
     26     "stamp_start": {
     27       "t_s": 1717069556
     28     },
     29     "stamp_expire": {
     30       "t_s": 1718279156
     31     },
     32     "key": "CFV2PY8164E231XZSQK30K8R6CBQ..."
     33   },
     34   {
     35   ...
     36   }
     37   ],
     38   "donation_units": [
     39   {
     40     "donation_unit_pub": {
     41       "cipher": "RSA",
     42       "rsa_public_key": "020000YC7XK99S..."
     43     },
     44     "year": 2024,
     45     "lost": false,
     46     "value": "EUR:5"
     47   },
     48   {
     49     "donation_unit_pub": {
     50       "cipher": "CS",
     51       "cs_public_key": "7SKRQGBSEPBG24..."
     52     },
     53     "year": 2024,
     54     "lost": false,
     55     "value": "EUR:1"
     56   },
     57   {
     58   ...
     59   }
     60   ]
     61 }
     62 \end{verbatim}
     63 
     64 \subsubsection{\texttt{/charities}}
     65 
     66 The following is an example response of a \texttt{curl 127.0.0.1:8080/charities} command.
     67 There is only one charity named \texttt{example} registered with a donation limit of 10 euros.
     68 
     69 \begin{verbatim}
     70 {
     71 "charities": [
     72   {
     73     "charity_pub": "ABETNXT9ZF606FRF3WD5...",
     74     "url": "example.com",
     75     "name": "example",
     76     "max_per_year": "EUR:10",
     77     "receipts_to_date": "EUR:0",
     78     "current_year": 2024
     79   }
     80 ]
     81 }
     82 \end{verbatim}
     83 
     84 To insert a charity a \texttt{POST} request can be sent using
     85 \texttt{curl -d @charity.json -X POST http://127.0.0.1:8080/charities}.
     86 
     87 The following is an example of a
     88 \texttt{charity.json} entry
     89 
     90 \begin{verbatim}
     91 {
     92 "charity_pub": "ABETNXT9ZF606FRF3WD5...",
     93 "charity_name": "mycharity",
     94 "charity_url": "mycharity.example.com",
     95 "max_per_year": "EUR:1000",
     96 "receipts_to_date": "EUR:0",
     97 "current_year": 2024
     98 }
     99 \end{verbatim}
    100 
    101 The response consists of the charity ID generated by the database.
    102 \begin{verbatim}
    103 {
    104 "charity-id": 1
    105 }
    106 \end{verbatim}
    107 
    108 
    109 \subsubsection{\texttt{/batch-issue}}
    110 
    111 The following is an example response of a \\
    112 \texttt{curl -d @issue.json -X POST http://127.0.0.1:8080/batch-issue/1}
    113 request showing a \texttt{issue.json} entry.
    114 The number at the end of the URL is the charity ID.
    115 
    116 
    117 
    118 \begin{verbatim}
    119 {
    120 "budikeypairs": [
    121 {
    122   "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED...",
    123   "blinded_udi": {
    124   "cipher": "RSA",
    125   "rsa_blinded_identifier": "AXPTEE24W28S9XN..."
    126   }
    127 }
    128 ],
    129 "charity_sig": "JEJ0QMDXD416XKSK1SG0DETJEH...",
    130 "year": 2024
    131 }
    132 \end{verbatim}
    133 
    134 \begin{verbatim}
    135 {
    136 "blind_signatures": [
    137   {
    138    "blinded_signature": {
    139    "cipher": "RSA",
    140    "blinded_rsa_signature": "16XHNWSCDRVKHF..."
    141     }
    142   }
    143 ],
    144 "issued_amount: "EUR:15"
    145 }
    146 \end{verbatim}
    147 
    148 \subsubsection{\texttt{/batch-submit}}
    149 
    150 \begin{verbatim}
    151 {
    152 "h_donor_tax_id": "N2NYR2SFNGZSS388R2SB0VK...",
    153 "donation_year": 2024,
    154 "donation_receipts": [
    155 {
    156   "h_donaton_unit_pub": "130C2KDHTAFDQFB8X...",
    157   "nonce": "JEQC39G",
    158   "donation_unit_sig":
    159   {
    160   "cipher": "RSA",
    161   "rsa_signature":  "GQBXPNE4JT5W53T3CVP6E..."
    162   }
    163 }
    164 ]
    165 }
    166 \end{verbatim}
    167 
    168 \subsubsection{\texttt{/donation-statement}}
    169 To obtain the donation statement, the donor submits a GET request for a specified year and taxpayer ID.
    170 
    171 The following is an example response of a \\
    172 \texttt{curl http://127.0.0.1:8080/donation-statement/$\backslash$} \\
    173 \hspace*{0.5cm} \ \texttt{2024/N2NYR2SFNGZSS388R2SB...} \\
    174 request.
    175 
    176 The last parameter of the URL is the \DI.
    177 
    178 \begin{verbatim}
    179 {
    180 "total": "EUR:15",
    181 "donation_statement": "C1JVDP25AR001W5AHMAZ...",
    182 "donau_pub": "63f62b7901311c2187bfcde6304d1..."
    183 }
    184 \end{verbatim}