The 'donau' URI scheme for validation of Donau donation statements.
Bern University of Applied SciencesHöheweg 80Biel/Bienne2501CHchristian.grothoff@bfh.chBern University of Applied SciencesHöheweg 80Biel/Bienne2501CHemmanuel.benoist@bfh.chBern University of Applied SciencesHöheweg 80Biel/Bienne2501CHbohdan.potuzhnyi@bfh.chTaler Systems AG7, rue de MondorfErpeldange5421LUdold@taler.net
General
Independent Streamtaxation
This document defines the 'donau' Uniform Resource Identifier (URI) scheme
for triggering interactions with a validator for Donau donation
statements.
This URI scheme allows applications to trigger interactions
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-deductible
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 cumulative and which ones are
redundant.
This specification only covers the syntax of the 'donau' URI
scheme and excludes details on the protocol(s) that would
allow taxpayers 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.
The validation tool will be registered for all donau:// URIs.
Since each taxation authority will typically use a different
domain, it will not be feasible to encode all the
domains of tax authorities servers inside the validation tool.
Hence a new URI scheme is needed that will trigger the validation
tool for any domain name.
Introduction
This document defines the 'donau' Uniform Resource Identifier (URI)
scheme for triggering interactions with
Donau validators.
Objective
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 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 total amount donated by the
taxpayer and the signature of the Donau donation statement.
This specification is based on the Bachelor Thesis of
Casaburi and Matya presenting the
solution and the first implementation of a Donau system.
Requirements Language
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP 14
when, and only when,
they appear in all capitals, as shown here.
Syntax of a 'donau' URI
This document uses the Augmented Backus-Naur Form (ABNF) of .
Semantics
Even if RFC3986 explicitly writes that scheme names
are case-insensitive, lower and upper case variations are presented here to
emphasize this possibility. The applications encoding URI in a QR-code can
benefit from the possibility to encode the URI using only uppercase letters
which should result in a more compact encoding.
The base of a Donau URI refers to the base URL of the Donau REST API.
It consists of the network location (host name or IP address) and MAY include
additional path segments (for example, https://admin.ch/taxes/donau/)
mapping to the Donau deployment behind reverse proxies. Validators MUST NOT
assume a specific domain naming convention or pattern
(such as donau.example) and
MUST accept bases with or without additional path components.
The year of a Donau URI refers to the year when the donations
have been done.
The taxid of a Donau URI refers to the taxid of the person that
did the donations and asks for their Donau donation statement to
be verified. The format of the taxid is specific for each tax authority.
The taxid is conveyed in the URI as a percent-encoded query parameter as
per . Implementations MUST decode taxid-enc
by applying percent-decoding to obtain the exact UTF-8 bytes of the tax identifier
before any processing. In particular, the character '/' MUST be percent-encoded
as %2F if present in a tax identifier.
The salt of a Donau URI refers to information used by a
wallet application to generate the Donau donation statement.
This salt is wallet-specific. As taxpayers MAY
use multiple wallets, tax authorities SHOULD
allowing a taxpayer to supply multiple Donau
donation statements for the same year. If the salts
are different, these should be treated as
cumulative by the validator application. The salt
SHOULD also used to obfuscate the taxpayer ID
in the donation protocol.
The total follows the syntax from 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 total amount should be used, while
the total amounts from 'donau' URIs with different salts should be
added.
Finally, algo specifies the specific signature algorithm
used; for now,
only ED25519 (see ) is supported.
The signature using the specified algorithm MUST be
made over the information above (see )
and MUST be encoded using the Base 32 U Crockford encoding
scheme .
The default operation of applications that invoke a URI with the
Donau scheme MUST be to launch a Donau validator (if
available). If no Donau validator is available, an application
SHOULD show a QR code with the content of the URI.
If multiple
Donau validators are registered, the user SHOULD be able to choose
which application to launch. This allows users with multiple
validators to choose which validator to perform the operation
with.
Validators MUST use HTTP over TLS when processing a "donau" URI.
Validators MUST use HTTP without TLS when processing a "donau+http" URI.
The base origin SHOULD 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.
ExamplesVerification of a Donau URI
The verification requires the Donau verification application to test
if a given taxpayer is entitled to a tax reduction.
For doing this, the Donau verification application must
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 total are available, or at least one is not available.
If signature and total are available, then the verification
application MUST verify
that the signature is valid for the server key (see to get the key).
If either or both are missing, the application MUST download them from
the get donation statement endpoint .
Obtaining Donau Server Public Keys
The verification app MUST obtain the signing public key
corresponding to the base for the given year.
The key MAY be retrieved from a
cache. If no key for this base and this year is available in the
cache, the verification app MUST download the key from the
base. The Donau server MUST provide the key at the /keys
endpoint. If the key is not available, no verification can take place
and the validator MUST return an appropriate error.
The verification app SHOULD cache downloaded signing
public keys for the current year.
Endpoint: /keys
Method: GET
Syntax: base/keys
Syntax response: defined hereunder
References: [this.I-D]
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 .
Example, a response to a GET request to the /keys endpoint.Donation Statement Retrieval
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 base.
The verification app MUST compute the hash of the donor
taxpayer ID hash-donor-id using SHA-512
over the exact UTF-8 bytes of the taxpayer ID string, followed by a single
NUL byte (0x00), followed by the salt string, followed by a final NUL byte (0x00):
hash-donor-id = SHA-512(taxid || 0x00 || salt || 0x00).
Here, taxid is the UTF-8 string obtained by percent-decoding the taxid-enc path segment.
The verification app MUST contact the
base at the endpoint /donation-statement with the year and hash-donor-id.
The hash of the donor taxpayer ID hash-donor-idMUST be encoded
using Base 32 U Crockford
encoding .
Servers implementing the donation-statement endpoint
MUST respect the
following syntax; all three fields (total-field, sig-field, pub-field) MUST be included.
The total 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).
Example of an element of USD 100.00 :Verification if Signature and Total are Available
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 total and the signature from the
base using the GET /donation-statement endpoint . Otherwise, it SHOULD use the
value given in the URI.
The verification of the signature is done using EdDSA as
specified in .
The verification MAY be done with the following instructions.
The signed data is the concatenation of the following fields
in network byte order (big-endian):
size (4 bytes): 32-bit unsigned integer with the total length of the signed data in bytes.
purpose (4 bytes): 32-bit unsigned integer with the constant value 1500.
total value (8 bytes): integer part as an unsigned 64-bit integer.
total fraction (4 bytes): fractional part as an unsigned 32-bit integer in units of 1/100000000.
currency (12 bytes): ASCII string, left-aligned with zero-padding on the right to 12 bytes.
hash of donor taxpayer ID (64 bytes): hash-donor-id = SHA-512( UTF-8(taxid) || 0x00 || UTF-8(salt) || 0x00 ).
year (4 bytes): 32-bit unsigned integer (the donation year).
Creating Donation Statement Signatures
The server signing the donation statement MUST use the Sign(d,message) procedure implemented as defined in .
The signature over the public key covers a 32-bit pseudo header
conceptually prefixed to the donation data fields.
The wire format is illustrated
in .
The Format for Creating Donation Statement Signatures
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
| SIZE | PURPOSE (1500) |
+-----+-----+-----+-----+-----+-----+-----+-----+
| TOTAL value |
+-----+-----+-----+-----+-----+-----+-----+-----+
| TOTAL fraction | CURRENCY |
+-----+-----+-----+-----+ +
| |
+-----+-----+-----+-----+-----+-----+-----+-----+
| SHA512 of the donor ID |
/ /
/ /
+-----+-----+-----+-----+-----+-----+-----+-----+
| YEAR |
+-----+-----+-----+-----+
SIZE:
A 32-bit value containing the length of the signed data in bytes
in network byte order.
PURPOSE:
A 32-bit signature purpose flag in network byte order. The value of this
field MUST 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 .
TOTAL value:
The integer part of the total value.
Unsigned integer containing the integer part of the value for the total.
It is represented using a 64 bit value (in big endian).
TOTAL fraction:
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.
TOTAL currency
A string representing the currency. ASCII, left-aligned and zero-padded to exactly 12 bytes.
HASH:
The SHA512 hash code for the donor ID.
YEAR:
The year on a 32 bit unsigned integer in big endian.
Validating Donation Statement Signatures
The signature verification step is taking the data presented in the
figure as input.
The signature MUST be verified using the EdDSA scheme described in
the procedure is
Verify(zk,message,signature).
Public key and signature, which are
encoded in Base 32 U Crockford in the URL,
MUST first be decoded to obtain the
respective binary value.
The Sign(d,message) and Verify(zk,message,signature) procedures MUST
be implemented as defined in .
Base 32 Representation of Binary Data
All binary data MUST be encoded to be transmitted. For encoding, one
MUST use the Base32 U Crockford encoding. This is a variation of the
base32 encoding . This encoding is presented
in detail in the appendix of the RFC for GNU Name System
The encoding works similarly to the standard, but uses another Base 32
Alphabet. The new alphabet is given in the Table , below.
The Base 32 Encoding Alphabet.
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 , below.
System reading a UMUST evaluate it as a V.
The Base 32 Decoding Alphabet.Security Considerations
Donau validators SHOULD support
"donau+http://"-URIs only when run in developer or debug mode
as otherwise the integrity and authenticity of the public key
cannot be assured.
Running "donau+http://"-URIs on a production server
MUST NOT be permitted, since it would be a security issue.
This scheme is intended only for testing purposes,
for instance on localhost.
Validator applications MUST include protections
against repeated validations of the same donation statement
with the same salt and year. Specifically, when summing up
multiple donation statements for the same taxpayer and
tax year, the MUST keep enough state to add
up the maximum total amounts per salt if multiple donation
statements are submitted with the same salt.
IANA Considerations
IANA maintains the "Uniform Resource Identifier (URI) Schemes"
registry that contains an entry for the 'donau' URI scheme. IANA is
requested to update that entry to reference this document when
published as an RFC.
Scheme name:
donau
Status:
provisional
URI scheme syntax:
See of [This.I-D].
URI scheme semantics:
See of [This.I-D].
Applications/protocols that use this scheme name:
GNU Taler
Contact:
<grothoff@gnu.org>
Change controller:
<grothoff@gnu.org>
References:
See of [This.I-D].
Normative ReferencesInformational ReferencesGNUnet Assigned Numbers Authority (GANA)GNUnet e.V.Tax-deductable Privacy-Preserving DonationsBern University of Applied Science, Bachelor ThesisBern University of Applied Science, Bachelor ThesisAppendix. Test Vector: Verify from URI
This appendix shows how to verify a donation statement starting from a
received URI. Public key is fetched from the Donau base.
Verification steps:
Verification (expected): call crypto_sign_verify_detached(sig, M, 100, pubkey). The result MUST indicate a valid signature for this vector.
Negative check (optional): flip one bit of M or sig and repeat; verification MUST fail.
Acknowledgements
The authors thank Ted Hardie for his comments on an earlier version of the draft.
This work was funded in part by the European Commission through the
Horizon Europe program under project number 101135475 (TALER). It also
has received funding from the Swiss State Secretariat for Education,
Research and Innovation (SERI).