1.12. The Donau RESTful API¶
The API specified here follows the general conventions for all details not specified in the individual requests. The glossary defines all specific terms used in this section.
1.12.1. API Overview¶
This is intended to provide a quick overview of the whole REST API. For a more detailed view of the protocol, see the protocol specification.
The chapters group the families of requests frequently encountered when using the Donau API:
Status information: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy
Issue receipts: For use by charities: Issue receipts for blinded unique donor ids.
Submit receipts: Receive the receipts and, if valid, add all of it’s donation units to the donor total. Returns a signature on the total yearly donation amount, hash of taxid+salt and year.
Charity administration and status information:
For use by administrators to add/modify a charity
For use by charities to get their remaining donation volume
1.12.2. Terms of service API¶
These APIs allow clients to obtain the terms of service and the privacy policy of a service.
- GET /terms¶
Get the terms of service of the service. The endpoint will consider the “Accept” and “Accept-Language” and “Accept-Encoding” headers when generating a response. Specifically, it will try to find a response with an acceptable mime-type, then pick the version in the most preferred language of the user, and finally apply compression if that is allowed by the client and deemed beneficial.
The endpoint will set an “Etag”, and subsequent requests of the same client should provide the tag in an “If-None-Match” header to detect if the terms of service have changed. If not, a “304 Not Modified” response will be returned. Note that the “304 Not Modified” will also be returned if the client changed the “Accept-Language” or “Accept-Encoding” header. Thus, if the client would like to download the resource in a different language or format, the “If-None-Match” header must be omitted.
If the “Etag” is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the terms of service were not configured correctly.
When returning a full response (not a “304 Not Modified”), the server should also include a “Avail-Languages” header which includes a comma-separated list of the languages in which the terms of service are available in (see availability hints specification). Clients can use this to generate a language switcher for users that may not have expressed a proper language preference.
- GET /privacy¶
Get the privacy policy of the service. Behaves the same way as The “/terms” endpoint, except that it returns the privacy policy instead of the terms of service.
1.12.3. Donau public keys and status information¶
This API is used by donors and charities to obtain global information about the Donau, such as online signing keys and available donation units. This is typically the first call any Donau client makes, as it returns information required to process all of the other interactions with the Donau. The returned information is secured by signature(s) from the Donau, especially the long-term offline signing key of the Donau, which clients should cache.
- GET /keys¶
Get a list of all donation units keys offered by the Donau, as well as the Donau’s current online signing key (used for donation statements).
Request:
Response:
- 200 OK:
The Donau responds with a DonauKeysResponse object. This request should virtually always be successful. It only fails if the Donau is misconfigured.
Details:
interface DonauKeysResponse { // libtool-style representation of the Donau protocol version, see // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; // Financial domain this Donau operates for. domain: string; // The Donau's base URL. base_url: string; // The Donau's currency. currency: string; // How many digits should the amounts be rendered // with by default. Small capitals should // be used to render fractions beyond the number // given here (like on gas stations). currency_fraction_digits: Integer; // Donation Units offered by this Donau donation_units: DonationUnitKeyGroup[]; // The Donau's signing keys. signkeys: SignKey[]; }
type DonationUnitKeyGroup = | DonationUnitKeyGroupRsa | DonationUnitKeyGroupCs;
interface DonationUnitKeyGroupRsa extends DonationUnitKeyGroupCommon { cipher: "RSA"; donation_units: ({ rsa_pub: RsaPublicKey; } & DonationUnitKeyCommon)[]; }
interface DonationUnitKeyGroupCs extends DonationUnitKeyGroupCommon { cipher: "CS"; donation_units: ({ cs_pub: Cs25519Point; } & DonationUnitKeyCommon)[]; }
// Common attributes for all donation unit groups interface DonationUnitKeyGroupCommon { // How much was donated based on this donation receipt. value: Amount; }
interface DonationUnitKeyCommon { // For which year is this donation unit key valid. year: Integer; // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not // revoked, but still cannot be used to withdraw receipts at this time (theoretically, // the private key could be recovered in the future; receipts signed with the private key // remain valid). lost?: boolean; }
type DonationUnitKey = | RsaDonationUnitKey | CSDonationUnitKey;
interface RsaDonationUnitKey { cipher: "RSA"; // RSA public key rsa_public_key: RsaPublicKey; }
interface CSDonationUnitKey { cipher: "CS"; // Public key of the donation unit. cs_public_key: Cs25519Point; }
A signing key in the
signkeyslist is a JSON object with the following fields:interface SignKey { // The actual Donau's EdDSA signing public key. key: EddsaPublicKey; // Initial validity date for the signing key. year: Integer; }
Note
Both the individual donation units and the donation units list is signed, allowing customers to prove that they received an inconsistent list.
- GET /seed¶
Return an entropy seed. The Donau will return a high-entropy value that will differ for every call. The response is NOT in JSON, but simply high-entropy binary data in the HTTP body. This API should be used by wallets to guard themselves against running on low-entropy (bad PRNG) hardware. Naturally, the entropy returned MUST be mixed with locally generated entropy.
- GET /config¶
Return the protocol version, financial domain and currency supported by this Donau backend.
Response:
- 200 OK:
The body is a DonauVersionResponse.
interface DonauVersionResponse { // libtool-style representation of the Donau protocol version, see // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; // Name of the protocol. name: "taler-donau"; // Currency supported by this Donau. currency: string; // Financial domain by this Donau. domain: string; }
1.12.4. Issue receipts¶
Inspired by the Taler exchange Withdrawal.
This API is used by the charity to obtain valid, attested donation receipts from the Donau. Use the charity GET route to see the remaining donation volume for the current year.
All incoming BDID are recorded under the corresponding charity_id by the Donau.
- POST /batch-issue/$CHARITY_ID¶
Send in a IssueReceiptsRequest and ask the Donau to sign all it’s contained BDID.
Request: IssueReceiptsRequest
Response:
- 200 OK:
The request was successful, and the response is a BSDonationReceipts.
- 403 Forbidden:
The charity signature is invalid. This response comes with a standard ErrorDetail response.
- 404 Not found:
At least one of the donation unit keys is not known to the Donau. Comes with a DonationUnitUnknownError. This suggests a bug in the donor as it should have used current donation unit keys from /keys.
- 409 Conflict:
The donation volume of the charity is not sufficient to issue donation receipts vor all sent in blinded udids. The response is a IssueError object.
- 410 Gone:
The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a DonationUnitExpiredMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.
Details:
interface IssueReceiptsRequest { charity_signature: EddsaSignature; year: Integer; bdids: BDID[]; }
interface BDID { donau_pub_hash: HashCode; taxpayer_blinded_id: BDIDEnvelope; }
type BDIDEnvelope = RSABDIDEnvelope | CSBDIDEnvelope ;
interface RSABDIDEnvelope { cipher: "RSA" | "RSA+age_restricted"; rsa_blinded_UDID: string; // Crockford Base32 encoded }
// For donation unit signatures based on Blind Clause-Schnorr, the UDID // consists of the public nonce and two Curve25519 scalars which are two // blinded challenges in the Blinded Clause-Schnorr signature scheme. // See https://taler.net/papers/cs-thesis.pdf for details. interface CSBDIDEnvelope { cipher: "CS" | "CS+age_restricted"; cs_nonce: string; // Crockford Base32 encoded cs_blinded_c0: string; // Crockford Base32 encoded cs_blinded_c1: string; // Crockford Base32 encoded }
// Secret for blinding/unblinding. // An RSA blinding secret, which is basically // a 256-bit nonce, converted to Crockford Base32. type BDIDBlindingKeyP = string;
interface DonationReceipts { blind_signed_receipt_signatures: DonationReceiptSignature[]; }
type BlindedDonationReceiptSignature = | RSABlindedDonationReceiptSignature | CSBlindedDonationReceiptSignature;
interface RSABlindedDonationReceiptSignature { cipher: "RSA"; // (blinded) RSA signature blinded_rsa_signature: BlindedRsaSignature; }
interface CSBlindedDonationReceiptSignature { type: "CS"; // Signer chosen bit value, 0 or 1, used // in Clause Blind Schnorr to make the // ROS problem harder. b: Integer; // Blinded scalar calculated from c_b. s: Cs25519Scalar; } type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ;
interface RSADonationReceiptSignature { cipher: "RSA"; rsa_blinded_donation_receipt_sig: string; // Crockford Base32 encoded }
interface CSDonationReceiptSignature { cipher: "CS"; cs_nonce: string; // Crockford Base32 encoded cs_blinded_c0: string; // Crockford Base32 encoded cs_blinded_c1: string; // Crockford Base32 encoded }
interface DonationUnitUnknownError{ unknown_hash_pub_donation_unit: HashCode[]; donau_pub: EddsaPublicKey; donau_sig: EddsaSignature; }
interface DonationUnitExpiredMessage{ h_donation_unit_pub: HashCode; donau_pub: EddsaPublicKey; donau_sig: EddsaSignature; }
1.12.5. Submit receipts¶
Inspired by the Taler exchange Deposit.
- POST /submit¶
Send in donation receipts for the past fiscal year, receive signed total back.
Request: SubmitDonationReceiptsRequest
Response:
- 200 OK:
The request was successful, and the response is a SubmitResponse.
- 403 Forbidden:
One of the signatures is invalid. This response comes with a standard ErrorDetail response.
- 404 Not found:
At least one of the donation unit keys is not known to the Donau. Comes with a DonationUnitUnknownError.
- 410 Gone:
The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a DonationUnitExpiredMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly. FIXME: text does not match our use case well.
Details:
interface SubmitDonationReceiptsRequest{ // hashed taxpayer ID plus salt taxnr_hashed: HashCode; // All donation receipts must be for this year. year: Integer; // Receipts should be sorted by amount. donation_receipts: DonationReceipt[]; }
interface DonationReceipt{ donation_unit_pub_hash: HashCode; nonce: string; donau_sig: DonationSignature }
type DonationSignature = RsaDonationSignature | CSDonationSignature;
interface RsaDonationSignature { cipher: "RSA"; // RSA signature rsa_signature: RsaSignature; }
interface CSDonationSignature { type: "CS"; // R value component of the signature. cs_signature_r: Cs25519Point; // s value component of the signature. cs_signature_s: Cs25519Scalar: }
interface SubmitResponse{ // *accepted* total total: Amount; // signature over taxid_hashed, total, year signature: EddsaSignature; }
1.12.6. Charity administration and status information¶
The administration requests require an authorized bearer token to be set in the HTTP “Authorization” Header. This token can be set by a proxy validating authentication/authorization (using e.g. LDAP). The GET status requests require an authorized bearer token as well.
- GET /charities¶
GET all charities. Only allowed if the request comes with the administration bearer token.
return all charities
Request:
Reponse:
Details:
interface Charities{ charities: CharitySummary[]; }
- GET /charities/$CHARITY_ID¶
GET a specific charity. Only allowed if the request comes with the charity or administration bearer token.
Request information about a charity.
Request:
Response:
- 200 OK:
The Donau responds with a Charity object
- 404 Not found:
The charity id does not belong to a charity known to the Donau.
interface Charity { charity_pub: EddsaPublicKey; name: string; url: string; max_per_year: Amount; receipts_to_date: Amount; current_year: Integer; }
- POST /charity¶
Add a charity. Only allowed if the request comes with the administrator bearer token.
Request: CharityRequest
Response:
Details:
- 201 Created:
The request was successful, and the response is a CharityResponse.
- 403 Forbidden:
The request did not contain an accepted administrator bearer token in it’s header.
interface CharityRequest{ charity_pub: EddsaPublicKey; name: string; url: string; max_per_year: Amount; receipts_to_date: Amount; current_year: Integer; }
interface CharityResponse{ id: Integer; }
- PATCH /charities/{id}¶
Modify a charity. Only allowed if the request comes with the administrator bearer token.
Request: CharityRequest
Response:
- 200 OK:
The request was successful.
- 403 Forbidden:
The request did not contain an accepted administrator bearer token in it’s header.
- DELETE /charities/{id}¶
Delete (or deactivate) a charity. Only allowed if the request comes with the administrator bearer token.
Request:
Response:
- 204 No content:
The request was successful.
- 403 Forbidden:
The request did not contain an accepted administrator bearer token in it’s header.