commit 32bf86cfd56bd0171eb32268564c7c475906eee8
parent c6f7f99afac1ea174f4d4935dfbf3362fe9af066
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Wed, 2 Jul 2025 15:02:17 +0200
comments and edits on donau RFC
Diffstat:
| M | draft-donau.xml | | | 149 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
1 file changed, 104 insertions(+), 45 deletions(-)
diff --git a/draft-donau.xml b/draft-donau.xml
@@ -12,6 +12,7 @@
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC9498 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.9498.xml">
<!ENTITY RFC7748 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.xml">
+<!ENTITY RFC8905 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8905.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- SEE ALSO: https://docs.taler.net/core/taler-uri.html -->
@@ -59,7 +60,7 @@
</address>
</author>
- <date day="30" month="September" year="2024" />
+ <date day="30" month="June" year="2025" />
<!-- Meta-data Declarations -->
<area>General</area>
@@ -71,17 +72,39 @@
<t>
This document defines the 'donau' Uniform Resource Identifier (URI) scheme
for triggering interactions with a validator for Donau donation
- statement.
+ statements.
</t>
<t>
This URI scheme allows applications to trigger interactions
- with a Donau validator. The Donau validator will receive URIs
- representing cases of taxpayers asking for their spending on
- charities to be recognized by the tax authority. The
- verification of the validity is triggered by this URI, it is
- done by a Donau validator that verifies if a given Donau
- donation statement is valid.
+ with a Donau validator. A Donau validator is typically run by
+ a tax authority to validate tax records from citizens that
+ made donations to a charity that supports the Donau protocol.
+ The Donau validator will receive 'donau' URIs representing the
+ sum of donations a taxpayer made to recognized charities over
+ a year. Donors would submit 'donau' URLs (or QR codes with
+ 'donau' URLs) to tax authorities to have their donations
+ recognized by the tax authority as tax-deductable
+ expenditures. The application logic to verify the validity of
+ the donation is triggered by 'donau' URIs. The validator
+ application would then typically confirm to the tax official
+ the validity of the signature encoded in the URI and show the
+ total amount donated as well as the taxpayer identification
+ number and the year of the donation. Multiple URIs could be
+ submitted per donor, and the application can correctly
+ determine which submissions are cummulative and which ones are
+ redundant.
+ </t>
+
+ <t>
+ This specification only covers the syntax of the 'donau' URI
+ scheme and excludes details on the protocol(s) that would
+ allow tax payers to donate to recognized charities to obtain
+ these suitable signed donation statements. While a
+ privacy-preserving protocol to obtain such statements exists
+ within the context of the GNU Taler protocol suite, other
+ protocols could be developed in the future and still yield
+ compatible 'donau' URIs as the URI scheme is reasonably generic.
</t>
</abstract>
@@ -100,12 +123,11 @@
<t>
A 'donau' URI always instructs a Donau validator to perform the
validation of a Donau donation statement.
- A 'donau' URI consists of the reference to a specific taxpayer for a
- given year plus optional parameters.
-</t>
-<t>
- Optional parameters can be the amount donated by the tax payer or
- the signature of the Donau donation statement.
+ A 'donau' URI consists of the reference to a the authority
+ that signed the statement, an identifier for the specific taxpayer,
+ the year of the donation, a salt and optional parameters.
+ Optional parameters include the amount donated by the
+ tax payer and the signature of the Donau donation statement.
</t>
</section>
<section title="Requirements Language">
@@ -128,16 +150,18 @@
<figure>
<artwork type="abnf"><![CDATA[
donau-URI = ("donau://" / "DONAU://" / "donau+http://" / "DONAU+HTTP://" )
- host "/" year "/" taxid [ "?" opts ]
+ host "/" year "/" taxid [ "?" ["amount=" amount "&sig=" algo ":" signature ]
host = ALPHA *( ALPHA / DIGIT / "-" / "." )
year = DIGIT DIGIT DIGIT 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 / "="
+ amount = currency ":" unit [ "." fraction ]
+ currency = 1*ALPHA
+ unit = 1*(DIGIT)
+ fraction = 1*(DIGIT)
+ salt = *(DIGIT)
+ algo = "ED25519"
+ signature = *(ALPHA / DIGIT)
]]>
</artwork>
</figure>
@@ -159,7 +183,24 @@
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
specific for each wallet, allowing a tax payer to have many Donau
- donation statements for the same year.
+ donation statements for the same year that should be treated as
+ cummulative by the validator application. The salt can also be
+ used to obfuscate the taxpayer ID in the donation protocol.
+
+ The amount follows the syntax from <xref target="RFC8905"/> and
+ represents the maximum amount donated in this year by the given
+ taxpayer with the given salt. Thus, given multiple 'donau' URIs
+ with the same salt, the maximum amount should be used, while
+ the amounts from 'donau' URIs with different salts should be
+ added.
+
+ Finally, algo specifies the specific signature algorithm
+ used; for now,
+ only ED25519 (see <xref target="RFC7748" />) is supported.
+ The signature using the specified algorithm must be
+ made over the information above (see <xref target="signature">)
+ and MUST be encoded using the Base 32 U Crockford encoding
+ scheme <xref target="base32-U-crockford"/>.
The default operation of applications that invoke a URI with the
Donau scheme MUST be to launch a Donau validator (if
@@ -171,26 +212,28 @@
with.
An application SHOULD allow dereferencing a "donau://" URI even
- if the action of that URI is not registered in the "Donau URI
- Actions" sub-registry.
+ if the action of that URI is not registered in the "Donau URI
+ Actions" sub-registry.
Donau-validators seeing a "donau://" URI MUST use HTTP over TLS when talking
- to the respective network service.
- Donau-validators seeing a "donau+http://" URI MUST use HTTP without TLS when talking
- 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>
+ to the respective network service.
+ Donau-validators seeing a "donau+http://" URI MUST use HTTP without TLS when talking
+ to the respective network service. Donau-validators SHOULD support
+ "donau+http://"-URIs only when run in developer or debug mode.
+ Validators would contact the host to obtain the public key
+ used for the signature. The host domain SHOULD also be shown to the
+ user to indicate which authority issued the proof of donation.
+ Alternatively, specific validation apps MAY only accept 'donau'
+ URLs from a specific set of hard-coded authorities and simply display
+ an error message when given 'donau' URLs from other authorities.
+
+ </t>
</section>
<section anchor="examples" title="Examples">
<figure>
<artwork><![CDATA[
- donau://example.com/2023/1319024730366/2998389878787879887?total=EUR:100
- donau://example.com/2023/1319024730366/2998389878787879887?total=EUR:100&signature=SHA256:RSA2048:3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G
+ donau://example.com/2025/1319024730366/2998389878787879887EUR:100/ED25519=3BBW6N8PVDYBRT0DERT8YYARQGFYHVQFG3WVAN1D58FRP5JG3M4G
]]>
</artwork>
</figure>
@@ -210,11 +253,11 @@
<t>
If signature and amount are available, then the verification
application will verify
- that the signature is valide for the server key (see <xref
+ that the signature is valid for the server key (see <xref
target="get-server-keys"/> to get the key).
</t>
<t>
- If one of both is missing, the application MUST download them from
+ If both are missing, the application MUST download them from
the get donation statement endpoint <xref target="get-donation-statement"/>.
</t>
@@ -222,27 +265,30 @@
<section anchor="get-server-keys" title="Access the Donau server public
keys">
<t>
- The verification app MUST have the EdDSA signing public key
+ The verification app MUST have a signing public key
corresponding to the host for the given year. The key MAY be retrieved from a
cache. If no key for this host and this year is available in the
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
+ The verification app SHOULD cache downloaded signing
public keys for the current year.
</t>
<t>
<list style="symbols">
<t>Name: /keys</t>
<t>Example request: GET https://donau.example.com/keys</t>
-<t>Example response: XXXXXXXXXXXXXXXX</t>
+<t>Example response: {"signkeys":["stamp_start":{"ts_s":42},"stamp_expire":{"ts_s":43},"key":"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>
+ FIXME-EB: formalize the above better ;-), like with /donation-statement.
+
+ Each of the "signkeys" is valid between "stamp_start" and
+ "stamp_expire" and the public "key" returned is encoded using Base 32
+ U Crockford encoding <xref target="base32-U-crockford"/>.
+ </t>
</section>
<section anchor="get-donation-statement" title="Get donation statement
@@ -270,6 +316,10 @@ target="base32-U-crockford"/>.
<t>References: [this.I-D]</t>
</list>
+FIXME-EB: why here 'total' and 'amount' in the URL? Use 'total' in both cases for consistency?
+FIXME-EB: why return 'pub'? Seems redundant!
+FIXME-EB: maybe return 'algo' also in /keys?
+
Servers implementing the donation-statement endpoint MUST respect the
following syntax, all three fields (total-field, sig-field, pub-field) MUST be included.
@@ -337,14 +387,20 @@ Example of an element of USD 100.00 :
The verification MAY be done with the following instructions
- The data to be confirmed is composed of the following information
- :
+ The data to be confirmed is composed of the following information:
<ul>
<li>The value 1500 written
in the network order on an 64 bit long unsigned integer.</li>
+ FIXME-EB: that's not how we do numbers in Taler for signatures.
+ We have first 64 bits value (in big endian), then 32 bits
+ for the fraction in 1/100000000th of the base unit (in big endian)
+ followed by 12 bytes for the currency, of which the last byte
+ must be a 0-terminator.
<li>The size of the confirmation to verify (also in network order).</li>
<li>The year on a 64 bit long unsigned integer in network order.</li>
+ FIXME-EB: this should include hashing over the salt, not just the taxpayer
+ ID and thus needs to be elaborated on how exactly this is hashed.
<li>The SHA256 hash code for the donor ID.</li>
</ul>
@@ -374,7 +430,8 @@ Example of an element of USD 100.00 :
]]></artwork>
</figure>
-
+ FIXME-EB: we'll need test vectors for this in an appendix!
+
</section>
<section anchor="signature-verification" title="Signature verification for a donation statement">
<t>
@@ -479,6 +536,8 @@ Value Encoding Value Encoding Value Encoding Value Encoding
&RFC7748;
+ &RFC8905;
+
</references>
