taler-docs

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

get-management-keys.rst (4816B)

      1 .. http:get:: /management/keys
      2 
      3   Get a list of future public keys to be used by the exchange.  Only to be
      4   used by the exchange's offline key management team. Not useful for anyone
      5   else (but also not secret, so access is public).
      6 
      7   **Response:**
      8 
      9   :http:statuscode:`200 OK`:
     10     The exchange responds with a `FutureKeysResponse` object. This request should
     11     virtually always be successful.
     12   :http:statuscode:`500 Internal Server Error`:
     13     The server experienced an internal error.
     14     This response comes with a standard `ErrorDetail` response with
     15     a code of ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``.
     16   :http:statuscode:`502 Bad Gateway`:
     17     A security module helper is unavailable.
     18     This response comes with a standard `ErrorDetail` response with
     19     a code of ``TALER_EC_EXCHANGE_DENOMINATION_HELPER_UNAVAILABLE`` or
     20     ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE``.
     21   :http:statuscode:`503 Service Unavailable`:
     22     The exchange is not yet ready (keys not loaded).
     23     This response comes with a standard `ErrorDetail` response with
     24     a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
     25 
     26   **Details:**
     27 
     28   .. ts:def:: FutureKeysResponse
     29 
     30     interface FutureKeysResponse {
     31 
     32       // Future denominations to be offered by this exchange
     33       // (only those lacking a master signature).
     34       future_denoms: FutureDenom[];
     35 
     36       // The exchange's future signing keys (only those lacking a master signature).
     37       future_signkeys: FutureSignKey[];
     38 
     39       // Master public key expected by this exchange (provided so that the
     40       // offline signing tool can check that it has the right key).
     41       master_pub: EddsaPublicKey;
     42 
     43       // Public key of the denomination security module.
     44       denom_secmod_public_key: EddsaPublicKey;
     45 
     46       // Public key of the signkey security module.
     47       signkey_secmod_public_key: EddsaPublicKey;
     48 
     49     }
     50 
     51   .. ts:def:: FutureDenom
     52 
     53     interface FutureDenom {
     54       // Name in the configuration file that defines this denomination.
     55       section_name: string;
     56 
     57       // How much are coins of this denomination worth?
     58       value: Amount;
     59 
     60       // When does the denomination key become valid?
     61       stamp_start: Timestamp;
     62 
     63       // When is it no longer possible to withdraw coins
     64       // of this denomination?
     65       stamp_expire_withdraw: Timestamp;
     66 
     67       // When is it no longer possible to deposit coins
     68       // of this denomination?
     69       stamp_expire_deposit: Timestamp;
     70 
     71       // Timestamp indicating by when legal disputes relating to these coins must
     72       // be settled, as the exchange will afterwards destroy its evidence relating to
     73       // transactions involving this coin.
     74       stamp_expire_legal: Timestamp;
     75 
     76       // Public key for the denomination.
     77       denom_pub: DenominationKey;
     78 
     79       // Fee charged by the exchange for withdrawing a coin of this denomination.
     80       fee_withdraw: Amount;
     81 
     82       // Fee charged by the exchange for depositing a coin of this denomination.
     83       fee_deposit: Amount;
     84 
     85       // Fee charged by the exchange for refreshing a coin of this denomination.
     86       fee_refresh: Amount;
     87 
     88       // Fee charged by the exchange for refunding a coin of this denomination.
     89       fee_refund: Amount;
     90 
     91       // Signature by the denomination security module
     92       // over `TALER_DenominationKeyAnnouncementPS`
     93       // for this denomination with purpose
     94       // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
     95       denom_secmod_sig: EddsaSignature;
     96 
     97     }
     98 
     99   .. ts:def:: DenominationKey
    100 
    101     type DenominationKey =
    102       | RsaDenominationKey
    103       | CSDenominationKey;
    104 
    105   .. ts:def:: RsaDenominationKey
    106 
    107     interface RsaDenominationKey {
    108       cipher: "RSA";
    109 
    110       // 32-bit age mask.
    111       age_mask: Integer;
    112 
    113       // RSA public key
    114       rsa_pub: RsaPublicKey;
    115     }
    116 
    117   .. ts:def:: CSDenominationKey
    118 
    119     interface CSDenominationKey {
    120       cipher: "CS";
    121 
    122       // 32-bit age mask.
    123       age_mask: Integer;
    124 
    125       // Public key of the denomination.
    126       cs_pub: Cs25519Point;
    127 
    128     }
    129 
    130   .. ts:def:: FutureSignKey
    131 
    132     interface FutureSignKey {
    133       // The actual exchange's EdDSA signing public key.
    134       key: EddsaPublicKey;
    135 
    136       // Initial validity date for the signing key.
    137       stamp_start: Timestamp;
    138 
    139       // Date when the exchange will stop using the signing key, allowed to overlap
    140       // slightly with the next signing key's validity to allow for clock skew.
    141       stamp_expire: Timestamp;
    142 
    143       // Date when all signatures made by the signing key expire and should
    144       // henceforth no longer be considered valid in legal disputes.
    145       stamp_end: Timestamp;
    146 
    147       // Signature over `TALER_SigningKeyAnnouncementPS`
    148       // for this signing key by the signkey security
    149       // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
    150       signkey_secmod_sig: EddsaSignature;
    151     }