diff options
Diffstat (limited to 'draft-schanzen-r5n.xml')
-rw-r--r-- | draft-schanzen-r5n.xml | 245 |
1 files changed, 114 insertions, 131 deletions
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml index f4a8099..dcc05d7 100644 --- a/draft-schanzen-r5n.xml +++ b/draft-schanzen-r5n.xml | |||
@@ -202,6 +202,18 @@ | |||
202 | The peer that initially creates and sends a GetMessage (<xref target="p2p_get"/>) or | 202 | The peer that initially creates and sends a GetMessage (<xref target="p2p_get"/>) or |
203 | PutMessage message (<xref target="p2p_put"/>). | 203 | PutMessage message (<xref target="p2p_put"/>). |
204 | </dd> | 204 | </dd> |
205 | <dt>HELLO block</dt> | ||
206 | <dd> | ||
207 | A HELLO block is a block with a dedicated block type and is specified in this document. | ||
208 | The HELLO block is used to store and retrieve Peer addresses. | ||
209 | In this document, HELLO blocks are used by the peer discovery mechanism. | ||
210 | </dd> | ||
211 | <dt>HELLO URL</dt> | ||
212 | <dd> | ||
213 | HELLO URLs are URL-formatted HELLO blocks. | ||
214 | They can used for out-of-band exchanges of peer information and are used for | ||
215 | address update signalling messages to neighbours. | ||
216 | </dd> | ||
205 | <dt>Key</dt> | 217 | <dt>Key</dt> |
206 | <dd> | 218 | <dd> |
207 | 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be | 219 | 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be |
@@ -320,8 +332,8 @@ | |||
320 | <t> | 332 | <t> |
321 | In order to establish an initial connection to a network of R<sup>5</sup>N | 333 | In order to establish an initial connection to a network of R<sup>5</sup>N |
322 | peers, an initial, addressable bootstrap peer is required. | 334 | peers, an initial, addressable bootstrap peer is required. |
323 | Further peers, including neighbors, are then learned via a bootstrapping | 335 | Further peers, including neighbors, are then learned via a peer discovery |
324 | process as defined in <xref target="bootstrapping"/>. | 336 | process as defined in <xref target="find_peer"/>. |
325 | </t> | 337 | </t> |
326 | <t> | 338 | <t> |
327 | Across this document, the functional components of an R<sup>5</sup>N | 339 | Across this document, the functional components of an R<sup>5</sup>N |
@@ -519,133 +531,6 @@ Connectivity | |Underlay| |Underlay| | |||
519 | and message transmission. | 531 | and message transmission. |
520 | </t> | 532 | </t> |
521 | </section> | 533 | </section> |
522 | <section anchor="bootstrapping"> | ||
523 | <name>Bootstrapping</name> | ||
524 | <t> | ||
525 | Initially, the implementation depends upon either the Underlay providing at | ||
526 | least one initial connection to a peer (signalled through | ||
527 | <tt>PEER_CONNECTED</tt>), or the application/end-user providing at | ||
528 | least one working HELLO to the DHT for bootstrapping. | ||
529 | While details on how the first connection is established <bcp14>MAY</bcp14> | ||
530 | depend on the specific implementation, this <bcp14>SHOULD</bcp14> usually be done | ||
531 | by an out-of-band exchange of the information from a HELLO block. | ||
532 | <!-- FIXME: Is this really an encoding of a block? It seems to me that "HELLO" | ||
533 | is not properly defined. --> | ||
534 | For this, section <xref target="hello_url"/> specifies a URL format for encoding HELLO | ||
535 | blocks as text strings which <bcp14>SHOULD</bcp14> be supported by implementations. | ||
536 | </t> | ||
537 | <t> | ||
538 | Regardless of how the initial connections are established, the | ||
539 | peers resulting from these initial connections | ||
540 | are subsequently stored in the routing table component | ||
541 | <xref target="routing_table"/>. | ||
542 | </t> | ||
543 | <t> | ||
544 | Furthermore, the Underlay <bcp14>SHOULD</bcp14> provide the implementation with one or more | ||
545 | addresses signalled through <tt>ADDRESS_ADDED</tt>. Zero addresses <bcp14>MAY</bcp14> be | ||
546 | provided if a peer can only establish outgoing connections and is otherwise unreachable. | ||
547 | <!-- FIXME: What about HelloMessages? What is the distinction between HELLO blocks | ||
548 | and HELLO messages? --> | ||
549 | The implementation periodically advertises all | ||
550 | active addresses in a HELLO block <xref target="hello_block"/>. | ||
551 | </t> | ||
552 | <t> | ||
553 | <!-- FIXME: Maybe make this a SHOULD and explain what happens if the implementation | ||
554 | does not. We should allow a minimal implementation of the protocol. --> | ||
555 | In order to fill its routing table by finding close peers in the network, an | ||
556 | implementation <bcp14>MUST</bcp14> now periodically send peer discovery messages | ||
557 | <xref target="find_peer"/>. | ||
558 | </t> | ||
559 | <t> | ||
560 | The frequency of advertisement and peer discovery messages | ||
561 | <bcp14>MAY</bcp14> be adapted according to network conditions, | ||
562 | the set of already connected neighbors, | ||
563 | the workload of the system and other factors which are at the discretion of | ||
564 | the developer. | ||
565 | </t> | ||
566 | <t> | ||
567 | <!-- FIXME: This whole section is a bit odd and I think we should breat it up | ||
568 | into an overview and the below explanaton should be part of message | ||
569 | processing --> | ||
570 | Any implementation encountering a HELLO GET request <bcp14>MUST</bcp14> respond | ||
571 | with its own HELLO block except if that block is | ||
572 | filtered by the request's result filter (see <xref target="result_filter"/>). | ||
573 | Implementations <bcp14>MAY</bcp14> respond | ||
574 | with additional valid HELLO blocks of other peers with keys | ||
575 | closest to the key of the GET request. A HELLO block is "valid" | ||
576 | if it is non-expired and | ||
577 | is not excluded by the result filter. "closest" is defined | ||
578 | by considering the distances between the request's key and the | ||
579 | peer addresses of all of the valid HELLO blocks known at the local node. | ||
580 | </t> | ||
581 | <section anchor="hello_url"> | ||
582 | <name>HELLO URLs</name> | ||
583 | <t> | ||
584 | The general format of a HELLO URL uses "gnunet://" | ||
585 | as the scheme, followed by "hello/" for the name | ||
586 | of the GNUnet subsystem, followed by "/"-separated values | ||
587 | with the GNS Base32 encoding (<xref target="I-D.schanzen-gns"/>) of | ||
588 | the <tt>Peer ID</tt>, a Base32-encoded EdDSA signature, and an expiration | ||
589 | time in seconds since the UNIX Epoch in decimal format. | ||
590 | After this a "?" begins a list of key-value pairs where the key | ||
591 | is the URI scheme of one of the peer's addresses and the value | ||
592 | is the URL-escaped payload of the address URI without the "://". | ||
593 | </t> | ||
594 | <t> | ||
595 | For example, consider the following URL: | ||
596 | </t> | ||
597 | <figure> | ||
598 | <artwork type="abnf"><![CDATA[ | ||
599 | gnunet://hello/RH1M20EPK834M6MHZ72\ | ||
600 | G3CMBSF3ECKNY4W0T9VAQP9Z7SZEM6Y3G/\ | ||
601 | NGRTAH6RA04X467CGCH7M7CEXR5F9CV5HT\ | ||
602 | ZFK0G9BWETY3CCE2QWGVT4WA7JN5M9HMWG\ | ||
603 | 60A00R71F1PJP8N5628EKGHHBAGA7M8JW3\ | ||
604 | 0/1647134480?udp=127.0.0.1%3A2086 | ||
605 | |||
606 | FIXME: signature is invalid, should | ||
607 | maybe generate proper test vector. | ||
608 | ]]> | ||
609 | </artwork> | ||
610 | </figure> | ||
611 | <t> | ||
612 | It specifies that the peer with the ID "RH1M...6Y3G" | ||
613 | is reachable via "udp" at 127.0.0.1 on port 2086 until | ||
614 | 1647134480 seconds after the Epoch. Note that "udp" | ||
615 | here is underspecified and just used as a simple example. | ||
616 | <!-- FIXME: Must be supported by which underlay? | ||
617 | This does not make sense. I may be able to generate | ||
618 | addr-names that my underlay supports, but there is not | ||
619 | way to guarantee that all underlays support it. --> | ||
620 | In practice, the key (addr-name) | ||
621 | <bcp14>MUST</bcp14> refer to a scheme supported by a | ||
622 | DHT Underlay. | ||
623 | </t> | ||
624 | <t> | ||
625 | The general syntax of HELLO URLs specified using | ||
626 | Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/> is: | ||
627 | </t> | ||
628 | <figure> | ||
629 | <artwork type="abnf"><![CDATA[ | ||
630 | hello-URL = "gnunet://hello/" meta [ "?" addrs ] | ||
631 | meta = pid "/" sig "/" exp | ||
632 | pid = *bchar | ||
633 | sig = *bchar | ||
634 | exp = *DIGIT | ||
635 | addrs = addr *( "&" addr ) | ||
636 | addr = addr-name "=" addr-value | ||
637 | addr-name = scheme | ||
638 | addr-value = *pchar | ||
639 | bchar = *(ALPHA / DIGIT) | ||
640 | ]]> | ||
641 | </artwork> | ||
642 | </figure> | ||
643 | <t> | ||
644 | 'scheme' is defined in <xref target="RFC3986" /> in Section 3.1. | ||
645 | 'pchar' is defined in <xref target="RFC3986" />, Appendix A. | ||
646 | </t> | ||
647 | </section> | ||
648 | </section> | ||
649 | <section anchor="routing" numbered="true" toc="default"> | 534 | <section anchor="routing" numbered="true" toc="default"> |
650 | <name>Routing</name> | 535 | <name>Routing</name> |
651 | <t> | 536 | <t> |
@@ -689,6 +574,20 @@ bchar = *(ALPHA / DIGIT) | |||
689 | upper limit on the number of neighbors kept per k-bucket. | 574 | upper limit on the number of neighbors kept per k-bucket. |
690 | </t> | 575 | </t> |
691 | <t> | 576 | <t> |
577 | Initially, the implementation depends upon either the Underlay providing at | ||
578 | least one initial connection to a peer (signalled through | ||
579 | <tt>PEER_CONNECTED</tt>), or the application/end-user providing at | ||
580 | least one working HELLO to the DHT for bootstrapping. | ||
581 | While details on how the first connection is established <bcp14>MAY</bcp14> | ||
582 | depend on the specific implementation, this <bcp14>SHOULD</bcp14> usually be done | ||
583 | by an out-of-band exchange of the information from a HELLO block. | ||
584 | <!-- FIXME: Is this really an encoding of a block? It seems to me that "HELLO" | ||
585 | is not properly defined. | ||
586 | FIXME: Should? Isn't this part of the HelloMessage? --> | ||
587 | For this, section <xref target="hello_url"/> specifies a URL format for encoding HELLO | ||
588 | blocks as text strings which <bcp14>SHOULD</bcp14> be supported by implementations. | ||
589 | </t> | ||
590 | <t> | ||
692 | Implementations <bcp14>SHOULD</bcp14> try to keep at least | 591 | Implementations <bcp14>SHOULD</bcp14> try to keep at least |
693 | 5 entries per k-bucket. Embedded systems that cannot manage | 592 | 5 entries per k-bucket. Embedded systems that cannot manage |
694 | this number of connections <bcp14>MAY</bcp14> use connection-level | 593 | this number of connections <bcp14>MAY</bcp14> use connection-level |
@@ -730,6 +629,22 @@ bchar = *(ALPHA / DIGIT) | |||
730 | Peer Discovery requests. Details about the format of the | 629 | Peer Discovery requests. Details about the format of the |
731 | HELLO message are given in <xref target="p2p_hello_wire"/>. | 630 | HELLO message are given in <xref target="p2p_hello_wire"/>. |
732 | </t> | 631 | </t> |
632 | <t> | ||
633 | The frequency of advertisement and peer discovery messages | ||
634 | <bcp14>MAY</bcp14> be adapted according to network conditions, | ||
635 | the set of already connected neighbors, | ||
636 | the workload of the system and other factors which are at the discretion of | ||
637 | the developer. | ||
638 | </t> | ||
639 | <t> | ||
640 | Furthermore, the Underlay <bcp14>SHOULD</bcp14> provide the implementation with one or more | ||
641 | addresses signalled through <tt>ADDRESS_ADDED</tt>. Zero addresses <bcp14>MAY</bcp14> be | ||
642 | provided if a peer can only establish outgoing connections and is otherwise unreachable. | ||
643 | <!-- FIXME: What about HelloMessages? What is the distinction between HELLO blocks | ||
644 | and HELLO messages? --> | ||
645 | The implementation periodically advertises all | ||
646 | active addresses in a HELLO block <xref target="hello_block"/>. | ||
647 | </t> | ||
733 | </section> | 648 | </section> |
734 | <section anchor="routing_bloomfilter"> | 649 | <section anchor="routing_bloomfilter"> |
735 | <name>Peer Bloom Filter</name> | 650 | <name>Peer Bloom Filter</name> |
@@ -1767,7 +1682,8 @@ BEGIN | |||
1767 | <li> | 1682 | <li> |
1768 | If <tt>BTYPE</tt> indicates a request for a HELLO block or | 1683 | If <tt>BTYPE</tt> indicates a request for a HELLO block or |
1769 | <tt>ANY</tt>, | 1684 | <tt>ANY</tt>, |
1770 | the peer <bcp14>MUST</bcp14> consult the HELLOs it has cached for the | 1685 | the peer <bcp14>MUST</bcp14> consult its own HELLO as well as |
1686 | the HELLOs it has cached for the | ||
1771 | peers in its routing table instead of the local block | 1687 | peers in its routing table instead of the local block |
1772 | storage (while continuing to respect flags like | 1688 | storage (while continuing to respect flags like |
1773 | <tt>DemultiplexEverywhere</tt> | 1689 | <tt>DemultiplexEverywhere</tt> |
@@ -3020,5 +2936,72 @@ Type | Name | References | Description | |||
3020 | </t> | 2936 | </t> |
3021 | </section> | 2937 | </section> |
3022 | </section> | 2938 | </section> |
3023 | </back> | 2939 | <section anchor="hello_url"> |
2940 | <name>HELLO URLs</name> | ||
2941 | <t> | ||
2942 | The general format of a HELLO URL uses "gnunet://" | ||
2943 | as the scheme, followed by "hello/" for the name | ||
2944 | of the GNUnet subsystem, followed by "/"-separated values | ||
2945 | with the GNS Base32 encoding (<xref target="I-D.schanzen-gns"/>) of | ||
2946 | the <tt>Peer ID</tt>, a Base32-encoded EdDSA signature, and an expiration | ||
2947 | time in seconds since the UNIX Epoch in decimal format. | ||
2948 | After this a "?" begins a list of key-value pairs where the key | ||
2949 | is the URI scheme of one of the peer's addresses and the value | ||
2950 | is the URL-escaped payload of the address URI without the "://". | ||
2951 | </t> | ||
2952 | <t> | ||
2953 | For example, consider the following URL: | ||
2954 | </t> | ||
2955 | <figure> | ||
2956 | <artwork type="abnf"><![CDATA[ | ||
2957 | gnunet://hello/RH1M20EPK834M6MHZ72\ | ||
2958 | G3CMBSF3ECKNY4W0T9VAQP9Z7SZEM6Y3G/\ | ||
2959 | NGRTAH6RA04X467CGCH7M7CEXR5F9CV5HT\ | ||
2960 | ZFK0G9BWETY3CCE2QWGVT4WA7JN5M9HMWG\ | ||
2961 | 60A00R71F1PJP8N5628EKGHHBAGA7M8JW3\ | ||
2962 | 0/1647134480?udp=127.0.0.1%3A2086 | ||
2963 | |||
2964 | FIXME: signature is invalid, should | ||
2965 | maybe generate proper test vector. | ||
2966 | ]]> | ||
2967 | </artwork> | ||
2968 | </figure> | ||
2969 | <t> | ||
2970 | It specifies that the peer with the ID "RH1M...6Y3G" | ||
2971 | is reachable via "udp" at 127.0.0.1 on port 2086 until | ||
2972 | 1647134480 seconds after the Epoch. Note that "udp" | ||
2973 | here is underspecified and just used as a simple example. | ||
2974 | <!-- FIXME: Must be supported by which underlay? | ||
2975 | This does not make sense. I may be able to generate | ||
2976 | addr-names that my underlay supports, but there is not | ||
2977 | way to guarantee that all underlays support it. --> | ||
2978 | In practice, the key (addr-name) | ||
2979 | <bcp14>MUST</bcp14> refer to a scheme supported by a | ||
2980 | DHT Underlay. | ||
2981 | </t> | ||
2982 | <t> | ||
2983 | The general syntax of HELLO URLs specified using | ||
2984 | Augmented Backus-Naur Form (ABNF) of <xref target="RFC5234"/> is: | ||
2985 | </t> | ||
2986 | <figure> | ||
2987 | <artwork type="abnf"><![CDATA[ | ||
2988 | hello-URL = "gnunet://hello/" meta [ "?" addrs ] | ||
2989 | meta = pid "/" sig "/" exp | ||
2990 | pid = *bchar | ||
2991 | sig = *bchar | ||
2992 | exp = *DIGIT | ||
2993 | addrs = addr *( "&" addr ) | ||
2994 | addr = addr-name "=" addr-value | ||
2995 | addr-name = scheme | ||
2996 | addr-value = *pchar | ||
2997 | bchar = *(ALPHA / DIGIT) | ||
2998 | ]]> | ||
2999 | </artwork> | ||
3000 | </figure> | ||
3001 | <t> | ||
3002 | 'scheme' is defined in <xref target="RFC3986" /> in Section 3.1. | ||
3003 | 'pchar' is defined in <xref target="RFC3986" />, Appendix A. | ||
3004 | </t> | ||
3005 | </section> | ||
3006 | </back> | ||
3024 | </rfc> | 3007 | </rfc> |