taler-docs

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

get-management-keys.rst (4093B)

      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 
     13   **Details:**
     14 
     15   .. ts:def:: FutureKeysResponse
     16 
     17     interface FutureKeysResponse {
     18 
     19       // Future denominations to be offered by this exchange
     20       // (only those lacking a master signature).
     21       future_denoms: FutureDenom[];
     22 
     23       // The exchange's future signing keys (only those lacking a master signature).
     24       future_signkeys: FutureSignKey[];
     25 
     26       // Master public key expected by this exchange (provided so that the
     27       // offline signing tool can check that it has the right key).
     28       master_pub: EddsaPublicKey;
     29 
     30       // Public key of the denomination security module.
     31       denom_secmod_public_key: EddsaPublicKey;
     32 
     33       // Public key of the signkey security module.
     34       signkey_secmod_public_key: EddsaPublicKey;
     35 
     36     }
     37 
     38   .. ts:def:: FutureDenom
     39 
     40     interface FutureDenom {
     41       // Name in the configuration file that defines this denomination.
     42       section_name: string;
     43 
     44       // How much are coins of this denomination worth?
     45       value: Amount;
     46 
     47       // When does the denomination key become valid?
     48       stamp_start: Timestamp;
     49 
     50       // When is it no longer possible to withdraw coins
     51       // of this denomination?
     52       stamp_expire_withdraw: Timestamp;
     53 
     54       // When is it no longer possible to deposit coins
     55       // of this denomination?
     56       stamp_expire_deposit: Timestamp;
     57 
     58       // Timestamp indicating by when legal disputes relating to these coins must
     59       // be settled, as the exchange will afterwards destroy its evidence relating to
     60       // transactions involving this coin.
     61       stamp_expire_legal: Timestamp;
     62 
     63       // Public key for the denomination.
     64       denom_pub: DenominationKey;
     65 
     66       // Fee charged by the exchange for withdrawing a coin of this denomination.
     67       fee_withdraw: Amount;
     68 
     69       // Fee charged by the exchange for depositing a coin of this denomination.
     70       fee_deposit: Amount;
     71 
     72       // Fee charged by the exchange for refreshing a coin of this denomination.
     73       fee_refresh: Amount;
     74 
     75       // Fee charged by the exchange for refunding a coin of this denomination.
     76       fee_refund: Amount;
     77 
     78       // Signature by the denomination security module
     79       // over `TALER_DenominationKeyAnnouncementPS`
     80       // for this denomination with purpose
     81       // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
     82       denom_secmod_sig: EddsaSignature;
     83 
     84     }
     85 
     86   .. ts:def:: DenominationKey
     87 
     88     type DenominationKey =
     89       | RsaDenominationKey
     90       | CSDenominationKey;
     91 
     92   .. ts:def:: RsaDenominationKey
     93 
     94     interface RsaDenominationKey {
     95       cipher: "RSA";
     96 
     97       // 32-bit age mask.
     98       age_mask: Integer;
     99 
    100       // RSA public key
    101       rsa_pub: RsaPublicKey;
    102     }
    103 
    104   .. ts:def:: CSDenominationKey
    105 
    106     interface CSDenominationKey {
    107       cipher: "CS";
    108 
    109       // 32-bit age mask.
    110       age_mask: Integer;
    111 
    112       // Public key of the denomination.
    113       cs_pub: Cs25519Point;
    114 
    115     }
    116 
    117   .. ts:def:: FutureSignKey
    118 
    119     interface FutureSignKey {
    120       // The actual exchange's EdDSA signing public key.
    121       key: EddsaPublicKey;
    122 
    123       // Initial validity date for the signing key.
    124       stamp_start: Timestamp;
    125 
    126       // Date when the exchange will stop using the signing key, allowed to overlap
    127       // slightly with the next signing key's validity to allow for clock skew.
    128       stamp_expire: Timestamp;
    129 
    130       // Date when all signatures made by the signing key expire and should
    131       // henceforth no longer be considered valid in legal disputes.
    132       stamp_end: Timestamp;
    133 
    134       // Signature over `TALER_SigningKeyAnnouncementPS`
    135       // for this signing key by the signkey security
    136       // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
    137       signkey_secmod_sig: EddsaSignature;
    138     }