commit 349fa10bb5cf2f9d827127868b2406b324c31de1
parent cd541c473834235478cdc96e30520c4d3f89bce5
Author: Matyja Lukas Adam <lukas.matyja@students.bfh.ch>
Date: Fri, 7 Jun 2024 12:06:55 +0200
add JSON examples
Diffstat:
3 files changed, 96 insertions(+), 13 deletions(-)
diff --git a/doc/thesis/chapters/implementation/donau.tex b/doc/thesis/chapters/implementation/donau.tex
@@ -11,7 +11,50 @@ The \texttt{GET /keys} request returns all valid donation unit public keys offer
%TODO
The following is an example response of a \lstinline{curl 127.0.0.1:8080/keys} command.
\begin{lstlisting}
- response
+{
+ "version": "0:0:0",
+ "base_url": "http://localhost:8080/",
+ "currency": "EUR",
+ "signkeys": [
+ {
+ "stamp_start": {
+ "t_s": 1717069556
+ },
+ "stamp_expire": {
+ "t_s": 1718279156
+ },
+ "key": "CFV2PY8164E231XZSQK30K8R6CBQ83DK2GSC2CXMKSA1YAK6Z6R0"
+ },
+ {
+ ...
+ }
+ ],
+ "donation_units": [
+ {
+ "donation_unit_pub": {
+ "cipher": "RSA",
+ "rsa_public_key": "020000YC7XK99SYSVFMAM6ANFECMQSK8ASBW4MFNTE9QWVBYPVX76DQBK14CDJPE1HC12NMXWWWSGKC0W93ZXV
+ 2JBB6A2TSHXPJCWA4FQ19M967PZ3YZP1M8PA71GDGMME7K2SSXSW9GJ9038NJP4D04FGD94AATPFWEM1J9Y1PYB
+ X140THJSSA0VNEDANQ2Q8ARJN09D2M0F8M5KN9G2001"
+ },
+ "year": 2024,
+ "lost": false,
+ "value": "EUR:5"
+ },
+ {
+ "donation_unit_pub": {
+ "cipher": "CS",
+ "cs_public_key": "7SKRQGBSEPBG24TC2PGXWEBVXHE579ZZBN8CAX6XGCHNSDKE4V9G"
+ },
+ "year": 2024,
+ "lost": false,
+ "value": "EUR:1"
+ },
+ {
+ ...
+ }
+ ]
+}
\end{lstlisting}
\subsubsection{\texttt{/charities}}
@@ -51,7 +94,7 @@ To insert a charity a POST request can be sent using \lstinline{curl -d @charity
}
\end{lstlisting}
-The response includes the charity ID generated by the database.
+The response consists of the charity ID generated by the database.
\begin{lstlisting}
{
"charity-id": 1
@@ -61,7 +104,6 @@ The response includes the charity ID generated by the database.
\subsubsection{\texttt{/batch-issue}}
-%TODO describe BUDI, donation unit -> glossary?
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).
\begin{figure}[ht]
@@ -70,13 +112,35 @@ Only recognized charities are allowed to request issue receipts for their donors
\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} request.
+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]
- json
+{
+ "budikeypairs": [
+ {
+ "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED01235X3XNEFK3WTSF00NDW9G3NJ3BTFMWTTMC5CR0774CCFRGBMAK46JPPDVYKX2G76R8GSAYZ5470DA5T30",
+ "blinded_udi": {
+ "cipher": "RSA",
+ "rsa_blinded_identifier": "AXPTEE24W28S9XNKB4KNTN5N4C25FG869GT6FQ5S8H3MDYJYRNFJB7MG6VEXQTWQ5QSEYGDK255EF6ATCQRSDM70JVTSQ7X6W5P6VND4GGP08ET48S47REG98A4TM972KPBQG25YDYZFCTB6854P6JQ0W10SEPHF66T2WCY9FJ9ZG99R364CXWAW79S8BCH758756V53C5HAR"
+ }
+ }
+ ],
+ "charity_sig": "JEJ0QMDXD416XKSK1SG0DETJEHEMPRY2X4TD80FT4EA0ZQSBADBM1RFB9T7N4F8XQKPW80EQMEDGBM592PMVDJ31PJC0YR0XF87EP28",
+ "year": 2024
+}
\end{lstlisting}
\begin{lstlisting}
- response
+{
+ "blind_signatures": [
+ {
+ "blinded_signature": {
+ "cipher": "RSA",
+ "blinded_rsa_signature": "16XHNWSCDRVKHFVH47NF8RGNYY5SB02FWSS5G8762C77RP9SK2RBRJT95SA4YV1A7PDX5T1D0R060KPHHTD1ZRV5CJHBNA50GD6RJ1RREYFPVJ13YP4XFV061YDKD3YMB9N3WTFAQPZ82ZBNR9YX8V47G6X7BHX9ZVC0NG9YHXB7PRNNPJSF0VNDR5T3B9RXC5ZTND5PSB8RW"
+ }
+ }
+ ],
+ "issued_amount: "EUR:15"
+}
\end{lstlisting}
\subsubsection{\texttt{/batch-submit}}
@@ -91,16 +155,35 @@ Even the donation statement will not be returned after a submit request, a donat
%\caption{flow chart submit receipt} \label{fig:donau_flow_submit_receipt}
\end{figure}
-%TODO
-The following is an example response of a \lstinline{curl -d @submit.json -X POST http://127.0.0.1:8080/batch-submit} request.
+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 a HTTP 201 status code with an empty response.
+
\begin{lstlisting}[title=submit.json]
- json
+{
+ "h_donor_tax_id": "N2NYR2SFNGZSS388R2SB0VKNWP8VCYJWQ93WR3RCCS38Y7DPPQEVEN31PNZA3RBZ3TWGPRQ6SAF1SMJ93S1R55R95271Y7TS5F5E388",
+ "donation_year": 2024,
+ "donation_receipts": [
+ {
+ "h_donaton_unit_pub": "130C2KDHTAFDQFB8XED01235X3XNEFK3WTSF00NDW9G3NJ3BTFMWTTMC5CR0774CCFRGBMAK46JPPDVYKX2G76R8GSAYZ5470DA5T30",
+ "nonce": "JEQC39G",
+ "donation_unit_sig":
+ {
+ "cipher": "RSA",
+ "rsa_signature": "GQBXPNE4JT5W53T3CVP6EAKD60XQZ75VJSJSKMNDRZA0Z00ZTC0BX6NWWRK9P7TZWZ3SFFE9B8PP1469SRQDABDNQM188CMP179VVEDMC8AAKZ3WTVC6QH58N9K9HJ6S34M405G0951GM750N4GGVMQXVTQ9VTZ006F2FXJ7655ZPNQ3KA32C1F6KXWHATSWGCJ051XJ30232"
+ }
+ }
+ ]
+}
\end{lstlisting}
+The following is an example response of a \lstinline{curl http://127.0.0.1:8080/donation-statement/2024/N2NYR2SFNGZSS388R2SB0VKNWP8VCYJWQ93WR3RCCS38Y7DPPQEVEN31PNZA3RBZ3TWGPRQ6SAF1SMJ93S1R55R95271Y7TS5F5E388} request.The last parameter of the URL is the salted and hashed tax id.
+
\begin{lstlisting}
- response
+{
+ "total": "EUR:15",
+ "donation_statement": "C1JVDP25AR001W5AHMAZRZR000RAS38NZHZG007R57XWF7BZ0004602ZAN9JWNAM8RPKG04XFW000C5CHMAZRZR0000AH9WF88K56NR",
+ "donau_pub": "63f62b7901311c2187bfcde6304d183317740db31432c133b49e541f2a66f9b0"
+}
\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 the chapter xx Donau REST API.
diff --git a/doc/thesis/include/glossary.tex b/doc/thesis/include/glossary.tex
@@ -3,7 +3,7 @@
\newglossaryentry{Donau}
{
name=Donau,
- description={The name of our project, short for donation authority}
+ description={Short for donation authority. Donau is used as project name. The hole system is called Donau system and the Server of the tax authority is also called Donau.}
}
\newglossaryentry{Taler}
@@ -57,7 +57,7 @@
\newglossaryentry{BKP}
{
name=BKP,
- description={Blinded unique donor identifier key pair, result of adding the corresponding hash of the DU public key to the BUDI}
+ description={Blinded unique donor identifier key pair, a tuple of the corresponding hash of the DU public key and the BUDI}
}
\glsaddall
diff --git a/doc/thesis/thesis.pdf b/doc/thesis/thesis.pdf
Binary files differ.
