taler-docs

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

post-csr-issue.rst (2405B)

      1 .. http:post:: /csr-issue
      2 
      3   Obtain donau-side input values in preparation for a
      4   issue receipt step for certain donation unit cipher types,
      5   specifically at this point for Clause-Schnorr blind
      6   signatures. This API is used by the donor.
      7 
      8   **Request:** The request body must be a `IssuePrepareRequest` object.
      9 
     10   **Response:**
     11 
     12   :http:statuscode:`201 Created`:
     13     The request was successful, and the response is a `IssuePrepareResponse`.  Note that repeating exactly the same request
     14     will again yield the same response (assuming none of the donation unit is expired).
     15   :http:statuscode:`400 Bad Request`:
     16     The request body is malformed or required fields are missing,
     17     or the specified denomination key does not support this operation.
     18     Returned with error codes ``TALER_EC_GENERIC_JSON_INVALID`` or
     19     ``TALER_EC_DONAU_GENERIC_INVALID_DENOMINATION_CIPHER_FOR_OPERATION``.
     20   :http:statuscode:`404 Not Found`:
     21     One of the referenced donation unit keys could not be found.
     22     Returned with error code
     23     ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
     24  :http:statuscode:`500 Internal Server Error`:
     25     The donation unit key is not known to the Donau, has the wrong cipher type,
     26     or the signing helper encountered an error.
     27     Returned with error code ``TALER_EC_DONAU_GENERIC_KEYS_MISSING`` or
     28     ``TALER_EC_DONAU_SIGNKEY_HELPER_BUG``.
     29   :http:statuscode:`503 Service unavailable`:
     30     The donau is lacking the keys to create the response.
     31     Returned with error code
     32     ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
     33 
     34   **Details:**
     35 
     36   .. ts:def:: IssuePrepareRequest
     37 
     38     interface IssuePrepareRequest {
     39 
     40       // Nonce to be used by the donau to derive
     41       // its private inputs from. Must not have ever
     42       // been used before.
     43       nonce: CSNonce;
     44 
     45       // Hash of the public key of the donation unit
     46       // the request relates to.
     47       du_pub_hash: HashCode;
     48 
     49     }
     50 
     51   .. ts:def:: IssuePrepareResponse
     52 
     53     type IssuePrepareResponse =
     54       | DonauIssueValue;
     55 
     56   .. ts:def:: DonauIssueValue
     57 
     58     type DonauIssueValue =
     59       | DonauRsaIssueValue
     60       | DonauCsIssueValue;
     61 
     62   .. ts:def:: DonauRsaIssueValue
     63 
     64     interface DonauRsaIssueValue {
     65       cipher: "RSA";
     66     }
     67 
     68   .. ts:def:: DonauCsIssueValue
     69 
     70     interface DonauCsIssueValue {
     71       cipher: "CS";
     72 
     73       // CSR R0 value
     74       r_pub_0: CSRPublic;
     75 
     76       // CSR R1 value
     77       r_pub_1: CSRPublic;
     78     }