[taler-docs] branch master updated: introducing of additional types, cleanup and clarifications

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new fc23c2d  introducing of additional types, cleanup and clarifications
fc23c2d is described below

commit fc23c2d90a9ef54d0750a01de4cf9ddc228bf603
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Wed Oct 20 12:09:25 2021 +0200

    introducing of additional types, cleanup and clarifications
---
 core/api-common.rst                      |  8 +++
 design-documents/024-age-restriction.rst | 95 +++++++++++++++++++++++---------
 2 files changed, 76 insertions(+), 27 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 155857c..a3baecf 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -222,6 +222,14 @@ hashed data. See `base32`_.
   // 32-byte hash code.
   type ShortHashCode = string;
 
+.. ts:def:: SHA256HashCode
+
+   type SHA256HashCode = ShortHashCode;
+
+.. ts:def:: SHA512HashCode
+
+   type SHA256HashCode = HashCode;
+
 
 Safe Integers
 ^^^^^^^^^^^^^
diff --git a/design-documents/024-age-restriction.rst 
b/design-documents/024-age-restriction.rst
index 0d8d3c3..abd6d0e 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -92,7 +92,7 @@ The main ideas are simple:
    attest for any age group).
 
 #. An age commitment is *bound to a particular coin* by incorporating the
-   SHA512 hash value of the age commitment (i.e. the M public keys) into the
+   SHA256 hash value of the age commitment (i.e. the M public keys) into the
    signature of the coin.  So instead of signing :math:`\text{FDH}_N(C_p)` with
    the RSA private key of a denomination with support for age restriction, we
    sign :math:`\text{FDH}_N(C_p, h_a)`.  Here, :math:`C_p` is the EdDSA public
@@ -116,8 +116,14 @@ The necessary changes in the exchange involve
 Extension for age restriction
 -----------------------------
 
+.. note::
+
+  Registering an extension is defined in
+  :doc:`design document 006 ― Extensions <006-extensions>`.
+
+
 The exchange indicates support for age-restriction in response to ``/keys`` by
-registering the extension ``age_restriction.v1`` with a value type
+registering the extension ``age_restriction`` with a value type
 ``ExtensionAgeRestriction``:
 
 .. ts:def:: ExtensionAgeRestriction
@@ -128,26 +134,57 @@ registering the extension ``age_restriction.v1`` with a 
value type
       // ``critical`` will be set to ``false``.
       critical: false;
 
-      // Age restriction specific fields.
+      // The field ``version`` is mandatory for an extension.  It is of type
+      // `LibtoolVersion`.
+      version: "1";
 
-      // 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 in 
-      // ``ExchangeKeysResponse.age_restricted_denoms``.
-      age_groups: string;
+      // Age restriction specific fields
+     
+      // The age groups.  This field is mandatory and binding in the sense
+      // that its value is taken into consideration when signing the
+      // denominations in `ExchangeKeysResponse`.``age_restricted_denoms``.
+      age_groups: AgeGroups;
    }
 
-Registering an extension is defined in
-:doc:`design document 006 ― Extensions <006-extensions>`.
+Age Groups
+~~~~~~~~~~
+
+Age groups are represented as a finite list of positive, increasing integers
+that mark the beginning of the *next* age group.  The value 0 implicitly marks
+the beginning of the first age group and the first number in the list marks the
+beginning of the *second* age group.  Age groups are encoded as a colon
+separated string of integer values.  They are refered to by their *slot*, i.e.
+"age group 3" is the age group that starts with the 3. integer in the list.
+
+For example: the string "8:10:12:14:16:18:21" represents the age groups
+
+0. {0,1,2,3,4,5,6,7}
+#. {8,9}
+#. {10,11}
+#. {12,13}
+#. {14,15}
+#. {16,17}
+#. {18,19,20}
+#. {21, ⋯ }
+
+The field ``age_groups`` of type `AgeGroups` is mandatory and binding in the
+sense that its value is taken into consideration when signing the denominations
+in ``ExchangeKeysResponse.age_restricted_denoms``.
+
+.. ts:def:: AgeGroups
+
+   // Representation of the age groups as colon 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".
+   type AgeGroups = string;
+
 
 Age restricted denominations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If age-restriction is registered as an extension under the name
-``age_restriction.v1``, as described above, the root-object
+``age_restriction``, 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 during the modified ``refresh`` and ``deposit``
@@ -177,7 +214,7 @@ changed since the given timestamp.
 
    // 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
+   // ``age_restriction`` is registered under ``entensions`` with type
    // ``ExtensionAgeRestriction``.
    //
    // The data structure for each denomination is the same as for the
@@ -206,7 +243,7 @@ SQL changes
 
 The exchange has to mark denominations with support for age restriction as such
 in the database.  Also, during the melting phase of the refresh operation, the
-exchange will have to persist the SHA512 hash of the age commitment of the
+exchange will have to persist the SHA256 hash of the age commitment of the
 original coin.
 
 The schema for the exchange is changed as follows:
@@ -230,7 +267,7 @@ The schema for the exchange is changed as follows:
    ALTER TABLE refresh_commitments
      ADD COLUMN age_commitment_h BYTEA CHECK (LENGTH(age_commitment_h)=64);
    COMMENT ON COLUMN refresh_commitments.age_commitment_h
-     IS 'SHA512 hash of the age commitment of the old coin, iff the 
corresponding
+     IS 'SHA256 hash of the age commitment of the old coin, iff the 
corresponding
          denomimination has support for age restriction, NULL otherwise.';
    COMMIT;
 
@@ -256,13 +293,17 @@ restriction).  Therefore, in the 
``/coins/$COIN_PUB/melt`` POST request, the
    interface MeltRequest {
       ...
 
-      // SHA512 hash of the age commitment of the coin, IFF the denomination
+      // SHA256 hash of the age commitment of the coin, IFF the denomination
       // has age restriction support.  MUST be omitted otherwise.
-      age_commitment_hash?: HashCode;
+      age_commitment_hash?: AgeCommitmentHash;
       
       ...
    }
 
+.. ts:def:: AgeCommitmentHash
+
+   type AgeCommitmentHash = SHA256HashCode;
+
 The responses to the POST request remain the same.
 
 For normal denominations *without* support for age restriction, the calculation
@@ -324,7 +365,7 @@ As always, the merchant has to provide the public key of a 
coin during a POST
 to ``/coins/$COIN_PUB/deposit``.  However, for coins with age restriction, the
 signature check requires the hash of the age commitment.  Therefore the request
 object ``DepositRequest`` is extended by an optional field
-``age_commitment_hash`` which MUST be set (with the SHA512 hash of the age
+``age_commitment_hash`` which MUST be set (with the SHA256 hash of the age
 commitment), iff the corresponding denomination had support for age restriction
 enabled.  The merchant has received this value prior from the customer during
 purchase.
@@ -335,9 +376,9 @@ purchase.
    ...
 
    // Iff the corresponding denomination had support for age restriction
-   // enabled, this field MUST contain the SHA512 value of the age commitment 
that
+   // enabled, this field MUST contain the SHA256 value of the age commitment 
that
    // was provided during the purchase.
-   age_commitment_hash?: HashCode;
+   age_commitment_hash?: AgeCommitmentHash;
 
    ...
    }
@@ -388,7 +429,7 @@ this value will not be smaller than, say, 8, and not larger 
than, say, 21.
 
 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.
+extension ``age_restriction`` for age restriction from the exchange.
 
 
 Making the payment
@@ -441,11 +482,11 @@ 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
+   .. 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
+   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 SHA256 hash value of the vector in
    ``age_commitment``.
 
 #. the minimum age requirement by checking the signature in ``minimum_age_sig``

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.