aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Schanzenbach <schanzen@gnunet.org>2021-12-22 15:03:56 +0100
committerMartin Schanzenbach <schanzen@gnunet.org>2021-12-22 15:03:56 +0100
commit1f24da95f9bda547be7663b5be51ea46fd2890ce (patch)
treeea7263daeb81a80fd3a4452e0059e8de88a4948c
parentba4d8e114ef00fce5769a0a98db8c42d2461dbb8 (diff)
downloadlsd0001-1f24da95f9bda547be7663b5be51ea46fd2890ce.tar.gz
lsd0001-1f24da95f9bda547be7663b5be51ea46fd2890ce.zip
add overview
-rw-r--r--draft-schanzen-gns.xml534
1 files changed, 282 insertions, 252 deletions
diff --git a/draft-schanzen-gns.xml b/draft-schanzen-gns.xml
index 673db6d..9f25e38 100644
--- a/draft-schanzen-gns.xml
+++ b/draft-schanzen-gns.xml
@@ -162,6 +162,33 @@
162 </t> 162 </t>
163 </section> 163 </section>
164 </section> 164 </section>
165 <section anchor="overview" numbered="true" toc="default">
166 <name>Overview</name>
167 <t>
168 In GNS, any user may create and manage one or more cryptographically
169 secured zones (<xref target="zones"/>).
170 A zone can be populated with mappings from labels to resource records by
171 its owner (<xref target="rrecords"/>).
172 Names can be delegated to other zones using delegation records and in
173 order to support (legacy) applications as well as facilitate the use
174 of petnames, GNS defines auxiliary record types in addition to
175 supporting traditional DNS records.
176 Resource records of zones are grouped by label, encrypted and signed
177 before beging published as RRBLOCK in a distributed key-value storage
178 (<xref target="publish"/>).
179 In this process, unique zone identification is hidden from the network
180 through the use of key blinding.
181 Starting from a configurable root zone, names are resolved following zone
182 delegations which are iteratively queried from the storage (<xref target="resolution"/>).
183 </t>
184 <t>
185 In this document, the "implementor" refers to the developer building
186 a GNS implementation including, for example, zone management tools and
187 name resolution components.
188 An "application" refers to a component which uses a GNS implementation
189 to resolve records from the network and (usually) processes its contents.
190 </t>
191 </section>
165 <section anchor="zones" numbered="true" toc="default"> 192 <section anchor="zones" numbered="true" toc="default">
166 <name>Zones</name> 193 <name>Zones</name>
167 <t> 194 <t>
@@ -366,7 +393,257 @@ zid := GNSCrockfordDecode(zkl)
366 <artwork name="" type="" align="left" alt=""><![CDATA[ 393 <artwork name="" type="" align="left" alt=""><![CDATA[
367zTLD := zkl[126:129].zkl[63:125].zkl[0:62] 394zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
368 ]]></artwork> 395 ]]></artwork>
396 </section>
397 <section anchor="revocation" numbered="true" toc="default">
398 <name>Zone Revocation</name>
399 <t>
400 Whenever a recursive resolver encounters a new GNS zone, it MUST
401 check against the local revocation list whether the respective
402 zone key has been revoked. If the zone key was revoked, the
403 resolution MUST fail with an empty result set.
404 </t>
405 <t>
406 In order to revoke a zone key, a signed revocation object MUST be
407 published.
408 This object MUST be signed using the private zone key.
409 The revocation object is broadcast to the network.
410 The specification of the broadcast mechanism is out of scope of this
411 document.
412 A possible broadcast mechanism for efficient flooding in a distributed
413 network is implemented in <xref target="GNUnet"/>.
414 Alternatively, revocation objects could also be distributed via a
415 distributed ledger or a trusted central server.
416 To prevent
417 flooding attacks, the revocation message MUST contain a proof of work
418 (PoW).
419 The revocation message including the PoW MAY be calculated
420 ahead of time to support timely revocation.
421 </t>
422 <t>
423 For all occurences below, "Argon2id" is the Password-based Key
424 Derivation Function as defined in <xref target="RFC9106" />. For the
425 PoW calculations the algorithm is instantiated with the
426 following parameters:
427 </t>
428 <dl>
429 <dt>S</dt>
430 <dd>The salt. Fixed 16-byte string: "GnsRevocationPow".</dd>
431 <dt>t</dt>
432 <dd>Number of iterations: 3</dd>
433 <dt>m</dt>
434 <dd>Memory size in KiB: 1024</dd>
435 <dt>T</dt>
436 <dd>Output length of hash in bytes: 64</dd>
437 <dt>p</dt>
438 <dd>Parallelization parameter: 1</dd>
439 <dt>v</dt>
440 <dd>Algorithm version: 0x13</dd>
441 <dt>y</dt>
442 <dd>Algorithm type (Argon2id): 2</dd>
443 <dt>X</dt><dd>Unused</dd>
444 <dt>K</dt><dd>Unused</dd>
445 </dl>
446 <t>
447 <xref target="figure_revocation"/> illustrates the wire format
448 of the message string "P" on which the PoW is calculated.
449 </t>
450 <figure anchor="figure_revocation">
451 <artwork name="" type="" align="left" alt=""><![CDATA[
4520 8 16 24 32 40 48 56
453+-----+-----+-----+-----+-----+-----+-----+-----+
454| POW |
455+-----------------------------------------------+
456| TIMESTAMP |
457+-----------------------------------------------+
458| ZONE TYPE | PUBLIC ZONE KEY |
459+-----+-----+-----+-----+ |
460/ /
461/ /
462+-----+-----+-----+-----+-----+-----+-----+-----+
463 ]]></artwork>
464 </figure>
465 <t>The Wire Format of the PoW Message String.</t>
466 <dl>
467 <dt>POW</dt>
468 <dd>
469 A 64-bit solution to the PoW. In network byte order.
470 </dd>
471 <dt>TIMESTAMP</dt>
472 <dd>
473 denotes the absolute 64-bit date when the revocation was computed.
474 In microseconds since midnight (0 hour), January 1, 1970 in network
475 byte order.
476 </dd>
477 <dt>PUBLIC KEY</dt>
478 <dd>
479 is the 256-bit public key zk of the zone which is being revoked and
480 the key to be used to verify SIGNATURE. The
481 wire format of this value is defined in <xref target="RFC8032" />,
482 Section 5.1.5.
483 </dd>
484 </dl>
485 <t>
486 Traditionally, PoW schemes require to find a POW such that
487 at least D leading zeroes are found in the hash result.
488 D is then referred to as the difficulty of the PoW.
489 In order to reduce the variance in time it takes to calculate the
490 PoW, we require that a number Z different PoWs must be
491 found that on average have D leading zeroes.
492 </t>
493 <t>
494 The resulting proofs may then published and disseminated. The concrete
495 dissemination and publication methods are out of scope of this
496 document. Given an average difficulty of D, the proofs have an
497 expiration time of EPOCH. With each additional bit difficulty, the
498 lifetime of the proof is prolonged for another EPOCH.
499 Consequently, by calculating a more difficult PoW, the lifetime of the
500 proof can be increased on demand by the zone owner.
501 </t>
502 <t>
503 The parameters are defined as follows:
504 </t>
505 <dl>
506 <dt>Z</dt>
507 <dd>The number of PoWs required is fixed at 32.</dd>
508 <dt>D</dt>
509 <dd>The difficulty is fixed at 22.</dd>
510 <dt>EPOCH</dt>
511 <dd>A single epoch is fixed at 365 days.</dd>
512 </dl>
513 <t>
514 The revocation message wire format is illustrated in
515 <xref target="figure_revocationdata"/>.
516 </t>
517 <figure anchor="figure_revocationdata">
518 <artwork name="" type="" align="left" alt=""><![CDATA[
5190 8 16 24 32 40 48 56
520+-----+-----+-----+-----+-----+-----+-----+-----+
521| TIMESTAMP |
522+-----+-----+-----+-----+-----+-----+-----+-----+
523| TTL |
524+-----+-----+-----+-----+-----+-----+-----+-----+
525| POW_0 |
526+-----+-----+-----+-----+-----+-----+-----+-----+
527| ... |
528+-----+-----+-----+-----+-----+-----+-----+-----+
529| POW_Z-1 |
530+-----------------------------------------------+
531| ZONE TYPE | PUBLIC ZONE KEY |
532+-----+-----+-----+-----+ |
533/ /
534/ /
535+-----+-----+-----+-----+-----+-----+-----+-----+
536| SIGNATURE |
537/ /
538/ /
539| |
540+-----+-----+-----+-----+-----+-----+-----+-----+
541 ]]></artwork>
542 </figure>
543 <t>The Revocation Message Wire Format.</t>
544 <dl>
545 <dt>TIMESTAMP</dt>
546 <dd>
547 denotes the absolute 64-bit date when the revocation was computed.
548 In microseconds since midnight (0 hour), January 1, 1970 in network
549 byte order. This is the same value as the timestamp used in the
550 individual PoW calculations.
551 </dd>
552 <dt>TTL</dt>
553 <dd>
554 denotes the relative 64-bit time to live of of the record in
555 microseconds also in network byte order. This field is informational
556 for a verifier. The verifier may discard revocation if the TTL
557 indicates that it is already expired. However, the actual TTL of the
558 revocation must be determined by examining the leading zeros in the
559 proof of work calculation.
560 </dd>
561 <dt>POW_i</dt>
562 <dd>
563 The values calculated as part of the PoW, in network byte order.
564 Each POW_i MUST be unique in the set of POW values.
565 To facilitate fast verification
566 of uniqueness, the POW values must be given in strictly
567 monotonically increasing order in the message.
568 </dd>
569 <dt>ZONE TYPE</dt>
570 <dd>
571 The 32-bit zone type corresponding to the zone public key.
572 </dd>
573 <dt>ZONE PUBLIC KEY</dt>
574 <dd>
575 is the public key zk of the zone which is being revoked and
576 the key to be used to verify SIGNATURE.
577 </dd>
578 <dt>SIGNATURE</dt>
579 <dd>
580 A signature over a timestamp and the public zone zk of the zone
581 which is revoked and corresponds to the key used in the PoW.
582 The signature is created using the Sign() function of
583 the cryptosystem of the zone and the private zone key
584 (see <xref target="ztype" />).
585 </dd>
586 </dl>
587 <t>
588 The signature over the public key covers a 32-bit pseudo header
589 conceptually prefixed to the public key. The pseudo header includes
590 the key length and signature purpose. The wire format is illustrated
591 in <xref target="figure_revsigwithpseudo"/>.
592 </t>
593 <figure anchor="figure_revsigwithpseudo">
594 <artwork name="" type="" align="left" alt=""><![CDATA[
5950 8 16 24 32 40 48 56
596+-----+-----+-----+-----+-----+-----+-----+-----+
597| SIZE (0x30) | PURPOSE (0x03) |
598+-----+-----+-----+-----+-----+-----+-----+-----+
599| TIMESTAMP |
600+-----+-----+-----+-----+-----+-----+-----+-----+
601| ZONE TYPE | ZONE PUBLIC KEY |
602+-----+-----+-----+-----+ |
603/ /
604/ /
605+-----+-----+-----+-----+-----+-----+-----+-----+
606 ]]></artwork>
607 </figure>
608 <t>The Wire Format of the Revocation Data for Signing.</t>
609 <dl>
610 <dt>SIZE</dt>
611 <dd>
612 A 32-bit value containing the length of the signed data in bytes
613 in network byte order.
614 </dd>
615 <dt>PURPOSE</dt>
616 <dd>
617 A 32-bit signature purpose flag. This field MUST be 3 (in network
618 byte order).
619 </dd>
620 <dt>ZONE TYPE</dt>
621 <dd>
622 The 32-bit zone type corresponding to the zone public key.
623 </dd>
624 <dt>ZONE PUBLIC KEY / TIMESTAMP</dt>
625 <dd>Both values as defined in the revocation data object above.</dd>
626 </dl>
627 <t>
628 In order to verify a revocation the following steps must be taken,
629 in order:
630 </t>
631 <ol>
632 <li>The current time MUST be between TIMESTAMP and
633 TIMESTAMP+TTL.</li>
634 <li>The signature MUST match the public key.</li>
635 <li>The set of POW values MUST NOT contain duplicates.</li>
636 <li>The average number of leading zeroes resulting from the provided
637 POW values D' MUST be greater than D.</li>
638 <li>The validation period (TTL) of the revocation is calculated as
639 (D'-D) * EPOCH * 1.1. The EPOCH is extended by
640 10% in order to deal with unsynchronized clocks.
641 The TTL added on top of the TIMESTAMP yields the
642 expiration date.</li>
643 </ol>
369 </section> 644 </section>
645
646
370 </section> 647 </section>
371 <section anchor="rrecords" numbered="true" toc="default"> 648 <section anchor="rrecords" numbered="true" toc="default">
372 <name>Resource Records</name> 649 <name>Resource Records</name>
@@ -438,8 +715,10 @@ zTLD := zkl[126:129].zkl[63:125].zkl[0:62]
438 <t> 715 <t>
439 Flags indicate metadata surrounding the resource record. A flag 716 Flags indicate metadata surrounding the resource record. A flag
440 value of 0 indicates that all flags are unset. 717 value of 0 indicates that all flags are unset.
441 Any GNS implementation MUST process all flags which are set in the 718 Applications creating resource records MUST set all bits which are
442 FLAGS field. If an implementation encounters a flag which it does not 719 not defined as a flag to 0. As additional flags may be defined in
720 future protocol versions, applications MUST ignore unknown flags.
721 If an implementation encounters a flag which it does not
443 recognize, the resource record is not valid and MUST be discarded. 722 recognize, the resource record is not valid and MUST be discarded.
444 <xref target="figure_flag"/> 723 <xref target="figure_flag"/>
445 illustrates the flag distribution in the 32-bit flag value of a 724 illustrates the flag distribution in the 32-bit flag value of a
@@ -1326,256 +1605,7 @@ q := SHA512 (HDKD-Public(zk, label))
1326 </dl> 1605 </dl>
1327 </section> 1606 </section>
1328 </section> 1607 </section>
1329 <section anchor="revocation" numbered="true" toc="default"> 1608 <section anchor="resolution" numbered="true" toc="default">
1330 <name>Zone Revocation</name>
1331 <t>
1332 Whenever a recursive resolver encounters a new GNS zone, it MUST
1333 check against the local revocation list whether the respective
1334 zone key has been revoked. If the zone key was revoked, the
1335 resolution MUST fail with an empty result set.
1336 </t>
1337 <t>
1338 In order to revoke a zone key, a signed revocation object MUST be
1339 published.
1340 This object MUST be signed using the private zone key.
1341 The revocation object is broadcast to the network.
1342 The specification of the broadcast mechanism is out of scope of this
1343 document.
1344 A possible broadcast mechanism for efficient flooding in a distributed
1345 network is implemented in <xref target="GNUnet"/>.
1346 Alternatively, revocation objects could also be distributed via a
1347 distributed ledger or a trusted central server.
1348 To prevent
1349 flooding attacks, the revocation message MUST contain a proof of work
1350 (PoW).
1351 The revocation message including the PoW MAY be calculated
1352 ahead of time to support timely revocation.
1353 </t>
1354 <t>
1355 For all occurences below, "Argon2id" is the Password-based Key
1356 Derivation Function as defined in <xref target="RFC9106" />. For the
1357 PoW calculations the algorithm is instantiated with the
1358 following parameters:
1359 </t>
1360 <dl>
1361 <dt>S</dt>
1362 <dd>The salt. Fixed 16-byte string: "GnsRevocationPow".</dd>
1363 <dt>t</dt>
1364 <dd>Number of iterations: 3</dd>
1365 <dt>m</dt>
1366 <dd>Memory size in KiB: 1024</dd>
1367 <dt>T</dt>
1368 <dd>Output length of hash in bytes: 64</dd>
1369 <dt>p</dt>
1370 <dd>Parallelization parameter: 1</dd>
1371 <dt>v</dt>
1372 <dd>Algorithm version: 0x13</dd>
1373 <dt>y</dt>
1374 <dd>Algorithm type (Argon2id): 2</dd>
1375 <dt>X</dt><dd>Unused</dd>
1376 <dt>K</dt><dd>Unused</dd>
1377 </dl>
1378 <t>
1379 <xref target="figure_revocation"/> illustrates the wire format
1380 of the message string "P" on which the PoW is calculated.
1381 </t>
1382 <figure anchor="figure_revocation">
1383 <artwork name="" type="" align="left" alt=""><![CDATA[
13840 8 16 24 32 40 48 56
1385+-----+-----+-----+-----+-----+-----+-----+-----+
1386| POW |
1387+-----------------------------------------------+
1388| TIMESTAMP |
1389+-----------------------------------------------+
1390| ZONE TYPE | PUBLIC ZONE KEY |
1391+-----+-----+-----+-----+ |
1392/ /
1393/ /
1394+-----+-----+-----+-----+-----+-----+-----+-----+
1395 ]]></artwork>
1396 </figure>
1397 <t>The Wire Format of the PoW Message String.</t>
1398 <dl>
1399 <dt>POW</dt>
1400 <dd>
1401 A 64-bit solution to the PoW. In network byte order.
1402 </dd>
1403 <dt>TIMESTAMP</dt>
1404 <dd>
1405 denotes the absolute 64-bit date when the revocation was computed.
1406 In microseconds since midnight (0 hour), January 1, 1970 in network
1407 byte order.
1408 </dd>
1409 <dt>PUBLIC KEY</dt>
1410 <dd>
1411 is the 256-bit public key zk of the zone which is being revoked and
1412 the key to be used to verify SIGNATURE. The
1413 wire format of this value is defined in <xref target="RFC8032" />,
1414 Section 5.1.5.
1415 </dd>
1416 </dl>
1417 <t>
1418 Traditionally, PoW schemes require to find a POW such that
1419 at least D leading zeroes are found in the hash result.
1420 D is then referred to as the difficulty of the PoW.
1421 In order to reduce the variance in time it takes to calculate the
1422 PoW, we require that a number Z different PoWs must be
1423 found that on average have D leading zeroes.
1424 </t>
1425 <t>
1426 The resulting proofs may then published and disseminated. The concrete
1427 dissemination and publication methods are out of scope of this
1428 document. Given an average difficulty of D, the proofs have an
1429 expiration time of EPOCH. With each additional bit difficulty, the
1430 lifetime of the proof is prolonged for another EPOCH.
1431 Consequently, by calculating a more difficult PoW, the lifetime of the
1432 proof can be increased on demand by the zone owner.
1433 </t>
1434 <t>
1435 The parameters are defined as follows:
1436 </t>
1437 <dl>
1438 <dt>Z</dt>
1439 <dd>The number of PoWs required is fixed at 32.</dd>
1440 <dt>D</dt>
1441 <dd>The difficulty is fixed at 22.</dd>
1442 <dt>EPOCH</dt>
1443 <dd>A single epoch is fixed at 365 days.</dd>
1444 </dl>
1445 <t>
1446 The revocation message wire format is illustrated in
1447 <xref target="figure_revocationdata"/>.
1448 </t>
1449 <figure anchor="figure_revocationdata">
1450 <artwork name="" type="" align="left" alt=""><![CDATA[
14510 8 16 24 32 40 48 56
1452+-----+-----+-----+-----+-----+-----+-----+-----+
1453| TIMESTAMP |
1454+-----+-----+-----+-----+-----+-----+-----+-----+
1455| TTL |
1456+-----+-----+-----+-----+-----+-----+-----+-----+
1457| POW_0 |
1458+-----+-----+-----+-----+-----+-----+-----+-----+
1459| ... |
1460+-----+-----+-----+-----+-----+-----+-----+-----+
1461| POW_Z-1 |
1462+-----------------------------------------------+
1463| ZONE TYPE | PUBLIC ZONE KEY |
1464+-----+-----+-----+-----+ |
1465/ /
1466/ /
1467+-----+-----+-----+-----+-----+-----+-----+-----+
1468| SIGNATURE |
1469/ /
1470/ /
1471| |
1472+-----+-----+-----+-----+-----+-----+-----+-----+
1473 ]]></artwork>
1474 </figure>
1475 <t>The Revocation Message Wire Format.</t>
1476 <dl>
1477 <dt>TIMESTAMP</dt>
1478 <dd>
1479 denotes the absolute 64-bit date when the revocation was computed.
1480 In microseconds since midnight (0 hour), January 1, 1970 in network
1481 byte order. This is the same value as the timestamp used in the
1482 individual PoW calculations.
1483 </dd>
1484 <dt>TTL</dt>
1485 <dd>
1486 denotes the relative 64-bit time to live of of the record in
1487 microseconds also in network byte order. This field is informational
1488 for a verifier. The verifier may discard revocation if the TTL
1489 indicates that it is already expired. However, the actual TTL of the
1490 revocation must be determined by examining the leading zeros in the
1491 proof of work calculation.
1492 </dd>
1493 <dt>POW_i</dt>
1494 <dd>
1495 The values calculated as part of the PoW, in network byte order.
1496 Each POW_i MUST be unique in the set of POW values.
1497 To facilitate fast verification
1498 of uniqueness, the POW values must be given in strictly
1499 monotonically increasing order in the message.
1500 </dd>
1501 <dt>ZONE TYPE</dt>
1502 <dd>
1503 The 32-bit zone type corresponding to the zone public key.
1504 </dd>
1505 <dt>ZONE PUBLIC KEY</dt>
1506 <dd>
1507 is the public key zk of the zone which is being revoked and
1508 the key to be used to verify SIGNATURE.
1509 </dd>
1510 <dt>SIGNATURE</dt>
1511 <dd>
1512 A signature over a timestamp and the public zone zk of the zone
1513 which is revoked and corresponds to the key used in the PoW.
1514 The signature is created using the Sign() function of
1515 the cryptosystem of the zone and the private zone key
1516 (see <xref target="ztype" />).
1517 </dd>
1518 </dl>
1519 <t>
1520 The signature over the public key covers a 32-bit pseudo header
1521 conceptually prefixed to the public key. The pseudo header includes
1522 the key length and signature purpose. The wire format is illustrated
1523 in <xref target="figure_revsigwithpseudo"/>.
1524 </t>
1525 <figure anchor="figure_revsigwithpseudo">
1526 <artwork name="" type="" align="left" alt=""><![CDATA[
15270 8 16 24 32 40 48 56
1528+-----+-----+-----+-----+-----+-----+-----+-----+
1529| SIZE (0x30) | PURPOSE (0x03) |
1530+-----+-----+-----+-----+-----+-----+-----+-----+
1531| TIMESTAMP |
1532+-----+-----+-----+-----+-----+-----+-----+-----+
1533| ZONE TYPE | ZONE PUBLIC KEY |
1534+-----+-----+-----+-----+ |
1535/ /
1536/ /
1537+-----+-----+-----+-----+-----+-----+-----+-----+
1538 ]]></artwork>
1539 </figure>
1540 <t>The Wire Format of the Revocation Data for Signing.</t>
1541 <dl>
1542 <dt>SIZE</dt>
1543 <dd>
1544 A 32-bit value containing the length of the signed data in bytes
1545 in network byte order.
1546 </dd>
1547 <dt>PURPOSE</dt>
1548 <dd>
1549 A 32-bit signature purpose flag. This field MUST be 3 (in network
1550 byte order).
1551 </dd>
1552 <dt>ZONE TYPE</dt>
1553 <dd>
1554 The 32-bit zone type corresponding to the zone public key.
1555 </dd>
1556 <dt>ZONE PUBLIC KEY / TIMESTAMP</dt>
1557 <dd>Both values as defined in the revocation data object above.</dd>
1558 </dl>
1559 <t>
1560 In order to verify a revocation the following steps must be taken,
1561 in order:
1562 </t>
1563 <ol>
1564 <li>The current time MUST be between TIMESTAMP and
1565 TIMESTAMP+TTL.</li>
1566 <li>The signature MUST match the public key.</li>
1567 <li>The set of POW values MUST NOT contain duplicates.</li>
1568 <li>The average number of leading zeroes resulting from the provided
1569 POW values D' MUST be greater than D.</li>
1570 <li>The validation period (TTL) of the revocation is calculated as
1571 (D'-D) * EPOCH * 1.1. The EPOCH is extended by
1572 10% in order to deal with unsynchronized clocks.
1573 The TTL added on top of the TIMESTAMP yields the
1574 expiration date.</li>
1575 </ol>
1576 </section>
1577
1578 <section anchor="resolution" numbered="true" toc="default">
1579 <name>Name Resolution</name> 1609 <name>Name Resolution</name>
1580 <t> 1610 <t>
1581 Names in GNS are resolved by recursively querying the record storage. 1611 Names in GNS are resolved by recursively querying the record storage.