Define age restriction as extension

1 files changed, 80 insertions, 34 deletions

diff --git a/design-documents/024-age-restriction.rst b/design-documents/024-age-restriction.rst
index 1d73fbc0..c7433f00 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -37,8 +37,8 @@ TODO
 Proposed Solution
 =================
 
-We propose an extension to GNU Taler for age-restriction that can be enabled
-optionally by an Exchange¹).
+We propose an extension to GNU Taler for age-restriction that can be enabled by
+an Exchange¹).
 
 Once enabled, coins with age restrictions can be withdrawn by parents/warden
 who can choose to **commit** the coins to a certain maximum age out of a
@@ -58,8 +58,8 @@ The proposed solution maintains the guarantees of GNU Taler with respect to
 anonymity and unlinkability. (TODO: refer to the paper, once published)
 
 ¹) Once the feature is enabled and the age groups are defined, the exchange has
-to stick to that decision until the support for age groups are disabled.  We
-might reconsider this design decision at some point.
+to stick to that decision until the support for age restriction is disabled.
+We might reconsider this design decision at some point.
 
 
 Building Blocks
@@ -74,50 +74,98 @@ Changes in the Exchange
 
 The necessary changes in the exchange involve
 
-* indication of support for age restriction
+* indication of support for age restriction as an extension
 * modification of the refresh protocol (both, commit and reveal phase)
 * modification of the deposit protocol
 
 
-Support for Age Restriction
----------------------------
+Extension for age restriction
+-----------------------------
 
-The exchange indicates support for age-restriction in response to ``/keys`` in
-an optional field ``age_restriction`` with new type ``AgeRestriction``:
+The exchange indicates support for age-restriction in response to ``/keys`` by
+registering the extension ``age_restriction.v1`` with a value type
+``ExtensionAgeRestriction``:
 
-.. ts:def:: AgeRestriction
+.. ts:def:: ExtensionAgeRestriction
+
+   interface ExtensionAgeRestriction {
+      // The fields ``description``and ``required`` are mandatory for each
+      // extension.
+      
+      // Description will be something like:
+      // "Support for age restriction version 1 enabled. See
+      //  https://docs.taler.net/design-documents/024-age-restriction.html";
+      description: string;
+
+      // Age restriction is not required to be supported by a wallet or
+      // merchant, so ``required`` will be set to ``false``.
+      required: boolean;
+
+      // Age restriction specific fields.
 
-   interface AgeRestriction {
       // Representation of the age groups as comma separated edges: Increasing
       // from left to right, the values mark the begining of an age group up
       // to, but not including the next value.  The initial age group starts at
       // 0 and is not listed.  Example: "8:10:12:14:16:18:21".
       // This field is mandatory and binding in the sense that its value is
-      // taken into consideration when signing the denominations below.
+      // taken into consideration when signing the denominations in 
+      // ``ExchangeKeysResponse.age_restricted_denoms``.
       age_groups: string;
+   }
 
-      // List of denominations that support age-restriction with the age groups
-      // given in ``age_groups``.  The data structure is the same as for the
-      // denominations in ``ExchangeKeysResponse.denoms``.
-      // **However**, the following differences apply for each denomination in
-      // the list:
-      //
-      //  1. The value of ``TALER_DenominationKeyValidityPS.denom_hash`` 
-      //     is taken over the public key of the denomination __and__ the
-      //     string in ``age_groups``.
-      //
-      //  2. The value of ``TALER_DenominationKeyValidityPS.purpose`` is set to
-      //     TALER_SIGNATURE_MASTER_AGE_RESTRICTED_DENOMINATION_KEY_VALIDITY
-      denoms: Denom[];
-
-      // Same role as ``ExchangeKeysResponse.eddsa_sig``, but only for the
-      // denominations listed in ``denoms`` above for age restriction.  The public
-      // EdDSA key of the exchange that was used to generate the signature is the
-      // same as ``ExchangeKeysResponse.eddsa_pub``.
-      eddsa_sig: EddsaSignature;
+Registering an extension is defined in
+:doc:`design document 006 *Extensions* <006-extensions>`.
+
+Age restricted denominations
+----------------------------
+
+If age-restriction is registered as an extension under the name
+``age_restriction.v1``, as described above, the root-object
+``ExchangeKeysResponse`` in response to ``/keys`` MUST be extended by an
+additional field ``age_restricted_denoms``.  This is an *additional* list of
+denominations that must be used for during modified ``refresh`` and ``deposit``
+operations (see below).
+
+The data structure for those denominations is the same as for the regular ones
+in ``ExchangeKeysResponse.denoms``.  **However**, the following differences
+apply for each denomination in the list:
+
+1. The value of ``TALER_DenominationKeyValidityPS.denom_hash``
+   is taken over the public key of the denomination **and** the string in
+   ``ExtensionAgeRestriction.age_groups`` from the corresponding extension
+   object (see above).
+
+2. The value of ``TALER_DenominationKeyValidityPS.purpose`` is set to
+   ``TALER_SIGNATURE_MASTER_AGE_RESTRICTED_DENOMINATION_KEY_VALIDITY``.
+
+.. ts:def:: ExchangeKeysResponse
+
+   interface ExchangeKeysResponse {
+   //...
+
+   // List of denominations that support age-restriction with the age groups
+   // given in age_groups.  This is only set **iff** the extension
+   // ``age_restriction.v1`` is registered under ``entensions`` with type
+   // ``ExtensionAgeRestriction``.
+   //
+   // The data structure for each denomination is the same as for the
+   // denominations in ExchangeKeysResponse.denoms.  **However**, the
+   // following differences apply for each denomination in the list:
+   //
+   //  1. The value of TALER_DenominationKeyValidityPS.denom_hash
+   //     is taken over the public key of the denomination __and__ the
+   //     string in ``ExtensionAgeRestriction.age_groups`` from the
+   //     corresponding extension object.
+   //
+   //  2. The value of TALER_DenominationKeyValidityPS.purpose is set to
+   //     TALER_SIGNATURE_MASTER_AGE_RESTRICTED_DENOMINATION_KEY_VALIDITY
+   age_restricted_denoms: Denoms[];
+
+   //...
    }
 
 
+
 Refresh
 -------
 
@@ -132,9 +180,7 @@ TODO: Add opaque hash value of the commitments to the protocol
 Changes in the Merchant
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-TODO
-
-* Spending protocol
+TODO: Spending protocol
 
 
 Changes in the Wallet