commit dc4b4366aa1bbeb6ceb6140fdd8baf2913108d30
parent 309f88d19ebf55620d258806e45172244fd3c325
Author: Matyja Lukas Adam <lukas.matyja@students.bfh.ch>
Date: Sat, 25 May 2024 14:03:13 +0200
update donau api
Diffstat:
| M | core/api-donau.rst | | | 152 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
1 file changed, 122 insertions(+), 30 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -249,15 +249,93 @@ Issue receipts
Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`.
-This API is used by the charity to obtain valid, attested donation receipts from the Donau.
+This API is used to obtain valid, attested donation receipts from the Donau.
Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year.
+CSR Issue
+~~~~~~~~~~~
-All incoming `BDID` are recorded under the corresponding charity_id by the Donau.
+.. http:post:: /csr-issue
+
+ Obtain donau-side input values in preparation for a
+ issue receipt step for certain donation unit cipher types,
+ specifically at this point for Clause-Schnorr blind
+ signatures. This API is used by the donor.
+
+ **Request:** The request body must be a `IssuePrepareRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The request was successful, and the response is a `IssuePrepareResponse`. Note that repeating exactly the same request
+ will again yield the same response (assuming none of the donation unit is expired).
+ :http:statuscode:`404 Not found`:
+ The donation unit key is not known to the donau.
+ :http:statuscode:`410 Gone`:
+ The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
+ year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to
+ understand which of the cases this is and handle it accordingly.
+
+ **Details:**
+
+ .. ts:def:: IssuePrepareRequest
+
+ interface IssuePrepareRequest {
+
+ // Nonce to be used by the donau to derive
+ // its private inputs from. Must not have ever
+ // been used before.
+ nonce: CSNonce;
+
+ // Hash of the public key of the donation unit
+ // the request relates to.
+ donation_unit_pub_hash: HashCode;
+
+ }
+
+ .. ts:def:: IssuePrepareResponse
+
+ type IssuePrepareResponse =
+ | DonauIssueValue;
+
+ .. ts:def:: DonauIssueValue
+
+ type DonauIssueValue =
+ | DonauRsaIssueValue
+ | DonauCsIssueValue;
+
+ .. ts:def:: DonauRsaIssueValue
+
+ interface DonauRsaIssueValue {
+ cipher: "RSA";
+ }
+
+ .. ts:def:: DonauCsIssueValue
+
+ interface DonauCsIssueValue {
+ cipher: "CS";
+
+ // CSR R0 value
+ r_pub_0: CsRPublic;
+
+ // CSR R1 value
+ r_pub_1: CsRPublic;
+ }
+
+
+Batch Issue
+~~~~~~~~~~~
+This is the effectiv issue receipts request. Depending on the amount of the donation a
+certain amount of blinded unique donation identifiers, or for short `BUDI`s, are required.
+Every `BUDI` will be signed by the corresponding requested donation unit, which is associated with a value.
+This API is used by the charity but the `BUDIKeyPairs` are coming from the donor.
+
+To make the request idempotent, the hash of the hole request is recorded under the
+corresponding charity_id by the Donau.
.. http:POST:: /batch-issue/$CHARITY_ID
- Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `BDID`.
+ Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `BUDI`s.
**Request:** `IssueReceiptsRequest`
@@ -268,59 +346,63 @@ All incoming `BDID` are recorded under the corresponding charity_id by the Donau
:http:statuscode:`403 Forbidden`:
The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
- At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
+ At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
+ This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
:http:statuscode:`409 Conflict`:
- The donation volume of the charity is not sufficient to issue donation receipts vor all sent in blinded udids. The response is a `IssueError` object.
+ The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
+ The response is a `IssueError` object.
:http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.
+ The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
+ year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code
+ provided to understand which of the cases this is and handle it accordingly.
**Details:**
.. ts:def:: IssueReceiptsRequest
interface IssueReceiptsRequest {
- charity_signature: EddsaSignature;
+ charity_sig: EddsaSignature;
year: Integer;
- bdids: BDID[];
+ budikeypairs: BUDIKeyPairs[];
}
- .. ts:def:: BDID
+ .. ts:def:: BUDIKeyPairs
- interface BDID {
- donau_pub_hash: HashCode;
- taxpayer_blinded_id: BDIDEnvelope;
+ interface BUDIKeyPairs {
+ h_donation_unit_pub: HashCode;
+ blinded_udi: BUDI;
}
- .. ts:def:: BDIDEnvelope
+ .. ts:def:: BUDI
- type BDIDEnvelope = RSABDIDEnvelope | CSBDIDEnvelope ;
+ type BUDI = RSABUDI | CSBUDI ;
- .. ts:def:: RSABDIDEnvelope
+ .. ts:def:: RSABUDI
- interface RSABDIDEnvelope {
+ interface RSABUDI {
cipher: "RSA" | "RSA+age_restricted";
- rsa_blinded_UDID: string; // Crockford Base32 encoded
+ rsa_blinded_udi: string; // Crockford Base32 encoded
}
- .. ts:def:: CSBDIDEnvelope
+ .. ts:def:: CSBUDI
- // For donation unit signatures based on Blind Clause-Schnorr, the UDID
+ // For donation unit signatures based on Blind Clause-Schnorr, the BUDI
// consists of the public nonce and two Curve25519 scalars which are two
// blinded challenges in the Blinded Clause-Schnorr signature scheme.
// See https://taler.net/papers/cs-thesis.pdf for details.
- interface CSBDIDEnvelope {
+ interface CSBUDI {
cipher: "CS" | "CS+age_restricted";
cs_nonce: string; // Crockford Base32 encoded
cs_blinded_c0: string; // Crockford Base32 encoded
cs_blinded_c1: string; // Crockford Base32 encoded
}
- .. ts:def:: BDIDBlindingKeyP
+ .. ts:def:: BUDIBlindingKeyP
// Secret for blinding/unblinding.
// An RSA blinding secret, which is basically
// a 256-bit nonce, converted to Crockford Base32.
- type BDIDBlindingKeyP = string;
+ type BUDIBlindingKeyP = string;
.. ts:def:: BSDonationReceipts
@@ -411,7 +493,9 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
.. http:POST:: /submit
- Send in donation receipts for the past fiscal year, receive signed total back.
+ Send in donation receipts for the current or one of the past fiscal years.
+ The donor will reveive the signed total back, which is called the
+ donation statement.
**Request:** `SubmitDonationReceiptsRequest`
@@ -423,8 +507,6 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
- :http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly. FIXME: text does not match our use case well.
**Details:**
@@ -432,9 +514,9 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
interface SubmitDonationReceiptsRequest{
// hashed taxpayer ID plus salt
- taxnr_hashed: HashCode;
+ h_donor_tax_id: HashCode;
// All donation receipts must be for this year.
- year: Integer;
+ donation_year: Integer;
// Receipts should be sorted by amount.
donation_receipts: DonationReceipt[];
}
@@ -442,9 +524,9 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
.. ts:def:: DonationReceipt
interface DonationReceipt{
- donation_unit_pub_hash: HashCode;
+ h_donation_unit_pub: HashCode;
nonce: string;
- donau_sig: DonationSignature
+ donation_unit_sig: DonationSignature
}
.. ts:def:: DonationSignature
@@ -480,10 +562,20 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
interface SubmitResponse{
// *accepted* total
total: Amount;
- // signature over taxid_hashed, total, year
+ // signature over h_donor_tax_id, total, donation_year
signature: EddsaSignature;
}
+
+ .. ts:def:: DonationUnitExpiredMessage
+
+ interface DonationUnitExpiredMessage{
+ h_donation_unit_pub: HashCode;
+ donau_pub: EddsaPublicKey;
+ donau_sig: EddsaSignature;
+ }
+
+
.. _donau_charity:
---------------------------------------------
