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;

  // 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[];

}

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;
}

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;

  // Hash of the RSA public key, as used in other API calls.
  pub_key_hash: HashCode;
}

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:

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.