commit 8817432a08c5da7871e3252f9a6da05d287f3143
parent 0337d0b116ffe5fba2b4b16b581578d66d03291d
Author: Pius Loosli <loosp2@bfh.ch>
Date: Thu, 12 Oct 2023 11:46:34 +0200
Donau: rework crypto in /issue, rename remainin "denomation" to "donation unit"
Diffstat:
| M | core/api-donau.rst | | | 83 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- |
1 file changed, 72 insertions(+), 11 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -36,7 +36,7 @@ This is intended to provide a quick overview of the whole REST API. For a more d
The chapters group the families of requests frequently encountered when using the donau API:
-* :ref:`Status information<donau_status>`: get the public signing keys of the donau, the denomination unit key, the donaus config or some entropy
+* :ref:`Status information<donau_status>`: get the public signing keys of the donau, the donation unit key, the donaus config or some entropy
* :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts for blinded unique donor ids.
* :ref:`Submit receipts<donau_submit>`: Receive the receipts and, if valid, add all of it's donation units to the donor total. Returns a signature on the total yearly donation amount, hash of taxid+salt and year.
* :ref:`Charity administration and status information<donau_charity>`:
@@ -74,7 +74,7 @@ long-term offline signing key of the Donau, which clients should cache.
timestamp. The given value must be an unsigned
64-bit integer representing seconds after 1970. If
the timestamp does not exactly match the
- ``stamp_start`` of one of the denomination keys, all
+ ``stamp_start`` of one of the donation unit keys, all
keys are returned.
**Response:**
@@ -128,7 +128,7 @@ long-term offline signing key of the Donau, which clients should cache.
interface DonationUnitKeyGroupRsa extends DonationUnitKeyGroupCommon {
cipher: "RSA";
- denoms: ({
+ donation_units: ({
rsa_pub: RsaPublicKey;
} & DonationUnitKeyCommon)[];
}
@@ -138,7 +138,7 @@ long-term offline signing key of the Donau, which clients should cache.
interface DonationUnitKeyGroupCs extends DonationUnitKeyGroupCommon {
cipher: "CS";
- denoms: ({
+ donation_units: ({
cs_pub: Cs25519Point;
} & DonationUnitKeyCommon)[];
}
@@ -156,7 +156,7 @@ long-term offline signing key of the Donau, which clients should cache.
interface DonationUnitKeyCommon {
- // For which year is this denomination unit key valid.
+ // For which year is this donation unit key valid.
year: Integer;
// Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not
@@ -186,7 +186,7 @@ long-term offline signing key of the Donau, which clients should cache.
interface CSDonationUnitKey {
cipher: "CS";
- // Public key of the denomination.
+ // Public key of the donation unit.
cs_public_key: Cs25519Point;
}
@@ -207,7 +207,7 @@ long-term offline signing key of the Donau, which clients should cache.
.. note::
- Both the individual donation units *and* the denomination list is signed,
+ Both the individual donation units *and* the donation units list is signed,
allowing customers to prove that they received an inconsistent list.
.. http:get:: /seed
@@ -298,19 +298,80 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
interface BDID {
donau_pub_hash: HashCode;
- taxpayer_blinded_id: CoinEnvelope; // maybe copy+paste data type and rename it
- taxid_hashed: HashCode; // NO: needs to be blinded hash: FDH_n(H(taxid,salt), nonce) * b^e mod n
- nonce: string; // NO!
+ taxpayer_blinded_id: BDIDEnvelope;
+ // already in BDIDenvelope
+ // blinded_unique_donor_id: HashCode; // NO: needs to be blinded hash: FDH_n(H(taxid,salt), nonce) * b^e mod n
}
+ .. ts:def:: BDIDEnvelope
+
+ type BDIDEnvelope = RSABDIDEnvelope | CSBDIDEnvelope ;
+
+ .. ts:def:: RSABDIDEnvelope
+
+ interface RSABDIDEnvelope {
+ cipher: "RSA" | "RSA+age_restricted";
+ rsa_blinded_UDID: string; // Crockford Base32 encoded
+ }
+
+ .. ts:def:: CSBDIDEnvelope
+
+ // For donation unit signatures based on Blind Clause-Schnorr, the UDID
+ // 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 {
+ 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
+
+ // Secret for blinding/unblinding.
+ // An RSA blinding secret, which is basically
+ // a 256-bit nonce, converted to Crockford Base32.
+ type BDIDBlindingKeyP = string;
+
.. ts:def:: BSDonationReceipts
interface DonationReceipts {
blind_signed_receipt_signatures: DonationReceiptSignature[];
}
- .. ts:def:: DonationReceiptSignature // FIXME: see BlindedDenominationSignature, not Envelope!!
+ .. ts:def:: DonationReceiptSignature
+ .. ts:def:: BlindedDonationReceiptSignature
+
+ type BlindedDonationReceiptSignature =
+ | RsaBlindedDonationReceiptSignature
+ | CSBlindedDonationReceiptSignature;
+
+ .. ts:def:: BlindedDonationReceiptSignature
+
+ interface RsaBlindedDonationReceiptSignature {
+ cipher: "RSA";
+
+ // (blinded) RSA signature
+ blinded_rsa_signature: BlindedRsaSignature;
+ }
+
+ .. ts:def:: CSBlindedDonationReceiptSignature
+
+ interface CSBlindedDonationReceiptSignature {
+ type: "CS";
+
+ // Signer chosen bit value, 0 or 1, used
+ // in Clause Blind Schnorr to make the
+ // ROS problem harder.
+ b: Integer;
+
+ // Blinded scalar calculated from c_b.
+ s: Cs25519Scalar;
+ }
+
+
type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ;
.. ts:def:: RSADonationReceiptSignature
