post-batch-issue-CHARITY_ID.rst (6114B)
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 Also returned for idempotent re-requests of an already-processed batch. 12 :http:statuscode:`400 Bad Request`: 13 The request was malformed. This can occur when the ``$CHARITY_ID`` cannot be 14 parsed, the ``budikeypairs`` array is empty or contains malformed entries, 15 or the total donation amount exceeds the charity's per-year limit. 16 Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED``, 17 ``TALER_EC_GENERIC_JSON_INVALID``, or 18 ``TALER_EC_DONAU_EXCEEDING_DONATION_LIMIT``. 19 :http:statuscode:`403 Forbidden`: 20 The charity signature is invalid. 21 Returned with error code ``TALER_EC_DONAU_CHARITY_SIGNATURE_INVALID``. 22 :http:statuscode:`404 Not Found`: 23 The charity is unknown to the Donau, or at least one of the referenced 24 donation unit keys could not be found. 25 Returned with error code ``TALER_EC_DONAU_CHARITY_NOT_FOUND`` or 26 ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``. 27 :http:statuscode:`409 Conflict`: 28 The year specified does not match the validity year for the given 29 denomination unit key. Returned with an error code of 30 ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_WRONG_YEAR``. 31 :http:statuscode:`410 Gone`: 32 The year specified is in the past, and the Donau does 33 not permit issuing donation receipts in the past. The 34 client should pick a donation unit from the current year. 35 Returned with an error code of 36 ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_EXPIRED``. 37 :http:statuscode:`425 Too Early`: 38 The year specified is in the future, and the Donau 39 does not permit issuing donation receipts in the future. 40 The client may retry the request in the specified year, 41 at that point it may succeed. Returned with an error code of 42 ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_TOO_EARLY``. 43 :http:statuscode:`500 Internal Server Error`: 44 The Donau encountered an internal error, such as a database failure or 45 a signing helper problem. 46 Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or 47 ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` 48 :http:statuscode:`503 Service unavailable`: 49 The donau is lacking the keys to create the donation statement. 50 Returned with error code 51 ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``. 52 53 **Details:** 54 55 .. ts:def:: IssueReceiptsRequest 56 57 interface IssueReceiptsRequest { 58 59 // Signature by the charity approving that the 60 // Donau should sign the donation receipts below. 61 charity_sig: EddsaSignature; 62 63 // Year for which the donation receipts are expected. 64 // Also determines which keys are used to sign the 65 // blinded donation receipts. 66 year: Integer; 67 68 // Array of blinded donation receipts to sign. 69 // Must NOT be empty (if no donation receipts 70 // are desired, just leave the entire ``donau`` 71 // argument blank). 72 budikeypairs: BlindedDonationReceiptKeyPair[]; 73 } 74 75 .. ts:def:: BlindedDonationReceiptKeyPair 76 77 interface BlindedDonationReceiptKeyPair { 78 // Hash of the public key that should be used to sign 79 // the donation receipt. 80 h_donation_unit_pub: HashCode; 81 82 // Blinded value to give to the Donau to sign over. 83 blinded_udi: BlindedUniqueDonationIdentifier; 84 } 85 86 .. ts:def:: BlindedUniqueDonationIdentifier 87 88 type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ; 89 90 .. ts:def:: RSABUDI 91 92 interface RSABUDI { 93 cipher: "RSA"; 94 rsa_blinded_identifier: string; // Crockford Base32 encoded 95 } 96 97 .. ts:def:: CSBUDI 98 99 // For donation unit signatures based on Blind Clause-Schnorr, the BUDI 100 // consists of the public nonce and two Curve25519 scalars which are two 101 // blinded challenges in the Blinded Clause-Schnorr signature scheme. 102 // See https://taler.net/papers/cs-thesis.pdf for details. 103 interface CSBUDI { 104 cipher: "CS"; 105 cs_nonce: string; // Crockford Base32 encoded 106 cs_blinded_c0: string; // Crockford Base32 encoded 107 cs_blinded_c1: string; // Crockford Base32 encoded 108 } 109 110 .. ts:def:: BUDIBlindingKeyP 111 112 // Secret for blinding/unblinding. 113 // An RSA blinding secret, which is basically 114 // a 256-bit nonce, converted to Crockford Base32. 115 type BUDIBlindingKeyP = string; 116 117 .. ts:def:: BlindedDonationReceiptSignaturesResponse 118 119 interface BlindedDonationReceiptSignaturesResponse { 120 // Total amount over which all the blind signatures are signing. 121 issued_amount: Amount; 122 123 // Array of the blind signatures. 124 blind_signatures: BlindedDonationReceiptSignature[]; 125 } 126 127 .. ts:def:: BlindedDonationReceiptSignature 128 129 type BlindedDonationReceiptSignature = 130 | RSABlindedDonationReceiptSignature 131 | CSBlindedDonationReceiptSignature; 132 133 .. ts:def:: RSABlindedDonationReceiptSignature 134 135 interface RSABlindedDonationReceiptSignature { 136 cipher: "RSA"; 137 138 // (blinded) RSA signature 139 blinded_rsa_signature: BlindedRsaSignature; 140 } 141 142 .. ts:def:: CSBlindedDonationReceiptSignature 143 144 interface CSBlindedDonationReceiptSignature { 145 cipher: "CS"; 146 147 // Signer chosen bit value, 0 or 1, used 148 // in Clause Blind Schnorr to make the 149 // ROS problem harder. 150 b: Integer; 151 152 // Blinded scalar calculated from c_b. 153 s: Cs25519Scalar; 154 } 155 156 .. ts:def:: IssueError 157 158 interface IssueError{ 159 max_per_year: Amount; 160 current_year: Amount; 161 } 162 163 .. ts:def:: DonationUnitUnknownError 164 165 interface DonationUnitUnknownError{ 166 unknown_hash_pub_donation_unit: HashCode[]; 167 donau_pub: EddsaPublicKey; 168 donau_sig: EddsaSignature; 169 } 170 171 .. ts:def:: DonationUnitExpiredMessage 172 173 interface DonationUnitExpiredMessage{ 174 h_donation_unit_pub: HashCode; 175 donau_pub: EddsaPublicKey; 176 donau_sig: EddsaSignature; 177 }