commit a83785e3c2fb8e89d62c71766656b4ec5bd83611
parent 32bf86cfd56bd0171eb32268564c7c475906eee8
Author: Emmanuel Benoist <emmanuel.benoist@bfh.ch>
Date: Fri, 11 Jul 2025 11:17:32 +0200
Formal definition of get-server-keys
Diffstat:
| M | draft-donau.xml | | | 87 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------- |
1 file changed, 80 insertions(+), 7 deletions(-)
diff --git a/draft-donau.xml b/draft-donau.xml
@@ -276,18 +276,89 @@
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: {"signkeys":["stamp_start":{"ts_s":42},"stamp_expire":{"ts_s":43},"key":"XXXXXXXXXXXXXXXX"]}</t>
-<t>References: [this.I-D]</t>
-</list>
+
+ <list style="symbols">
+ <t>Endpoint: /keys</t>
+ <t>Method: GET</t>
+ <t>Syntax: /keys</t>
+ <t>Syntax response: defined hereunder</t>
+ <t>Contact: N/A</t>
+ <t>References: [this.I-D]</t>
+ </list>
+
+
+
- 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"/>.
+
+ <sourcecode>
+ <![CDATA[
+ ; Core JSON tokens (simplified; assumes standard JSON for strings, numbers, booleans, null, arrays, objects)
+JSONString = DQUOTE *(%x20-21 / %x23-5B / %x5D-10FFFF / "\" EscapedChar) DQUOTE
+UCrockford = *( ALPHA32 / "-" )
+ALPHA32 = DIGIT / LETTER
+DIGIT = %x30-39 ; 0-9
+LETTER = %x41-48 / %x4A-4E / %x50-5A / %x61-68 / %x6A-6E / %x70-7A
+JSONUCrockfordString = DQUOTE UCrockford DQUOTE
+EscapedChar = %x22 / %x5C / %x2F / %x62 / %x66 / %x6E / %x72 / %x74 /
+ "u" 4HEXDIG
+JSONNumber = [ "-" ] 1DIGIT *( DIGIT ) [ "." 1DIGIT *( DIGIT ) ]
+ [ ( "e" / "E" ) [ "+" / "-" ] 1DIGIT *( DIGIT ) ]
+JSONBool = "true" / "false"
+JSONNull = "null"
+JSONArray = "[" [ JSONException *( "," JSONException ) ] "]"
+JSONObject = "{" [ JSONMember *( "," JSONMember ) ] "}"
+JSONMember = JSONString ":" JSONException
+JSONException = JSONString / JSONNumber / JSONObject / JSONArray / JSONBool / JSONNull
+
+; Specific DonauKeysResponse structure
+DonauKeysResponse = "{"
+ JSONMemberSep
+ "}"
+JSONMemberSep = version , domain , base_url , currency , currency_fraction_digits ,
+ donation_units , signkeys
+
+version = DQUOTE "version" DQUOTE ":" JSONString
+domain = DQUOTE "domain" DQUOTE ":" JSONString
+base_url = DQUOTE "base_url" DQUOTE ":" JSONString
+currency = DQUOTE "currency" DQUOTE ":" JSONString
+currency_fraction_digits = DQUOTE "currency_fraction_digits" DQUOTE ":" JSONNumber
+EDDSAPubKey = JSONUCrockfordString
+SignKey = DQUOTE "key" DQUOTE ":" EDDSAPubKey
+donation_units = DQUOTE "donation_units" DQUOTE ":" "[" DonationUnitKeyGroup *( "," DonationUnitKeyGroup ) "]"
+signkeys = DQUOTE "signkeys" DQUOTE ":" "[" SignKey *( "," SignKey ) "]"
+
+DonationUnitKeyGroup = "{" cipher_field "," value_field "," donation_units_array "}"
+cipher_field = DQUOTE "cipher" DQUOTE ":" ( DQUOTE "RSA" DQUOTE / DQUOTE "CS" DQUOTE )
+value_field = DQUOTE "value" DQUOTE ":" JSONNumber
+donation_units_array = DQUOTE "donation_units" DQUOTE ":" "[" DUNK_UNIT_KEY *( "," DUNK_UNIT_KEY ) "]"
+
+; donation unit entries differ depending on cipher
+DUNK_UNIT_KEY = "{" base_fields "," key_specific "}"
+base_fields = DQUOTE "year" DQUOTE ":" JSONNumber [ "," DQUOTE "lost" DQUOTE ":" JSONBool ]
+key_specific = ( DQUOTE "rsa_pub" DQUOTE ":" JSONObject ) /
+ ( DQUOTE "cs_pub" DQUOTE ":" JSONString )
+
+SignKey = "{" DQUOTE "key" DQUOTE ":" JSONObject "," DQUOTE "year" DQUOTE ":" JSONNumber "}"
+ ]]>
+ </sourcecode>
+
+Example, a response to a GET request to the /key/ endpoint.
+ <sourcecode>
+ <![CDATA[
+ {"signkeys":
+ [ "stamp_start":{"ts_s":42},
+ "stamp_expire":{"ts_s":43},
+ "key":"XXXXXXXXXXXXXXXX"
+ ]
+ }
+ ]]>
+ </sourcecode>
+
+
</t>
</section>
@@ -319,6 +390,8 @@
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?
+RESPONSE-EB : I do not know, this is just https://docs.taler.net/core/api-donau.html
+
Servers implementing the donation-statement endpoint MUST respect the
following syntax, all three fields (total-field, sig-field, pub-field) MUST be included.
