commit 9f79ff8eb95ad9c8aaf532c907adab79b3c75936
parent a83785e3c2fb8e89d62c71766656b4ec5bd83611
Author: Emmanuel Benoist <emmanuel.benoist@bfh.ch>
Date: Fri, 11 Jul 2025 19:12:49 +0200
Definition of the data to be signed
Diffstat:
| M | draft-donau.xml | | | 100 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------- |
1 file changed, 75 insertions(+), 25 deletions(-)
diff --git a/draft-donau.xml b/draft-donau.xml
@@ -150,7 +150,7 @@
<figure>
<artwork type="abnf"><![CDATA[
donau-URI = ("donau://" / "DONAU://" / "donau+http://" / "DONAU+HTTP://" )
- host "/" year "/" taxid [ "?" ["amount=" amount "&sig=" algo ":" signature ]
+ host "/" year "/" taxid [ "?" ["total=" amount "&sig=" algo ":" signature ]
host = ALPHA *( ALPHA / DIGIT / "-" / "." )
year = DIGIT DIGIT DIGIT DIGIT
taxid = *( ALPHA / DIGIT / "-" /".")
@@ -187,8 +187,8 @@
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
+ The total follows the syntax from <xref target="RFC8905"/> and
+ represents the total 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
@@ -248,10 +248,10 @@
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 total are available or at least one is not available.
</t>
<t>
- If signature and amount are available, then the verification
+ If signature and total are available, then the verification
application will verify
that the signature is valid for the server key (see <xref
target="get-server-keys"/> to get the key).
@@ -365,7 +365,7 @@ Example, a response to a GET request to the /key/ endpoint.
<section anchor="get-donation-statement" title="Get donation statement
and signature">
<t>
- If the Donau-URI does not contain the amount or the signature, the
+ If the Donau-URI does not contain the total or the signature, the
verification app MUST download them from the /donation-statement/
endpoint of the host.<br/>
@@ -444,13 +444,13 @@ Example of an element of USD 100.00 :
</t>
</section>
-<section anchor="signature-amount-available" title="Signature and
- Amount are available">
+<section anchor="signature-total-available" title="Signature and
+ total are available">
<t>
The verification app MUST verify that the signature corresponds to
the claimed values.
- If the information is not in the URI, 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 total and the signature from the
host using the GET /donation-statement/ endpoint <xref
target="get-donation-statement"/>. Otherwise, it SHOULD use the
value given in the URI.
@@ -463,15 +463,13 @@ Example of an element of USD 100.00 :
The data to be confirmed is composed of the following information:
<ul>
+ <li>The size of the confirmation to verify written
+ in the network order on an 32 bit unsigned integer.</li>
<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>
+ in the network order on an 32 bit unsigned integer.</li>
+ <li>The total number is written in three fields. First the integer part of the value represented on 64 bit unsigned integer in big endian. Then comes the fractional part of the total value represented by a unsigned integer on 32 bit (also big endian) representing the number of 1/100000000th of the base unit. The third part is a 12 byte string (terminating with the 0x00 character) representing the currency of the total value.
+
+ <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>
@@ -486,23 +484,75 @@ Example of an element of USD 100.00 :
</t>
<figure anchor="figure_signature_data" title="The binary representation of the data to sign">
<artwork name="" type="" align="left" alt=""><![CDATA[
+
+]]></artwork>
+ </figure>
+
+
+
+ <t>
+ The signature over the public key covers a 32-bit pseudo header
+ conceptually prefixed to the EXPIRATION and BDATA fields.
+ The wire format is illustrated
+ in <xref target="figure_rrsigwithpseudo"/>.
+ </t>
+ <figure anchor="figure_rrsigwithpseudo">
+ <name>The Wire Format Used for Creating the Signature of the RRBLOCK</name>
+ <artwork name="" type="" alt="">
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
-| number 1500 /
+| SIZE | PURPOSE (1500) |
+-----+-----+-----+-----+-----+-----+-----+-----+
-/ size of the confirmation /
+| TOTAL value |
+-----+-----+-----+-----+-----+-----+-----+-----+
-/ Year /
+| TOTAL fraction | CURRENCY |
++-----+-----+-----+-----+ +
+| |
+-----+-----+-----+-----+-----+-----+-----+-----+
-/ SHA256 of the donor ID /
-/ /
+| SHA256 of the donor ID |
/ /
/ /
+-----+-----+-----+-----+-----+-----+-----+-----+
+| YEAR |
++-----+-----+-----+-----+
+ </artwork>
+ </figure>
+ <dl newline="false">
+ <dt>SIZE:</dt>
+ <dd>
+ A 32-bit value containing the length of the signed data in bytes
+ in network byte order.
+ </dd>
+ <dt>PURPOSE:</dt>
+ <dd>
+ A 32-bit signature purpose flag in network byte order. The value of this
+ field <bcp14>MUST</bcp14> be 1500. It defines the context in which
+ the signature is created so that it cannot be reused in other parts
+ of the protocol that might include possible future extensions.
+ The value of this field corresponds to an entry in the
+ GANA "GNUnet Signature Purposes" registry <xref target="GANA"/>.
+ </dd>
+ <dt>TOTAL value:</dt>
+ <dd>
+ The integer part of the total value. Unsigned integer containing the integer part of the value for the total. It is represented on 64 bits value (in big endian),
+ </dd>
+ <dt>TOTAL fraction:</dt>
+ <dd>
+ The fractional part of the total value is represented by an unsigned integer on 32 bits (also in big endian notation). It represents the fractional part of the value in 1/100000000th of the base unit.
+ </dd>
+ <dt>TOTAL Currency</dt>
+ A string representing the currency. 12 bytes for the currency as an string. The last byte
+ must be a 0-terminator.
+ </dd>
+ <dt>HASH:</dt>
+ <dd>The SHA256 hash code for the donor ID.</dd>
+ </dl>
+ <dt>YEAR:</dt>
+ <dd>The year on a 32 bit unsigned integer in big endian.</dd>
+ </dl>
+ </section>
-]]></artwork>
- </figure>
-
+
FIXME-EB: we'll need test vectors for this in an appendix!
</section>
