taler-docs

api-donau.rst (23019B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2014-2023 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
   @author Pius Loosli
   @author Lukas Matyja
   @author Johannes Casaburi
 
 .. _donau-api:
 
 =====================
 The Donau RESTful API
 =====================
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 .. contents:: Table of Contents
   :local:
 
 .. _donau-overview:
 
 ------------
 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:
 
 * :ref:`Status information<donau_status>`: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy
 * :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts with blinded unique donor ids from a donor.
 * :ref:`Donation statement<donation_statement>`: Summarizes the donation receipts to the donation statement signature which is made over the total yearly donation amount,
           the year and the hash of taxid+salt. Provides an API to get the donation statement signature.
 * :ref:`Charity administration and status information<donau_charity>`:
 
   * For use by administrators to add/modify a charity
   * For use by charities to get their remaining donation volume
 
 .. include:: tos.rst
 
 .. _donau_status:
 
 ----------------------------------------
 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.
 
 .. http: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:**
 
   :http:statuscode:`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:**
 
   .. ts:def:: DonauKeysResponse
 
     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;
 
       // Legal/financial domain this Donau operates for. Shown to the
       // user by the wallet when selecting a Donau. Should match the
       // name of the financial authority that the user would recognize.
       legal_domain: string;
 
       // The Donau's base URL.
       base_url: string;
 
       // The Donau's currency.
       currency: string;
 
       // Donation units offered by this Donau.  Each entry enumerates a
       // specific key together with its value and status.
       donation_units: DonationUnit[];
 
       // The Donau's signing keys.
       signkeys: SignKey[];
 
     }
 
   .. ts:def:: DonationUnit
 
     interface DonationUnit extends DonationUnitKeyCommon {
       // How much a receipt signed with this key is worth.
       value: Amount;
 
       // Public key material of the donation unit.
       donation_unit_pub: DonationUnitKey;
     }
 
   .. ts:def:: DonationUnitKeyCommon
 
     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;
     }
 
   .. ts:def:: DonationUnitKey
 
     type DonationUnitKey =
       | RsaDonationUnitKey
       | CSDonationUnitKey;
 
   .. ts:def:: RsaDonationUnitKey
 
     interface RsaDonationUnitKey {
       cipher: "RSA";
 
       // RSA public key
       rsa_public_key: RsaPublicKey;
 
       // Hash of the RSA public key, as used in other API calls.
       pub_key_hash: HashCode;
     }
 
   .. ts:def:: CSDonationUnitKey
 
     interface CSDonationUnitKey {
       cipher: "CS";
 
       // Public key of the donation unit.
       cs_public_key: Cs25519Point;
 
       // Hash of the CS public key, as used in other API calls.
       pub_key_hash: HashCode;
     }
 
   A signing key in the ``signkeys`` list is a JSON object with the following fields:
 
   .. ts:def:: SignKey
 
     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.
 
 .. http: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.
 
 .. http:get:: /config
 
   Return the protocol version, financial domain and currency supported by this
   Donau backend.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The body is a `DonauVersionResponse`.
 
   .. ts:def:: 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: "donau";
 
       // Currency supported by this Donau.
       currency: string;
 
       // Financial domain by this Donau.
       domain: string;
 
     }
 
 
 .. _donau_issue:
 
 --------------
 Issue receipts
 --------------
 
 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`.
 
 This API is used to obtain valid, attested donation receipts from the Donau.
 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year.
 
 CSR  Issue
 ~~~~~~~~~~~
 
 .. http:post:: /csr-issue
 
   Obtain donau-side input values in preparation for a
   issue receipt step for certain donation unit cipher types,
   specifically at this point for Clause-Schnorr blind
   signatures. This API is used by the donor.
 
   **Request:** The request body must be a `IssuePrepareRequest` object.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `IssuePrepareResponse`.  Note that repeating exactly the same request
     will again yield the same response (assuming none of the donation unit is expired).
   :http:statuscode:`404 Not found`:
     The donation unit key is not known to the donau.
   :http:statuscode:`410 Gone`:
     The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
     year 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:**
 
   .. ts:def:: IssuePrepareRequest
 
     interface IssuePrepareRequest {
 
       // Nonce to be used by the donau to derive
       // its private inputs from. Must not have ever
       // been used before.
       nonce: CSNonce;
 
       // Hash of the public key of the donation unit
       // the request relates to.
       du_pub_hash: HashCode;
 
     }
 
   .. ts:def:: IssuePrepareResponse
 
     type IssuePrepareResponse =
       | DonauIssueValue;
 
   .. ts:def:: DonauIssueValue
 
     type DonauIssueValue =
       | DonauRsaIssueValue
       | DonauCsIssueValue;
 
   .. ts:def:: DonauRsaIssueValue
 
     interface DonauRsaIssueValue {
       cipher: "RSA";
     }
 
   .. ts:def:: DonauCsIssueValue
 
     interface DonauCsIssueValue {
       cipher: "CS";
 
       // CSR R0 value
       r_pub_0: CSRPublic;
 
       // CSR R1 value
       r_pub_1: CSRPublic;
     }
 
 
 Batch Issue
 ~~~~~~~~~~~
 This is the effectiv issue receipts request. Depending on the amount of the donation a
 certain amount of blinded unique donation identifiers, or for short BUDIs, are required.
 Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value.
 This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` are coming from the donor.
 
 To make the request idempotent, the hash of the hole request is recorded under the
 corresponding charity_id by the Donau.
 
 .. http:POST:: /batch-issue/$CHARITY_ID
 
   Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs.
 
   **Request:** `IssueReceiptsRequest`
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`.
   :http:statuscode:`403 Forbidden`:
     The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`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 :ref:`/keys<donau_status>`.
   :http:statuscode:`409 Conflict`:
     The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
     The response is a `IssueError` object.
   :http:statuscode:`410 Gone`:
     The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
     year 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:**
 
   .. ts:def:: IssueReceiptsRequest
 
     interface IssueReceiptsRequest {
 
       // Signature by the charity approving that the
       // Donau should sign the donation receipts below.
       charity_sig: EddsaSignature;
 
       // Year for which the donation receipts are expected.
       // Also determines which keys are used to sign the
       // blinded donation receipts.
       year: Integer;
 
       // Array of blinded donation receipts to sign.
       // Must NOT be empty (if no donation receipts
       // are desired, just leave the entire ``donau``
       // argument blank).
       budikeypairs: BlindedDonationReceiptKeyPair[];
     }
 
   .. ts:def:: BlindedDonationReceiptKeyPair
 
     interface BlindedDonationReceiptKeyPair {
       // Hash of the public key that should be used to sign
       // the donation receipt.
       h_donation_unit_pub: HashCode;
 
       // Blinded value to give to the Donau to sign over.
       blinded_udi: BlindedUniqueDonationIdentifier;
     }
 
   .. ts:def:: BlindedUniqueDonationIdentifier
 
     type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ;
 
   .. ts:def:: RSABUDI
 
     interface RSABUDI {
       cipher: "RSA";
       rsa_blinded_identifier: string;          // Crockford Base32 encoded
     }
 
   .. ts:def:: CSBUDI
 
     // For donation unit signatures based on Blind Clause-Schnorr, the BUDI
     // 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 CSBUDI {
       cipher: "CS";
       cs_nonce: string;      // Crockford Base32 encoded
       cs_blinded_c0: string; // Crockford Base32 encoded
       cs_blinded_c1: string; // Crockford Base32 encoded
     }
 
   .. ts:def:: BUDIBlindingKeyP
 
     // Secret for blinding/unblinding.
     // An RSA blinding secret, which is basically
     // a 256-bit nonce, converted to Crockford Base32.
     type BUDIBlindingKeyP = string;
 
   .. ts:def:: BlindedDonationReceiptSignaturesResponse
 
     interface BlindedDonationReceiptSignaturesResponse {
       // Total amount over which all the blind signatures are signing.
       issued_amount: Amount;
 
       // Array of the blind signatures.
       blind_signatures: BlindedDonationReceiptSignature[];
     }
 
   .. ts:def:: BlindedDonationReceiptSignature
 
     type BlindedDonationReceiptSignature =
       | RSABlindedDonationReceiptSignature
       | CSBlindedDonationReceiptSignature;
 
   .. ts:def:: RSABlindedDonationReceiptSignature
 
     interface RSABlindedDonationReceiptSignature {
       cipher: "RSA";
 
       // (blinded) RSA signature
       blinded_rsa_signature: BlindedRsaSignature;
     }
 
   .. ts:def:: CSBlindedDonationReceiptSignature
 
     interface CSBlindedDonationReceiptSignature {
       cipher: "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;
     }
 
   .. ts:def:: IssueError
 
     interface IssueError{
       max_per_year: Amount;
       current_year: Amount;
     }
 
   .. ts:def:: DonationUnitUnknownError
 
     interface DonationUnitUnknownError{
       unknown_hash_pub_donation_unit: HashCode[];
       donau_pub: EddsaPublicKey;
       donau_sig: EddsaSignature;
     }
 
   .. ts:def:: DonationUnitExpiredMessage
 
     interface DonationUnitExpiredMessage{
       h_donation_unit_pub: HashCode;
       donau_pub: EddsaPublicKey;
       donau_sig: EddsaSignature;
     }
 
 .. _donation_statement:
 
 ------------------
 Donation statement
 ------------------
 
 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
 
 Donation statement operations are requested by a donor.
 
 .. http:POST:: /batch-submit
 
   Send in donation receipts for the current or one of the past fiscal years.
   The donor will reveive the signed total back, which is called the
   donation statement.
 
   **Request:** `SubmitDonationReceiptsRequest`
 
   **Response:**
 
   :http:statuscode:`201 Created`:
     The request was successful, and a donation statement is now available. The response will be empty.
   :http:statuscode:`403 Forbidden`:
     One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
 
   **Details:**
 
   .. ts:def:: SubmitDonationReceiptsRequest
 
     interface SubmitDonationReceiptsRequest{
       // hashed taxpayer ID plus salt
       h_donor_tax_id: HashCode;
       // All donation receipts must be for this year.
       donation_year: Integer;
       // Receipts should be sorted by amount.
       donation_receipts: DonationReceipt[];
     }
 
   .. ts:def:: DonationReceipt
 
     interface DonationReceipt {
       h_donation_unit_pub: HashCode;
       nonce: string;
       donation_unit_sig: DonationReceiptSignature;
     }
 
   .. ts:def:: DonationReceiptSignature
 
     type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ;
 
   .. ts:def:: RSADonationReceiptSignature
 
     interface RSADonationReceiptSignature {
       cipher: "RSA";
 
       // RSA signature
       rsa_signature: RsaSignature;
     }
 
   .. ts:def:: CSDonationReceiptSignature
 
     interface CSDonationReceiptSignature {
       cipher: "CS";
 
       // R value component of the signature.
       cs_signature_r: Cs25519Point;
 
       // s value component of the signature.
       cs_signature_s: Cs25519Scalar;
     }
 
 .. http:GET:: /donation-statement/$YEAR/$HASH_DONOR_ID
 
   Get the donation statement for a specific year and donor.
 
   **Request:**
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `DonationStatementResponse`.
   :http:statuscode:`403 Forbidden`:
     One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     Either the donor or the year or the corresponding donation statement was not found.
     This response comes with a standard `ErrorDetail` response.
 
   **Details:**
 
   .. ts:def:: DonationStatementResponse
 
     interface DonationStatementResponse {
       total: Amount;
       // signature over h_donor_tax_id, total, donation_year
       donation_statement_sig: EddsaSignature;
       // the corresponding public key to the signature
       donau_pub: EddsaPublicKey;
     }
 
 .. _donau_charity:
 
 ---------------------------------------------
 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.
 
 .. http:GET::  /charities
 
   GET all charities. Only allowed if the request comes with the administration bearer token.
 
   return all charities
 
   **Request:**
 
   **Reponse:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `Charities`.
 
   **Details:**
 
   .. ts:def:: Charities
 
     interface Charities{
       charities: CharitySummary[];
     }
 
   .. ts:def:: CharitySummary
 
     interface CharitySummary {
 
       // Unique ID of the charity within the Donau.
       charity_id: Integer;
 
       // Public key of the charity, used by the charity to
       // authorize issuing donation receipts.
       charity_pub: EddsaPublicKey;
 
       // Human-readable name of the charity.
       charity_name: string;
 
       // Maximum amount of donation receipts this charity is
       // allowed to issue per year.
       max_per_year: Amount;
 
       // Year for which ``receipts_to_date`` is given.
       current_year: Integer;
 
       // Total amount of donation receipts the donau has
       // issued for this charity so far this year.
       receipts_to_date: Amount;
     }
 
 .. _donau_charity_get:
 
 .. http:get:: /charity/$CHARITY_ID
 
   Request information about a specific charity.
   Only allowed if the request comes with a signature by
   the respective charity.
 
   **Request:**
 
   *Charity-Signature*:
 
     The client must provide Base-32 encoded EdDSA signature with
     ``$CHARITY_PRIV``, affirming the desire to obtain the charity status.
     Note that this is merely a simple authentication mechanism,
     the details of the request are not protected by the signature.
     The ``$CHARITY_PRIV`` is usually the merchant instance
     private key.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The Donau responds with a `Charity` object
   :http:statuscode:`404 Not found`:
     The charity id does not belong to a charity known to the Donau.
 
   .. ts:def:: Charity
 
     interface Charity {
       charity_pub: EddsaPublicKey;
       name: string;
       url: string;
       max_per_year: Amount;
       receipts_to_date: Amount;
       current_year: Integer;
     }
 
 .. http:POST:: /charities
 
   Register a new charity with the Donau. Only allowed if the request comes with the
   administrator bearer token. The request body defines the charity's signing key,
   contact information, and the initial accounting values for the current business
   year. On success the Donau assigns a numeric identifier to the charity record.
 
   **Request:** `CharityRequest`
 
   **Response:**
 
   **Details:**
 
   :http:statuscode:`201 Created`:
     The request was successful, and the response is a `CharityResponse`.
 
   :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in its header.
 
   :http:statuscode:`404 Not found`:
     The referenced resource needed to create the charity was not found. This response
     comes with a standard `ErrorDetail` response.
 
   :http:statuscode:`409 Conflict`:
     A charity with the same public key exists in the backend, but it
     has different details. This response
     comes with a standard `ErrorDetail` response.
 
   .. ts:def:: CharityRequest
 
     interface CharityRequest {
 
       // Long-term EdDSA public key that identifies the charity.
       charity_pub: EddsaPublicKey;
 
       // Canonical URL that should be presented to donors.
       charity_url: string;
 
       // Human-readable display name of the charity.
       charity_name: string;
 
       // Allowed donation volume for the charity per calendar year.
       max_per_year: Amount;
     }
 
   .. ts:def:: CharityResponse
 
     interface CharityResponse {
 
       // Unique ID assigned to the charity in the backend.
       charity_id: Integer;
     }
 
 
 .. http:PATCH:: /charities/{charity_id}
 
   Modify a charity.
   Only allowed if the request comes with the administrator bearer token.
 
   **Request:** ``CharityRequest``
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The update succeeded. The response body is empty.
 
   :http:statuscode:`400 Bad Request`:
     The request was malformed. For example, ``max_per_year`` must not be
     smaller than the current ``receipts_to_date`` of the charity.
 
   :http:statuscode:`401 Unauthorized`:
     Missing or invalid bearer token.
 
   :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in its header.
 
   :http:statuscode:`404 Not Found`:
     The charity ID is unknown to the Donau.
 
   **Details:**
 
   The request body has the same shape as :ts:type:`CharityRequest` used by
   :http:POST:`/charities`. All fields are required and will replace the stored
   values of the charity.
 
 
 .. http:DELETE:: /charities/{charity_id}
 
   Delete (or deactivate) a charity. Only allowed if the request comes with the administrator bearer token.
 
   **Request:**
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The request was successful.
 
   :http:statuscode:`403 Forbidden`:
     The request did not contain an accepted administrator bearer token in it's header.