From 2d7ebea9c5e3474350bf7d82b41d411ef3319e49 Mon Sep 17 00:00:00 2001 From: Özgür Kesim Date: Sun, 17 Oct 2021 13:06:53 +0200 Subject: added protocol changes to the merchant API --- design-documents/024-age-restriction.rst | 104 ++++++++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 8 deletions(-) diff --git a/design-documents/024-age-restriction.rst b/design-documents/024-age-restriction.rst index efa140c2..48a258d1 100644 --- a/design-documents/024-age-restriction.rst +++ b/design-documents/024-age-restriction.rst @@ -103,8 +103,8 @@ TODO: Summarize the design based on the five functions ``Commit()``, Özgür and Christian is published. -Changes in the Exchange -^^^^^^^^^^^^^^^^^^^^^^^ +Changes in the Exchange API +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The necessary changes in the exchange involve @@ -292,7 +292,7 @@ Refresh - reveal phase During the reveal phase -- that is upon POST to ``/refreshes/$RCH/reveal`` -- the client has to provide the original age commitment of the old coin (i.e. the vector of public keys), iff the corresponding denomination had support for age -restriction. The size of the vector ist defined by the Exchange implictely as +restriction. The size of the vector ist defined by the Exchange implicetly as the amount of age groups defined in the field ``.age_groups`` of the ``ExtensionAgeRestriction``. @@ -304,7 +304,7 @@ the amount of age groups defined in the field ``.age_groups`` of the // Iff the corresponding denomination has support for age restriction, // the client MUST provide the original age commitment, i.e. the vector // of public keys. - // The size of the vector ist defined by the Exchange implictely as the + // The size of the vector ist defined by the Exchange implicetly as the // amount of age groups defined in the field ``.age_groups`` of the // ``ExtensionAgeRestriction``. old_age_commitment?: EddsaPublicKey[]; @@ -342,7 +342,8 @@ purchase. ... } -Again, the exchange can now check the validity of the coin by evaluating +Again, the exchange can now check the validity of the coin with age restriction +by evaluating .. math:: \text{FDH}_N(C_p, h_a)\; \stackrel{?}{=}\; \left(\sigma_C\right)^{e} \;\;\text{mod}N @@ -357,10 +358,97 @@ TODO: maybe rename this field into something more opaque, like -Changes in the Merchant -^^^^^^^^^^^^^^^^^^^^^^^ +Changes in the Merchant API +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TODO: Spending protocol + +Claiming the order +------------------ + +If an order requires a minimum age, the merchant MUST express that required +minimum age in response to order claim by the wallet, that is, a POST to +``[/instances/$INSTANCE]/orders/$ORDER_ID/claim``. + +The object ``ContractTerms`` is extended by an optional field +``required_minimum_age`` that can be any integer greater than 0. In reality +this value will not be smaller than, say, 8, and not larger than, say, 21. + +.. ts:def:: ContractTerms + + interface ContractTerms { + ... + + // If the order requires a minimum age greater than 0, this field is set + // to the integer value of that age. In reality this value will not be + // smaller than, say, 8, and not larger than, say, 21. + required_minimum_age?: Integer; + + ... + } + +By sending the contract term with the field ``required_minimum_age`` set to an +non-zero integer value, the merchant implicetly signals that it understands the +extension ``age_restriction.v1`` for age restriction from the exchange. + + +Making the payment +------------------ + +If the ``ContractTerms`` had a non-zero value in field +``required_minimum_age``, the wallet has to provide evidence of that minimum +age + +#. by using coins which are of denominations that have age support enabled + +#. *and* ―for each coin― it has the right private key of the restricted age + commitment to the age group into which the required minimum age falls (i.e. + a non-empty entry at the right index in vector of EdDSA keys, see above). + +#. and signs the required minimum age with each coin's private key + corresponding to the age group, + +#. and sends ―for each coin― the complete age commitment and the signature to + the merchant. + + +For doing so, the object ``CoinPaySig`` used within a ``PayRequest`` during a +POST to ``[/instances/$INSTANCE]/orders/$ORDER_ID/pay`` is extended as follows: + +.. ts:def:: CoinPaySig + + export interface CoinPaySig { + ... + + // If a minimum age was required by the order and the wallet had coins that + // are at least commited to the corresponding age group, this is the + // signature of the minimum age as a string, using the private key to the + // corresponding age group. + minimum_age_sig?: EddsaSignature; + + // If a minium age was required by the order, this is age commitment bound + // to the coin, i.e. the complete vector of EdDSA public keys, one for each + // age group (as defined by the exchange). + age_commitment?: EddsaPublicKey[]; + + } + + +The merchant can now verify + +#. the validity of each (age restricted) coin by evaluating + + .. math:: \text{FDH}_N(C_p, h_a)\; \stackrel{?}{=}\; \left(\sigma_C\right)^{e} \;\;\text{mod}N + + Again, :math:`C_p` is the EdDSA public key of a coin, :math:`\sigma_C` is its + signature, :math:`\langle e, N \rangle` is the RSA public key of the + denomination and :math:`h_a` is the SHA512 hash value of the vector in + ``age_commitment``. + +#. the minimum age requirement by checking the signature in ``minimum_age_sig`` + against the public key ``age_commitment[k]`` of the corresponding age group, + say, ``k``. (The minimum age must fall into the age group at index ``k`` as + defined by the exchange) + Changes in the Wallet -- cgit v1.2.3