taler-docs

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

post-blinding-prepare.rst (3497B)

      1 .. http:post:: /blinding-prepare
      2 
      3   Obtain exchange-side input values in preparation for a
      4   blinding step of multiple coins for certain denomination
      5   cipher types, specifically at this point for Clause-Schnorr
      6   blind signatures.
      7 
      8   **Request:**
      9 
     10   The request body must be a `BlindingPrepareRequest` object.
     11 
     12   **Response:**
     13 
     14   :http:statuscode:`200 OK`:
     15     The request was successful, and the response is a
     16     `BlindingPrepareResponse`.  Note that repeating exactly the same request
     17     will again yield the same response (assuming none of the denominations is
     18     expired).
     19   :http:statuscode:`400 Bad Request`:
     20     The request body is malformed or a parameter is invalid.
     21     This response comes with a standard `ErrorDetail` response.
     22     Possible error codes include
     23     ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
     24     ``TALER_EC_EXCHANGE_GENERIC_NEW_DENOMS_ARRAY_SIZE_EXCESSIVE``.
     25   :http:statuscode:`404 Not found`:
     26     A denomination key is not known to the exchange.
     27     The response is a `DenominationUnknownMessage`.
     28   :http:statuscode:`410 Gone`:
     29     A requested denomination key is not yet or no longer valid.
     30     It either before the validity start, past the expiration or was revoked.
     31     The response is a `DenominationGoneMessage`.
     32     Clients must evaluate the error code provided to understand
     33     which of the cases this is and handle it accordingly.
     34   :http:statuscode:`413 Request entity too large`:
     35     The uploaded body is to long, it exceeds the size limit.
     36     Returned with an error code of
     37     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     38   :http:statuscode:`500 Internal Server Error`:
     39     The server experienced an internal error.
     40     This response comes with a standard `ErrorDetail` response with
     41     a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
     42 
     43   **Details:**
     44 
     45 
     46   .. ts:def:: BlindingPrepareRequest
     47 
     48     type BlindingPrepareRequest = BlindingPrepareRequestCS;
     49 
     50 
     51   .. ts:def:: BlindingPrepareRequestCS
     52 
     53     interface BlindingPrepareRequestCS {
     54       // Cipher type
     55       cipher: "CS";
     56 
     57       // The type of operation this blinding is for.
     58       operation: "withdraw" | "melt";
     59 
     60       // Master seed for the Clause-Schnorr R-value creation.
     61       // MUST not have been used in any prior request of this type.
     62       seed: BlindingMasterSeed;
     63 
     64       // Array of denominations and coin offsets for
     65       // each of the fresh coins with a CS-cipher
     66       // denomination.
     67       // The coin_offset values MUST be strongly increasing.
     68       nks: BlindingInputParameter[];
     69 
     70     }
     71 
     72   .. ts:def:: BlindingInputParameter
     73 
     74     interface BlindingInputParameter {
     75 
     76       // Offset of this coin in the list of
     77       // fresh coins. May not match the array offset
     78       // as the fresh coins may include non-CS
     79       // denominations as well.
     80       coin_offset: Integer;
     81 
     82       // Hash of the public key of the denomination the
     83       // request relates to. Must be a CS denomination type.
     84       denom_pub_hash: HashCode;
     85     }
     86 
     87 
     88 
     89   .. ts:def:: BlindingPrepareResponse
     90 
     91     type BlindingPrepareResponse = BlindingPrepareResponseCS;
     92 
     93 
     94   .. ts:def:: BlindingPrepareResponseCS
     95 
     96     interface BlindingPrepareResponseCS {
     97       cipher: "CS";
     98 
     99       // Array of pairs of CS values, one pair per input
    100       r_pubs: CSRPublicPair[];
    101     }
    102 
    103 
    104   .. ts:def:: CSRPublicPair
    105 
    106     // Pair of points (of type `CSRPublic`) on the curve Curve25519,
    107     // one of which is randomly selected in the Clause-Schnorr
    108     // signature scheme.
    109     type CSRPublicPair = [CSRPublic, CSRPublic];