| 65 | | <li><a class="reference internal" href="#abstract" id="id2">Abstract</a></li> |
| 66 | | <li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li> |
| 67 | | <li><a class="reference internal" href="#operation" id="id4">Operation</a><ul> |
| 68 | | <li><a class="reference internal" href="#single-protocol-nodes" id="id5">Single-protocol nodes</a></li> |
| 69 | | <li><a class="reference internal" href="#double-stack-nodes" id="id6">Double-stack nodes</a><ul> |
| 70 | | <li><a class="reference internal" href="#bootstrapping" id="id7">Bootstrapping</a></li> |
| 71 | | <li><a class="reference internal" href="#stationary-operation" id="id8">Stationary operation</a></li> |
| 72 | | </ul> |
| 73 | | </li> |
| 74 | | </ul> |
| 75 | | </li> |
| 76 | | <li><a class="reference internal" href="#changes-and-extensions-to-existing-messages" id="id9">Changes and extensions to existing messages</a><ul> |
| 77 | | <li><a class="reference internal" href="#new-parameters" id="id10">New parameters</a><ul> |
| 78 | | <li><a class="reference internal" href="#nodes6" id="id11">nodes6</a></li> |
| 79 | | <li><a class="reference internal" href="#values6" id="id12">values6</a></li> |
| 80 | | <li><a class="reference internal" href="#want" id="id13">want</a></li> |
| 81 | | </ul> |
| 82 | | </li> |
| 83 | | <li><a class="reference internal" href="#changes-to-message-semantics" id="id14">Changes to message semantics</a><ul> |
| 84 | | <li><a class="reference internal" href="#find-nodes-and-get-peers" id="id15">find_nodes and get_peers</a></li> |
| 85 | | <li><a class="reference internal" href="#announce-peers" id="id16">announce_peers</a></li> |
| 86 | | </ul> |
| 87 | | </li> |
| 88 | | </ul> |
| 89 | | </li> |
| 90 | | <li><a class="reference internal" href="#acknowledgements" id="id17">Acknowledgements</a></li> |
| 91 | | <li><a class="reference internal" href="#references" id="id18">References</a></li> |
| 92 | | <li><a class="reference internal" href="#copyright" id="id19">Copyright</a></li> |
| | 65 | <li><a class="reference internal" href="#abstract" id="id3">Abstract</a></li> |
| | 66 | <li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li> |
| | 67 | <li><a class="reference internal" href="#operation" id="id5">Operation</a><ul> |
| | 68 | <li><a class="reference internal" href="#single-protocol-nodes" id="id6">Single-protocol nodes</a></li> |
| | 69 | <li><a class="reference internal" href="#double-stack-nodes" id="id7">Double-stack nodes</a><ul> |
| | 70 | <li><a class="reference internal" href="#bootstrapping" id="id8">Bootstrapping</a></li> |
| | 71 | <li><a class="reference internal" href="#steady-state-operation" id="id9">Steady-state operation</a></li> |
| | 72 | </ul> |
| | 73 | </li> |
| | 74 | </ul> |
| | 75 | </li> |
| | 76 | <li><a class="reference internal" href="#changes-and-extensions-to-existing-messages" id="id10">Changes and extensions to existing messages</a><ul> |
| | 77 | <li><a class="reference internal" href="#changes-to-existing-parameters" id="id11">Changes to existing parameters</a><ul> |
| | 78 | <li><a class="reference internal" href="#values" id="id12">values</a></li> |
| | 79 | </ul> |
| | 80 | </li> |
| | 81 | <li><a class="reference internal" href="#new-parameters" id="id13">New parameters</a><ul> |
| | 82 | <li><a class="reference internal" href="#nodes6" id="id14">nodes6</a></li> |
| | 83 | <li><a class="reference internal" href="#want" id="id15">want</a></li> |
| | 84 | </ul> |
| | 85 | </li> |
| | 86 | <li><a class="reference internal" href="#changes-to-message-semantics" id="id16">Changes to message semantics</a><ul> |
| | 87 | <li><a class="reference internal" href="#find-nodes-and-get-peers" id="id17">find_nodes and get_peers</a></li> |
| | 88 | <li><a class="reference internal" href="#announce-peers" id="id18">announce_peers</a></li> |
| | 89 | </ul> |
| | 90 | </li> |
| | 91 | </ul> |
| | 92 | </li> |
| | 93 | <li><a class="reference internal" href="#acknowledgements" id="id19">Acknowledgements</a></li> |
| | 94 | <li><a class="reference internal" href="#references" id="id20">References</a></li> |
| | 95 | <li><a class="reference internal" href="#copyright" id="id21">Copyright</a></li> |
| 115 | | <p>The extension described in this document also solves a long-standing issue |
| 116 | | with the protocol defined in BEP-5, and does so without endangering |
| 117 | | compatibility. When a get_peers request is sent with an explicit request |
| 118 | | for an address family, the presence of contact information in the reply is |
| 119 | | no longer governed by the presence of a "values" key; this avoids the |
| 120 | | well-known problem of contact information being masked by peer information.</p> |
| | 118 | <p>The extension described in this document also solves a long-standing |
| | 119 | issue with the protocol defined in BEP-5. The presence of contact |
| | 120 | information in the reply is no longer governed by the presence of |
| | 121 | a "values" key; this avoids the well-known problem of contact |
| | 122 | information being masked by peer information. While this is an |
| | 123 | incompatible change, it is believed to be properly handled by all |
| | 124 | deployed implementations.</p> |
| 156 | | <div class="section" id="stationary-operation"> |
| 157 | | <h3>Stationary operation</h3> |
| 158 | | <p>Once bootstrap is successful, a node should not request data in both |
| 159 | | address families; it should only request "nodes" replies from IPv4 nodes, |
| 160 | | and "nodes6" replies from IPv6 nodes. Requesting both address families is |
| 161 | | unlikely to provide any useful information, and unnecessarily increases |
| 162 | | network traffic.</p> |
| | 159 | <div class="section" id="steady-state-operation"> |
| | 160 | <h3>Steady-state operation</h3> |
| | 161 | <p>Once bootstrap is successful, a node should normally only request |
| | 162 | "nodes" replies from IPv4 nodes, and "nodes6" replies from IPv6 nodes. |
| | 163 | Requesting both address families in all requests is unlikely to |
| | 164 | provide useful information, and hence uselessly increases network |
| | 165 | traffic.</p> |
| | 174 | <div class="section" id="changes-to-existing-parameters"> |
| | 175 | <h2>Changes to existing parameters</h2> |
| | 176 | <div class="section" id="values"> |
| | 177 | <h3>values</h3> |
| | 178 | <p>In a reply sent over IPv4, the "values" parameter contains a list of |
| | 179 | strings, each of which contains compact format IPv4 contact |
| | 180 | information for a single peer.</p> |
| | 181 | <p>In a reply sent over IPv6, "values' contains a list of strings, each |
| | 182 | of which contains compact format IPv6 contact information for a single |
| | 183 | peer.</p> |
| | 184 | <p>Implementations of this specification must be able to properly parse |
| | 185 | hybrid "values" lists -- lists containing an arbitrary mixture of |
| | 186 | 6-octet IPv4 values and 18-octet IPv6 values. However, |
| | 187 | implementations should not send such hybrid lists, and must not send |
| | 188 | hybrid lists in a reply to an IPv4 request that doesn't contain |
| | 189 | a "want" parameter.</p> |
| | 190 | <blockquote> |
| | 191 | <strong>Rationale</strong>: a request sent over IPv4 with no "want" parameter |
| | 192 | could originate from a node that implements plain BEP-5, and which |
| | 193 | might therefore be unable to parse a hybrid list.</blockquote> |
| | 194 | </div> |
| | 195 | </div> |
| 206 | | <p>A node sending a find_nodes or get_peers request should include a "want" |
| 207 | | parameter containing one or both of the characters "4" or "6". A node |
| 208 | | replying to a find_nodes or get_peers request must include a "nodes" |
| 209 | | parameter if the request's "want" parameter included a "4", and a "nodes6" |
| 210 | | parameter if the request's "want" parameter included a "6".</p> |
| 211 | | <p>In the absence of a "want" parameter, the behaviour of the replying node is |
| 212 | | more involved. For a reply to a find_nodes request, the node should |
| 213 | | include "nodes" if the request was sent over IPv4, and include "nodes6" if |
| 214 | | the request was sent over IPv6.</p> |
| 215 | | <p>For a get_peers request with no "want" parameter, value should only be |
| 216 | | included if there is no "values" or "values6" parameter. If no "values" or |
| 217 | | "values6" parameter is being sent, the presence of "nodes" or "nodes6" is |
| 218 | | governed by the network-layer protocol of the request, as above.</p> |
| 219 | | <blockquote> |
| 220 | | <strong>Rationale</strong>: it has been suggested that the reply to a get_peers |
| 221 | | request should always include a "nodes" or "nodes6" parameter, |
| 222 | | independently of the presence of a "values" or "values6" parameter. |
| 223 | | While this is clearly a better semantics, it is not backward-compatible, |
| 224 | | and it is not known whether it breaks any deployed implementations.</blockquote> |
| 225 | | <p>When a node receives a get_peers request and it has contact information for |
| 226 | | the matching address family and info-hash, it should include either |
| 227 | | a "values" parameter (if the request was sent over IPv4) or a "values6" |
| 228 | | parameter in the reply.</p> |
| 229 | | <p>A reply sent over IPv4 must not contain a "values6" parameter, and a reply |
| 230 | | sent over IPv6 must not contain a "values" parameter. In other words, the |
| 231 | | "want" parameter only governs the presence of the "nodes" and "nodes6" |
| 232 | | parameters.</p> |
| | 231 | <p>A node sending a find_nodes or get_peers request should include |
| | 232 | a "want" parameter containing one or both of the characters "4" or |
| | 233 | "6". A node replying to a find_nodes or get_peers request should |
| | 234 | include a "nodes" parameter if and only if the request's "want" |
| | 235 | parameter included a "4", and should include a "nodes6" parameter if |
| | 236 | and only if the request's "want" parameter included a "6".</p> |
| | 237 | <p>In the absence of a "want" parameter, the reply should include "nodes" |
| | 238 | if the request was sent over IPv4, and should include "nodes6" if the |
| | 239 | request was sent over IPv6.</p> |
| | 240 | <blockquote> |
| | 241 | <strong>Rationale</strong>: this is an incompatible change to the protocol |
| | 242 | defined in BEP-5 <a class="footnote-reference" href="#bep-5" id="id2">[1]</a>, which specifies that "nodes" and |
| | 243 | "values" are mutually exclusive. However, this change makes the DHT |
| | 244 | more reliable, and has been deployed by most implementations for |
| | 245 | over a year with no negative effects.</blockquote> |
| | 246 | <p>When a node receives a get_peers request and it has contact |
| | 247 | information for the matching address family and info-hash, it should |
| | 248 | additionally include a "values" parameter containing a list of 6-octet |
| | 249 | strings if the request was sent over IPv4, and a list of 18-octet |
| | 250 | strings if the request was sent over IPv6.</p> |
| | 251 | <p>A reply sent over IPv4 should not contain 18-octet IPv6 contact |
| | 252 | information, and a reply sent over IPv6 should not contain 6-octet |
| | 253 | IPv4 contact information. In other words, the "want" parameter only |
| | 254 | governs the presence of the "nodes" and "nodes6" parameters, not the |
| | 255 | interpretation of "values".</p> |
| | 256 | <blockquote> |
| | 257 | <strong>Rationale</strong>: if the requesting node is a single-stack node, it has |
| | 258 | no interest in values of the other address family. If the |
| | 259 | requesting node is a double-stack node, then it must perform the two |
| | 260 | announces in parallel; providing both sets of data in both sets of |
| | 261 | replies merely increases the amount of traffic without giving any |
| | 262 | extra information.</blockquote> |
