[lsd0013] branch master updated: adding syntax for the donation statement JSON from the server.

[Admin]

This is an automated email from the git hooks/post-receive script.

emmanuel-benoist pushed a commit to branch master
in repository lsd0013.

The following commit(s) were added to refs/heads/master by this push:
     new 722c101  adding syntax for the donation statement JSON from the server.
722c101 is described below

commit 722c101a0ca9d4fd86f2586756ee3c2411f815e4
Author: Emmanuel Benoist <emmanuel.benoist@bfh.ch>
AuthorDate: Wed Jun 4 16:27:33 2025 +0200

    adding syntax for the donation statement JSON from the server.
---
 draft-donau.xml | 162 ++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 117 insertions(+), 45 deletions(-)

diff --git a/draft-donau.xml b/draft-donau.xml
index 4f810f2..526f7c6 100644
--- 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>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.