taler-docs

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

get-keys.rst (3612B)

      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   :http:statuscode:`502 Bad Gateway`:
     14     The Donau is unable to reach one of its cryptographic helper processes.
     15     Returned with error code
     16     ``TALER_EC_DONAU_DONATION_UNIT_HELPER_UNAVAILABLE`` or
     17     ``TALER_EC_DONAU_SIGNKEY_HELPER_UNAVAILABLE``.
     18   :http:statuscode:`503 Service Unavailable`:
     19     The Donau has no valid keys at this time, likely due to a configuration
     20     problem.
     21     Returned with error code ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
     22 
     23   **Details:**
     24 
     25   .. ts:def:: DonauKeysResponse
     26 
     27     interface DonauKeysResponse {
     28       // libtool-style representation of the Donau protocol version, see
     29       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
     30       // The format is "current:revision:age".
     31       version: string;
     32 
     33       // Legal/financial domain this Donau operates for. Shown to the
     34       // user by the wallet when selecting a Donau. Should match the
     35       // name of the financial authority that the user would recognize.
     36       legal_domain: string;
     37 
     38       // The Donau's base URL.
     39       base_url: string;
     40 
     41       // The Donau's currency.
     42       currency: string;
     43 
     44       // Donation units offered by this Donau.  Each entry enumerates a
     45       // specific key together with its value and status.
     46       donation_units: DonationUnit[];
     47 
     48       // The Donau's signing keys.
     49       signkeys: SignKey[];
     50 
     51     }
     52 
     53   .. ts:def:: DonationUnit
     54 
     55     interface DonationUnit extends DonationUnitKeyCommon {
     56       // How much a receipt signed with this key is worth.
     57       value: Amount;
     58 
     59       // Public key material of the donation unit.
     60       donation_unit_pub: DonationUnitKey;
     61     }
     62 
     63   .. ts:def:: DonationUnitKeyCommon
     64 
     65     interface DonationUnitKeyCommon {
     66 
     67       // For which year is this donation unit key valid.
     68       year: Integer;
     69 
     70       // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not
     71       // revoked, but still cannot be used to withdraw receipts at this time (theoretically,
     72       // the private key could be recovered in the future; receipts signed with the private key
     73       // remain valid).
     74       lost?: boolean;
     75     }
     76 
     77   .. ts:def:: DonationUnitKey
     78 
     79     type DonationUnitKey =
     80       | RsaDonationUnitKey
     81       | CSDonationUnitKey;
     82 
     83   .. ts:def:: RsaDonationUnitKey
     84 
     85     interface RsaDonationUnitKey {
     86       cipher: "RSA";
     87 
     88       // RSA public key
     89       rsa_public_key: RsaPublicKey;
     90 
     91       // Hash of the RSA public key, as used in other API calls.
     92       pub_key_hash: HashCode;
     93     }
     94 
     95   .. ts:def:: CSDonationUnitKey
     96 
     97     interface CSDonationUnitKey {
     98       cipher: "CS";
     99 
    100       // Public key of the donation unit.
    101       cs_public_key: Cs25519Point;
    102 
    103       // Hash of the CS public key, as used in other API calls.
    104       pub_key_hash: HashCode;
    105     }
    106 
    107   A signing key in the ``signkeys`` list is a JSON object with the following fields:
    108 
    109   .. ts:def:: SignKey
    110 
    111     interface SignKey {
    112       // The actual Donau's EdDSA signing public key.
    113       key: EddsaPublicKey;
    114 
    115       // Initial validity date for the signing key.
    116       year: Integer;
    117 
    118     }
    119 
    120 
    121   .. note::
    122 
    123     Both the individual donation units *and* the donation units list is signed,
    124     allowing customers to prove that they received an inconsistent list.