commit 1f24da95f9bda547be7663b5be51ea46fd2890ce
parent ba4d8e114ef00fce5769a0a98db8c42d2461dbb8
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Wed, 22 Dec 2021 15:03:56 +0100
add overview
Diffstat:
1 file changed, 282 insertions(+), 252 deletions(-)
diff --git a/draft-schanzen-gns.xml b/draft-schanzen-gns.xml
@@ -162,6 +162,33 @@
</t>
</section>
</section>
+ <section anchor="overview" numbered="true" toc="default">
+ <name>Overview</name>
+ <t>
+ In GNS, any user may create and manage one or more cryptographically
+ secured zones (<xref target="zones"/>).
+ A zone can be populated with mappings from labels to resource records by
+ its owner (<xref target="rrecords"/>).
+ Names can be delegated to other zones using delegation records and in
+ order to support (legacy) applications as well as facilitate the use
+ of petnames, GNS defines auxiliary record types in addition to
+ supporting traditional DNS records.
+ Resource records of zones are grouped by label, encrypted and signed
+ before beging published as RRBLOCK in a distributed key-value storage
+ (<xref target="publish"/>).
+ In this process, unique zone identification is hidden from the network
+ through the use of key blinding.
+ Starting from a configurable root zone, names are resolved following zone
+ delegations which are iteratively queried from the storage (<xref target="resolution"/>).
+ </t>
+ <t>
+ In this document, the "implementor" refers to the developer building
+ a GNS implementation including, for example, zone management tools and
+ name resolution components.
+ An "application" refers to a component which uses a GNS implementation
+ to resolve records from the network and (usually) processes its contents.
+ </t>
+ </section>
<section anchor="zones" numbered="true" toc="default">
<name>Zones</name>
<t>
@@ -366,7 +393,257 @@ zid := GNSCrockfordDecode(zkl)
<artwork name="" type="" align="left" alt=""><![CDATA[
zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
]]></artwork>
+ </section>
+ <section anchor="revocation" numbered="true" toc="default">
+ <name>Zone Revocation</name>
+ <t>
+ Whenever a recursive resolver encounters a new GNS zone, it MUST
+ check against the local revocation list whether the respective
+ zone key has been revoked. If the zone key was revoked, the
+ resolution MUST fail with an empty result set.
+ </t>
+ <t>
+ In order to revoke a zone key, a signed revocation object MUST be
+ published.
+ This object MUST be signed using the private zone key.
+ The revocation object is broadcast to the network.
+ The specification of the broadcast mechanism is out of scope of this
+ document.
+ A possible broadcast mechanism for efficient flooding in a distributed
+ network is implemented in <xref target="GNUnet"/>.
+ Alternatively, revocation objects could also be distributed via a
+ distributed ledger or a trusted central server.
+ To prevent
+ flooding attacks, the revocation message MUST contain a proof of work
+ (PoW).
+ The revocation message including the PoW MAY be calculated
+ ahead of time to support timely revocation.
+ </t>
+ <t>
+ For all occurences below, "Argon2id" is the Password-based Key
+ Derivation Function as defined in <xref target="RFC9106" />. For the
+ PoW calculations the algorithm is instantiated with the
+ following parameters:
+ </t>
+ <dl>
+ <dt>S</dt>
+ <dd>The salt. Fixed 16-byte string: "GnsRevocationPow".</dd>
+ <dt>t</dt>
+ <dd>Number of iterations: 3</dd>
+ <dt>m</dt>
+ <dd>Memory size in KiB: 1024</dd>
+ <dt>T</dt>
+ <dd>Output length of hash in bytes: 64</dd>
+ <dt>p</dt>
+ <dd>Parallelization parameter: 1</dd>
+ <dt>v</dt>
+ <dd>Algorithm version: 0x13</dd>
+ <dt>y</dt>
+ <dd>Algorithm type (Argon2id): 2</dd>
+ <dt>X</dt><dd>Unused</dd>
+ <dt>K</dt><dd>Unused</dd>
+ </dl>
+ <t>
+ <xref target="figure_revocation"/> illustrates the wire format
+ of the message string "P" on which the PoW is calculated.
+ </t>
+ <figure anchor="figure_revocation">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+0 8 16 24 32 40 48 56
++-----+-----+-----+-----+-----+-----+-----+-----+
+| POW |
++-----------------------------------------------+
+| TIMESTAMP |
++-----------------------------------------------+
+| ZONE TYPE | PUBLIC ZONE KEY |
++-----+-----+-----+-----+ |
+/ /
+/ /
++-----+-----+-----+-----+-----+-----+-----+-----+
+ ]]></artwork>
+ </figure>
+ <t>The Wire Format of the PoW Message String.</t>
+ <dl>
+ <dt>POW</dt>
+ <dd>
+ A 64-bit solution to the PoW. In network byte order.
+ </dd>
+ <dt>TIMESTAMP</dt>
+ <dd>
+ denotes the absolute 64-bit date when the revocation was computed.
+ In microseconds since midnight (0 hour), January 1, 1970 in network
+ byte order.
+ </dd>
+ <dt>PUBLIC KEY</dt>
+ <dd>
+ is the 256-bit public key zk of the zone which is being revoked and
+ the key to be used to verify SIGNATURE. The
+ wire format of this value is defined in <xref target="RFC8032" />,
+ Section 5.1.5.
+ </dd>
+ </dl>
+ <t>
+ Traditionally, PoW schemes require to find a POW such that
+ at least D leading zeroes are found in the hash result.
+ D is then referred to as the difficulty of the PoW.
+ In order to reduce the variance in time it takes to calculate the
+ PoW, we require that a number Z different PoWs must be
+ found that on average have D leading zeroes.
+ </t>
+ <t>
+ The resulting proofs may then published and disseminated. The concrete
+ dissemination and publication methods are out of scope of this
+ document. Given an average difficulty of D, the proofs have an
+ expiration time of EPOCH. With each additional bit difficulty, the
+ lifetime of the proof is prolonged for another EPOCH.
+ Consequently, by calculating a more difficult PoW, the lifetime of the
+ proof can be increased on demand by the zone owner.
+ </t>
+ <t>
+ The parameters are defined as follows:
+ </t>
+ <dl>
+ <dt>Z</dt>
+ <dd>The number of PoWs required is fixed at 32.</dd>
+ <dt>D</dt>
+ <dd>The difficulty is fixed at 22.</dd>
+ <dt>EPOCH</dt>
+ <dd>A single epoch is fixed at 365 days.</dd>
+ </dl>
+ <t>
+ The revocation message wire format is illustrated in
+ <xref target="figure_revocationdata"/>.
+ </t>
+ <figure anchor="figure_revocationdata">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+0 8 16 24 32 40 48 56
++-----+-----+-----+-----+-----+-----+-----+-----+
+| TIMESTAMP |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| TTL |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| POW_0 |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| ... |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| POW_Z-1 |
++-----------------------------------------------+
+| ZONE TYPE | PUBLIC ZONE KEY |
++-----+-----+-----+-----+ |
+/ /
+/ /
++-----+-----+-----+-----+-----+-----+-----+-----+
+| SIGNATURE |
+/ /
+/ /
+| |
++-----+-----+-----+-----+-----+-----+-----+-----+
+ ]]></artwork>
+ </figure>
+ <t>The Revocation Message Wire Format.</t>
+ <dl>
+ <dt>TIMESTAMP</dt>
+ <dd>
+ denotes the absolute 64-bit date when the revocation was computed.
+ In microseconds since midnight (0 hour), January 1, 1970 in network
+ byte order. This is the same value as the timestamp used in the
+ individual PoW calculations.
+ </dd>
+ <dt>TTL</dt>
+ <dd>
+ denotes the relative 64-bit time to live of of the record in
+ microseconds also in network byte order. This field is informational
+ for a verifier. The verifier may discard revocation if the TTL
+ indicates that it is already expired. However, the actual TTL of the
+ revocation must be determined by examining the leading zeros in the
+ proof of work calculation.
+ </dd>
+ <dt>POW_i</dt>
+ <dd>
+ The values calculated as part of the PoW, in network byte order.
+ Each POW_i MUST be unique in the set of POW values.
+ To facilitate fast verification
+ of uniqueness, the POW values must be given in strictly
+ monotonically increasing order in the message.
+ </dd>
+ <dt>ZONE TYPE</dt>
+ <dd>
+ The 32-bit zone type corresponding to the zone public key.
+ </dd>
+ <dt>ZONE PUBLIC KEY</dt>
+ <dd>
+ is the public key zk of the zone which is being revoked and
+ the key to be used to verify SIGNATURE.
+ </dd>
+ <dt>SIGNATURE</dt>
+ <dd>
+ A signature over a timestamp and the public zone zk of the zone
+ which is revoked and corresponds to the key used in the PoW.
+ The signature is created using the Sign() function of
+ the cryptosystem of the zone and the private zone key
+ (see <xref target="ztype" />).
+ </dd>
+ </dl>
+ <t>
+ The signature over the public key covers a 32-bit pseudo header
+ conceptually prefixed to the public key. The pseudo header includes
+ the key length and signature purpose. The wire format is illustrated
+ in <xref target="figure_revsigwithpseudo"/>.
+ </t>
+ <figure anchor="figure_revsigwithpseudo">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+0 8 16 24 32 40 48 56
++-----+-----+-----+-----+-----+-----+-----+-----+
+| SIZE (0x30) | PURPOSE (0x03) |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| TIMESTAMP |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| ZONE TYPE | ZONE PUBLIC KEY |
++-----+-----+-----+-----+ |
+/ /
+/ /
++-----+-----+-----+-----+-----+-----+-----+-----+
+ ]]></artwork>
+ </figure>
+ <t>The Wire Format of the Revocation Data for Signing.</t>
+ <dl>
+ <dt>SIZE</dt>
+ <dd>
+ A 32-bit value containing the length of the signed data in bytes
+ in network byte order.
+ </dd>
+ <dt>PURPOSE</dt>
+ <dd>
+ A 32-bit signature purpose flag. This field MUST be 3 (in network
+ byte order).
+ </dd>
+ <dt>ZONE TYPE</dt>
+ <dd>
+ The 32-bit zone type corresponding to the zone public key.
+ </dd>
+ <dt>ZONE PUBLIC KEY / TIMESTAMP</dt>
+ <dd>Both values as defined in the revocation data object above.</dd>
+ </dl>
+ <t>
+ In order to verify a revocation the following steps must be taken,
+ in order:
+ </t>
+ <ol>
+ <li>The current time MUST be between TIMESTAMP and
+ TIMESTAMP+TTL.</li>
+ <li>The signature MUST match the public key.</li>
+ <li>The set of POW values MUST NOT contain duplicates.</li>
+ <li>The average number of leading zeroes resulting from the provided
+ POW values D' MUST be greater than D.</li>
+ <li>The validation period (TTL) of the revocation is calculated as
+ (D'-D) * EPOCH * 1.1. The EPOCH is extended by
+ 10% in order to deal with unsynchronized clocks.
+ The TTL added on top of the TIMESTAMP yields the
+ expiration date.</li>
+ </ol>
</section>
+
+
</section>
<section anchor="rrecords" numbered="true" toc="default">
<name>Resource Records</name>
@@ -438,8 +715,10 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
<t>
Flags indicate metadata surrounding the resource record. A flag
value of 0 indicates that all flags are unset.
- Any GNS implementation MUST process all flags which are set in the
- FLAGS field. If an implementation encounters a flag which it does not
+ Applications creating resource records MUST set all bits which are
+ not defined as a flag to 0. As additional flags may be defined in
+ future protocol versions, applications MUST ignore unknown flags.
+ If an implementation encounters a flag which it does not
recognize, the resource record is not valid and MUST be discarded.
<xref target="figure_flag"/>
illustrates the flag distribution in the 32-bit flag value of a
@@ -1326,256 +1605,7 @@ q := SHA512 (HDKD-Public(zk, label))
</dl>
</section>
</section>
- <section anchor="revocation" numbered="true" toc="default">
- <name>Zone Revocation</name>
- <t>
- Whenever a recursive resolver encounters a new GNS zone, it MUST
- check against the local revocation list whether the respective
- zone key has been revoked. If the zone key was revoked, the
- resolution MUST fail with an empty result set.
- </t>
- <t>
- In order to revoke a zone key, a signed revocation object MUST be
- published.
- This object MUST be signed using the private zone key.
- The revocation object is broadcast to the network.
- The specification of the broadcast mechanism is out of scope of this
- document.
- A possible broadcast mechanism for efficient flooding in a distributed
- network is implemented in <xref target="GNUnet"/>.
- Alternatively, revocation objects could also be distributed via a
- distributed ledger or a trusted central server.
- To prevent
- flooding attacks, the revocation message MUST contain a proof of work
- (PoW).
- The revocation message including the PoW MAY be calculated
- ahead of time to support timely revocation.
- </t>
- <t>
- For all occurences below, "Argon2id" is the Password-based Key
- Derivation Function as defined in <xref target="RFC9106" />. For the
- PoW calculations the algorithm is instantiated with the
- following parameters:
- </t>
- <dl>
- <dt>S</dt>
- <dd>The salt. Fixed 16-byte string: "GnsRevocationPow".</dd>
- <dt>t</dt>
- <dd>Number of iterations: 3</dd>
- <dt>m</dt>
- <dd>Memory size in KiB: 1024</dd>
- <dt>T</dt>
- <dd>Output length of hash in bytes: 64</dd>
- <dt>p</dt>
- <dd>Parallelization parameter: 1</dd>
- <dt>v</dt>
- <dd>Algorithm version: 0x13</dd>
- <dt>y</dt>
- <dd>Algorithm type (Argon2id): 2</dd>
- <dt>X</dt><dd>Unused</dd>
- <dt>K</dt><dd>Unused</dd>
- </dl>
- <t>
- <xref target="figure_revocation"/> illustrates the wire format
- of the message string "P" on which the PoW is calculated.
- </t>
- <figure anchor="figure_revocation">
- <artwork name="" type="" align="left" alt=""><![CDATA[
-0 8 16 24 32 40 48 56
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| POW |
-+-----------------------------------------------+
-| TIMESTAMP |
-+-----------------------------------------------+
-| ZONE TYPE | PUBLIC ZONE KEY |
-+-----+-----+-----+-----+ |
-/ /
-/ /
-+-----+-----+-----+-----+-----+-----+-----+-----+
- ]]></artwork>
- </figure>
- <t>The Wire Format of the PoW Message String.</t>
- <dl>
- <dt>POW</dt>
- <dd>
- A 64-bit solution to the PoW. In network byte order.
- </dd>
- <dt>TIMESTAMP</dt>
- <dd>
- denotes the absolute 64-bit date when the revocation was computed.
- In microseconds since midnight (0 hour), January 1, 1970 in network
- byte order.
- </dd>
- <dt>PUBLIC KEY</dt>
- <dd>
- is the 256-bit public key zk of the zone which is being revoked and
- the key to be used to verify SIGNATURE. The
- wire format of this value is defined in <xref target="RFC8032" />,
- Section 5.1.5.
- </dd>
- </dl>
- <t>
- Traditionally, PoW schemes require to find a POW such that
- at least D leading zeroes are found in the hash result.
- D is then referred to as the difficulty of the PoW.
- In order to reduce the variance in time it takes to calculate the
- PoW, we require that a number Z different PoWs must be
- found that on average have D leading zeroes.
- </t>
- <t>
- The resulting proofs may then published and disseminated. The concrete
- dissemination and publication methods are out of scope of this
- document. Given an average difficulty of D, the proofs have an
- expiration time of EPOCH. With each additional bit difficulty, the
- lifetime of the proof is prolonged for another EPOCH.
- Consequently, by calculating a more difficult PoW, the lifetime of the
- proof can be increased on demand by the zone owner.
- </t>
- <t>
- The parameters are defined as follows:
- </t>
- <dl>
- <dt>Z</dt>
- <dd>The number of PoWs required is fixed at 32.</dd>
- <dt>D</dt>
- <dd>The difficulty is fixed at 22.</dd>
- <dt>EPOCH</dt>
- <dd>A single epoch is fixed at 365 days.</dd>
- </dl>
- <t>
- The revocation message wire format is illustrated in
- <xref target="figure_revocationdata"/>.
- </t>
- <figure anchor="figure_revocationdata">
- <artwork name="" type="" align="left" alt=""><![CDATA[
-0 8 16 24 32 40 48 56
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| TIMESTAMP |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| TTL |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| POW_0 |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| ... |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| POW_Z-1 |
-+-----------------------------------------------+
-| ZONE TYPE | PUBLIC ZONE KEY |
-+-----+-----+-----+-----+ |
-/ /
-/ /
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| SIGNATURE |
-/ /
-/ /
-| |
-+-----+-----+-----+-----+-----+-----+-----+-----+
- ]]></artwork>
- </figure>
- <t>The Revocation Message Wire Format.</t>
- <dl>
- <dt>TIMESTAMP</dt>
- <dd>
- denotes the absolute 64-bit date when the revocation was computed.
- In microseconds since midnight (0 hour), January 1, 1970 in network
- byte order. This is the same value as the timestamp used in the
- individual PoW calculations.
- </dd>
- <dt>TTL</dt>
- <dd>
- denotes the relative 64-bit time to live of of the record in
- microseconds also in network byte order. This field is informational
- for a verifier. The verifier may discard revocation if the TTL
- indicates that it is already expired. However, the actual TTL of the
- revocation must be determined by examining the leading zeros in the
- proof of work calculation.
- </dd>
- <dt>POW_i</dt>
- <dd>
- The values calculated as part of the PoW, in network byte order.
- Each POW_i MUST be unique in the set of POW values.
- To facilitate fast verification
- of uniqueness, the POW values must be given in strictly
- monotonically increasing order in the message.
- </dd>
- <dt>ZONE TYPE</dt>
- <dd>
- The 32-bit zone type corresponding to the zone public key.
- </dd>
- <dt>ZONE PUBLIC KEY</dt>
- <dd>
- is the public key zk of the zone which is being revoked and
- the key to be used to verify SIGNATURE.
- </dd>
- <dt>SIGNATURE</dt>
- <dd>
- A signature over a timestamp and the public zone zk of the zone
- which is revoked and corresponds to the key used in the PoW.
- The signature is created using the Sign() function of
- the cryptosystem of the zone and the private zone key
- (see <xref target="ztype" />).
- </dd>
- </dl>
- <t>
- The signature over the public key covers a 32-bit pseudo header
- conceptually prefixed to the public key. The pseudo header includes
- the key length and signature purpose. The wire format is illustrated
- in <xref target="figure_revsigwithpseudo"/>.
- </t>
- <figure anchor="figure_revsigwithpseudo">
- <artwork name="" type="" align="left" alt=""><![CDATA[
-0 8 16 24 32 40 48 56
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| SIZE (0x30) | PURPOSE (0x03) |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| TIMESTAMP |
-+-----+-----+-----+-----+-----+-----+-----+-----+
-| ZONE TYPE | ZONE PUBLIC KEY |
-+-----+-----+-----+-----+ |
-/ /
-/ /
-+-----+-----+-----+-----+-----+-----+-----+-----+
- ]]></artwork>
- </figure>
- <t>The Wire Format of the Revocation Data for Signing.</t>
- <dl>
- <dt>SIZE</dt>
- <dd>
- A 32-bit value containing the length of the signed data in bytes
- in network byte order.
- </dd>
- <dt>PURPOSE</dt>
- <dd>
- A 32-bit signature purpose flag. This field MUST be 3 (in network
- byte order).
- </dd>
- <dt>ZONE TYPE</dt>
- <dd>
- The 32-bit zone type corresponding to the zone public key.
- </dd>
- <dt>ZONE PUBLIC KEY / TIMESTAMP</dt>
- <dd>Both values as defined in the revocation data object above.</dd>
- </dl>
- <t>
- In order to verify a revocation the following steps must be taken,
- in order:
- </t>
- <ol>
- <li>The current time MUST be between TIMESTAMP and
- TIMESTAMP+TTL.</li>
- <li>The signature MUST match the public key.</li>
- <li>The set of POW values MUST NOT contain duplicates.</li>
- <li>The average number of leading zeroes resulting from the provided
- POW values D' MUST be greater than D.</li>
- <li>The validation period (TTL) of the revocation is calculated as
- (D'-D) * EPOCH * 1.1. The EPOCH is extended by
- 10% in order to deal with unsynchronized clocks.
- The TTL added on top of the TIMESTAMP yields the
- expiration date.</li>
- </ol>
- </section>
-
- <section anchor="resolution" numbered="true" toc="default">
+ <section anchor="resolution" numbered="true" toc="default">
<name>Name Resolution</name>
<t>
Names in GNS are resolved by recursively querying the record storage.
