taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-keys.rst (3154B)

      1 .. http:get:: /keys
      2 
      3   Get a list of all donation units keys offered by the Donau,
      4   as well as the Donau's current online signing key (used for donation statements).
      5 
      6   **Request:**
      7 
      8   **Response:**
      9 
     10   :http:statuscode:`200 OK`:
     11     The Donau responds with a `DonauKeysResponse` object. This request should
     12     virtually always be successful. It only fails if the Donau is misconfigured.
     13 
     14   **Details:**
     15 
     16   .. ts:def:: DonauKeysResponse
     17 
     18     interface DonauKeysResponse {
     19       // libtool-style representation of the Donau protocol version, see
     20       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
     21       // The format is "current:revision:age".
     22       version: string;
     23 
     24       // Legal/financial domain this Donau operates for. Shown to the
     25       // user by the wallet when selecting a Donau. Should match the
     26       // name of the financial authority that the user would recognize.
     27       legal_domain: string;
     28 
     29       // The Donau's base URL.
     30       base_url: string;
     31 
     32       // The Donau's currency.
     33       currency: string;
     34 
     35       // Donation units offered by this Donau.  Each entry enumerates a
     36       // specific key together with its value and status.
     37       donation_units: DonationUnit[];
     38 
     39       // The Donau's signing keys.
     40       signkeys: SignKey[];
     41 
     42     }
     43 
     44   .. ts:def:: DonationUnit
     45 
     46     interface DonationUnit extends DonationUnitKeyCommon {
     47       // How much a receipt signed with this key is worth.
     48       value: Amount;
     49 
     50       // Public key material of the donation unit.
     51       donation_unit_pub: DonationUnitKey;
     52     }
     53 
     54   .. ts:def:: DonationUnitKeyCommon
     55 
     56     interface DonationUnitKeyCommon {
     57 
     58       // For which year is this donation unit key valid.
     59       year: Integer;
     60 
     61       // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not
     62       // revoked, but still cannot be used to withdraw receipts at this time (theoretically,
     63       // the private key could be recovered in the future; receipts signed with the private key
     64       // remain valid).
     65       lost?: boolean;
     66     }
     67 
     68   .. ts:def:: DonationUnitKey
     69 
     70     type DonationUnitKey =
     71       | RsaDonationUnitKey
     72       | CSDonationUnitKey;
     73 
     74   .. ts:def:: RsaDonationUnitKey
     75 
     76     interface RsaDonationUnitKey {
     77       cipher: "RSA";
     78 
     79       // RSA public key
     80       rsa_public_key: RsaPublicKey;
     81 
     82       // Hash of the RSA public key, as used in other API calls.
     83       pub_key_hash: HashCode;
     84     }
     85 
     86   .. ts:def:: CSDonationUnitKey
     87 
     88     interface CSDonationUnitKey {
     89       cipher: "CS";
     90 
     91       // Public key of the donation unit.
     92       cs_public_key: Cs25519Point;
     93 
     94       // Hash of the CS public key, as used in other API calls.
     95       pub_key_hash: HashCode;
     96     }
     97 
     98   A signing key in the ``signkeys`` list is a JSON object with the following fields:
     99 
    100   .. ts:def:: SignKey
    101 
    102     interface SignKey {
    103       // The actual Donau's EdDSA signing public key.
    104       key: EddsaPublicKey;
    105 
    106       // Initial validity date for the signing key.
    107       year: Integer;
    108 
    109     }
    110 
    111 
    112   .. note::
    113 
    114     Both the individual donation units *and* the donation units list is signed,
    115     allowing customers to prove that they received an inconsistent list.