commit 722c101a0ca9d4fd86f2586756ee3c2411f815e4
parent f3f863e3ee43855e9091bfa7d1237f23cf9852ea
Author: Emmanuel Benoist <emmanuel.benoist@bfh.ch>
Date: Wed, 4 Jun 2025 16:27:33 +0200
adding syntax for the donation statement JSON from the server.
Diffstat:
| M | draft-donau.xml | | | 162 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------- |
1 file changed, 117 insertions(+), 45 deletions(-)
diff --git a/draft-donau.xml b/draft-donau.xml
@@ -115,7 +115,7 @@
</section>
<section anchor="syntax"
- title="Syntax of a 'taler' URI">
+ title="Syntax of a 'donau' URI">
<t>
This document uses the Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/>.
</t>
@@ -125,12 +125,13 @@
host "/" year "/" taxid [ "?" opts ]
host = ALPHA *( ALPHA / DIGIT / "-" / "." )
year = DIGIT DIGIT DIGIT DIGIT
- taxid = *( ALPHA / DIGIT / "-" )
+ taxid = *( ALPHA / DIGIT / "-" /".")
salt = *(DIGIT)
opts = opt *( "&" opt )
opt = opt-name "=" opt-value
opt-name = ALPHA *( ALPHA / DIGIT / "-" / "." / ":" )
opt-value = *pchar
+ pchar= ALPHA / DIGIT / "="
]]>
</artwork>
</figure>
@@ -147,7 +148,7 @@
The taxid of a Donau URI referes to the taxid of the person that
did the donations and asks for their Donau donation statement to
- be verified.
+ be verified. The format of the taxid is specific for each tax authority.
The salt of a Donau URI referes to the information used by the
Donau-wallet application to generate the Donau donation statement. This salt is
@@ -173,6 +174,9 @@
to the respective network service. Donau-validators SHOULD support
"donau+http://"-URIs only when run in developer or debug mode.
+ The optional parameters that are containing binary data (the
+ signature) MUST be encoded using the Base 32 U Crockford encoding
+ scheme <xref target=""base32-U-crockford"/>.
</t>
</section>
@@ -180,7 +184,7 @@
<figure>
<artwork><![CDATA[
donau://example.com/2023/1319024730366/2998389878787879887?total=EUR:100
- donau://example.com/2023/1319024730366/2998389878787879887?total=EUR:100&signature=3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G
+ donau://example.com/2023/1319024730366/2998389878787879887?total=EUR:100&signature=SHA256:RSA2048:3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G
]]>
</artwork>
</figure>
@@ -194,7 +198,15 @@
verify that the Donau-URI corresponds to a valid Donau donation
statement. The Donau verification application MUST verify the
validity of the donation statement. There are two possibilities:
- signature and amount are available or at least one is not available
+ signature and amount are available or at least one is not available.
+
+ If signature and amount are available, then the verification
+ application will directly generate the corresponding JSON and verify
+ that the signature is valide for the server key (see <xref
+ target="get-server-keys"/> to get the key).
+
+ If one of both is missing, the application MUST download them from
+ the get donation statement endpoint <xref target="get-donation-statement"/>.
</section>
@@ -207,8 +219,9 @@
cache, the verification app MUST download the key from the
host. The Donau server MUST provide the key at the /keys
entrypoint. If the key is not available, no verification can take place.
-
-
+
+ The verification app SHOULD store the already downloaded signing
+ public keys for the current year.
</t>
<t>
<list style="symbols">
@@ -217,6 +230,9 @@
<t>Example response: XXXXXXXXXXXXXXXX</t>
<t>References: [this.I-D]</t>
</list>
+
+The key returned is encoded using Base 32 U Crockford encoding <xref
+target="base32-U-crockford"/>.
</t>
</section>
@@ -233,6 +249,10 @@
concatenated binary data this produce the hash-donor-id. The verification app will contact the
host in the endpoint /donation-statement with the year and the hash-donor-id.
+ The hash-donor-id must be encoded using Base 32 U Crockford
+ encoding <xref target="base32-U-crockford"/>.
+
+
<list style="symbols">
<t>Endpoint: /donation-statement</t>
<t>Method: GET</t>
@@ -240,51 +260,100 @@
<t>Contact: N/A</t>
<t>References: [this.I-D]</t>
</list>
-
+
+Servers implementing the donation-statement endpoint MUST respect the
+following syntax, all three fields (total-field, sig-field, pub-field) MUST be included.
+
+The amount is a string formed first of the currency (in capital
+letters) then ":" and then the value (can be an integer or a decimal
+number).
+
+ <sourcecode>
+ <![CDATA[
+json-object = "{" ws field-list ws "}"
+
+field-list = field *(ws "," ws field)
+field = total-field / sig-field / pub-field
+
+; Allow any order of the three fields
+total-field = DQUOTE "total" DQUOTE ws ":" ws DQUOTE currency ":" value DQUOTE
+sig-field = DQUOTE "donation_statement_sig" DQUOTE ws ":" ws DQUOTE signature DQUOTE
+pub-field = DQUOTE "donau_pub" DQUOTE ws ":" ws DQUOTE signature DQUOTE ; same format as signature
+
+currency = 1*(%x41-5A) ; A-Z uppercase letters
+value = int / decimal
+int = ["-"] 1*DIGIT
+decimal = ["-"] 1*DIGIT "." 1*DIGIT
+
+signature = 1*(ALPHA / DIGIT / "=")
+
+; Common tokens
+ws = *WSP
+DQUOTE = %x22 ; "
+WSP = %x20 / %x09
+DIGIT = %x30-39
+ALPHA = %x41-5A / %x61-7A
+ ]]>
+ </sourcecode>
+
+
+
+Example of an element of USD 100.00 :
+ <sourcecode>
+ <![CDATA[
+{
+ total: "USD:100",
+ donation_statement_sig: "SIGNATURE",
+ donau_pub: "EDDSA_PUBLIC_KEY"
+}
+ ]]>
+ </sourcecode>
+
+
</t>
</section>
<section anchor="signature-amount-available" title="Signature and
Amount are available">
<t>
- The verification app MUST verify that the signature correspond to
+ The verification app MUST verify that the signature corresponds to
the claimed values.
- If the information is not in the URL, the verification app MUST download the amount and the signature from the
+ If the information is not in the URI, the verification app MUST download the amount and the signature from the
host using the GET /donation-statement/ endpoint <xref
- target="get-donation-statement"/>. Otherwise, it MAY verify it
+ target="get-donation-statement"/>. Otherwise, it SHOULD use the
+ value given in the URI.
The verification app MUST generate the JSON corresponding to the
- claim and validate the signature <xref target=""/>.
-
- The action "withdraw" is used to trigger a bank-integrated withdrawal operation.
- This means that the user has been interacting with some online banking App and
- wants to instruct the bank to transfer money from the user's bank account into
- a the GNU Taler wallet. The wallet now needs to allow the user to select the
- GNU Taler exchange, and then ultimately provide the bank with its
- reserve public key and await the completion of the wire transfer.
-</t>
-<t>
- The specific arguments are:
- <list style="symbols">
- <t>amount: currency code followed by the numerical amount, using
- dot as to separate the fractional part of the number. For example
- EUR:12.5 represents twelve euros fifty, GBP:1000 represents
- thousand british pounds. </t>
- <t>signature: the decimal number representing the binary value for
- the signature of the Donau donation statement.</t>
- </list>
-</t>
-<t>
-<list style="symbols">
-<t>Name: withdraw</t>
-<t>Syntax: taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid}{?external-confirmation=ext}</t>
-<t>Example: taler://withdraw/bank.example.com/wid</t>
-<t>Contact: N/A</t>
-<t>References: [this.I-D]</t>
-</list>
+ claim and validate the signature <xref
+ target="signature-verification"/> of this element.
+
+ The JSON contains the information of the URI or the ones that have
+ been downloaded.
+
+
+ Example of JSON string
+
+TODO FIX ME : what is that JSON STRING ??
+ <sourcecode>
+ <![CDATA[
+ {
+ kdfjlksdfkl : kkkjlkjkjlkjlkjl
+}
+ ]]>
+ </sourcecode>
+
</t>
</section>
+
+<section anchor="signature-verification">
+The signature versification step is taking the JSON as
+input. Signature MUST be verified using the EdDSA scheme described in
+<xref target="RFC8032"/>. Public key and signature that are given
+encoded in Base 32 U Crockford must first be decoded to get a binary
+out of it.
+</section>
+
<section anchor="base32-U-crockford" title="Base 32 representation of
binary data">
All binary data MUST be encoded to be transmitted. For encoding, one
@@ -311,7 +380,7 @@ Alphabet. The new alphabet is given in the Table <xref target="figure_base32_enc
</figure>
-To prevent OCR problems, a system decoding binary data encoded with base 32 U Crockford MUST
+To prevent optical character reading (OCR) problems, a system decoding binary data encoded with base 32 U Crockford MUST
accept the codes presented in the Table <xref target="figure_base32_decoding"/>, below. System reading a U
MUST evaluate it as a V.
@@ -319,15 +388,18 @@ MUST evaluate it as a V.
<figure anchor="figure_base32_decoding" title="The Base 32 Decoding Alphabet.">
<artwork name="" type="" align="left" alt=""><![CDATA[
Value Encoding Value Encoding Value Encoding Value Encoding
- 0 0 9 9 18 J|j 27 V|v|u|U
+ 0 0 9 9 18 J|j 27 V|v|u|U
1 1|i|I|l|L 10 A|a 19 K|k 28 W|w
- 2 2 11 B|b 20 M|m 29 X|x
- 3 3 12 C|c 21 N|n 30 Y|y
- 4 4 13 D|d 22 P|p 31 Z|z
+ 2 2 11 B|b 20 M|m 29 X|x
+ 3 3 12 C|c 21 N|n 30 Y|y
+ 4 4 13 D|d 22 P|p 31 Z|z
5 5 14 E|e 23 Q|q
- 6 6 15 F|f 24 R|r (pad) =
+ 6 6 15 F|f 24 R|r (pad) =
7 7 16 G|g 25 S|s
8 8 17 H|h 26 T|t
+ ]]></artwork>
+ </figure>
+
</section>
