taler-docs

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

post-batch-issue-CHARITY_ID.rst (4795B)

      1 .. http:POST:: /batch-issue/$CHARITY_ID
      2 
      3   Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs.
      4 
      5   **Request:** `IssueReceiptsRequest`
      6 
      7   **Response:**
      8 
      9   :http:statuscode:`200 OK`:
     10     The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`.
     11   :http:statuscode:`403 Forbidden`:
     12     The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
     13   :http:statuscode:`404 Not found`:
     14     At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
     15     This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
     16   :http:statuscode:`409 Conflict`:
     17     The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
     18     The response is a `IssueError` object.
     19   :http:statuscode:`410 Gone`:
     20     The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
     21     year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code
     22     provided to understand which of the cases this is and handle it accordingly.
     23 
     24   **Details:**
     25 
     26   .. ts:def:: IssueReceiptsRequest
     27 
     28     interface IssueReceiptsRequest {
     29 
     30       // Signature by the charity approving that the
     31       // Donau should sign the donation receipts below.
     32       charity_sig: EddsaSignature;
     33 
     34       // Year for which the donation receipts are expected.
     35       // Also determines which keys are used to sign the
     36       // blinded donation receipts.
     37       year: Integer;
     38 
     39       // Array of blinded donation receipts to sign.
     40       // Must NOT be empty (if no donation receipts
     41       // are desired, just leave the entire ``donau``
     42       // argument blank).
     43       budikeypairs: BlindedDonationReceiptKeyPair[];
     44     }
     45 
     46   .. ts:def:: BlindedDonationReceiptKeyPair
     47 
     48     interface BlindedDonationReceiptKeyPair {
     49       // Hash of the public key that should be used to sign
     50       // the donation receipt.
     51       h_donation_unit_pub: HashCode;
     52 
     53       // Blinded value to give to the Donau to sign over.
     54       blinded_udi: BlindedUniqueDonationIdentifier;
     55     }
     56 
     57   .. ts:def:: BlindedUniqueDonationIdentifier
     58 
     59     type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ;
     60 
     61   .. ts:def:: RSABUDI
     62 
     63     interface RSABUDI {
     64       cipher: "RSA";
     65       rsa_blinded_identifier: string;          // Crockford Base32 encoded
     66     }
     67 
     68   .. ts:def:: CSBUDI
     69 
     70     // For donation unit signatures based on Blind Clause-Schnorr, the BUDI
     71     // consists of the public nonce and two Curve25519 scalars which are two
     72     // blinded challenges in the Blinded Clause-Schnorr signature scheme.
     73     // See https://taler.net/papers/cs-thesis.pdf for details.
     74     interface CSBUDI {
     75       cipher: "CS";
     76       cs_nonce: string;      // Crockford Base32 encoded
     77       cs_blinded_c0: string; // Crockford Base32 encoded
     78       cs_blinded_c1: string; // Crockford Base32 encoded
     79     }
     80 
     81   .. ts:def:: BUDIBlindingKeyP
     82 
     83     // Secret for blinding/unblinding.
     84     // An RSA blinding secret, which is basically
     85     // a 256-bit nonce, converted to Crockford Base32.
     86     type BUDIBlindingKeyP = string;
     87 
     88   .. ts:def:: BlindedDonationReceiptSignaturesResponse
     89 
     90     interface BlindedDonationReceiptSignaturesResponse {
     91       // Total amount over which all the blind signatures are signing.
     92       issued_amount: Amount;
     93 
     94       // Array of the blind signatures.
     95       blind_signatures: BlindedDonationReceiptSignature[];
     96     }
     97 
     98   .. ts:def:: BlindedDonationReceiptSignature
     99 
    100     type BlindedDonationReceiptSignature =
    101       | RSABlindedDonationReceiptSignature
    102       | CSBlindedDonationReceiptSignature;
    103 
    104   .. ts:def:: RSABlindedDonationReceiptSignature
    105 
    106     interface RSABlindedDonationReceiptSignature {
    107       cipher: "RSA";
    108 
    109       // (blinded) RSA signature
    110       blinded_rsa_signature: BlindedRsaSignature;
    111     }
    112 
    113   .. ts:def:: CSBlindedDonationReceiptSignature
    114 
    115     interface CSBlindedDonationReceiptSignature {
    116       cipher: "CS";
    117 
    118       // Signer chosen bit value, 0 or 1, used
    119       // in Clause Blind Schnorr to make the
    120       // ROS problem harder.
    121       b: Integer;
    122 
    123       // Blinded scalar calculated from c_b.
    124       s: Cs25519Scalar;
    125     }
    126 
    127   .. ts:def:: IssueError
    128 
    129     interface IssueError{
    130       max_per_year: Amount;
    131       current_year: Amount;
    132     }
    133 
    134   .. ts:def:: DonationUnitUnknownError
    135 
    136     interface DonationUnitUnknownError{
    137       unknown_hash_pub_donation_unit: HashCode[];
    138       donau_pub: EddsaPublicKey;
    139       donau_sig: EddsaSignature;
    140     }
    141 
    142   .. ts:def:: DonationUnitExpiredMessage
    143 
    144     interface DonationUnitExpiredMessage{
    145       h_donation_unit_pub: HashCode;
    146       donau_pub: EddsaPublicKey;
    147       donau_sig: EddsaSignature;
    148     }