[tor-commits] [torspec/master] Add proposal 314 (markdown) and 315 (required fields.)
nickm at torproject.org
nickm at torproject.org
Thu Apr 23 14:44:29 UTC 2020
commit 3ada0e7ed37c293b9cf13ade46558d31679e2a05
Author: Nick Mathewson <nickm at torproject.org>
Date: Thu Apr 23 10:43:48 2020 -0400
Add proposal 314 (markdown) and 315 (required fields.)
Also tweak reindex.py under the assumption that we will be accepting
proposal 314.
---
proposals/000-index.txt | 4 +
proposals/314-allow-markdown-proposals.md | 38 +++++++++
proposals/315-update-dir-required-fields.txt | 111 +++++++++++++++++++++++++++
proposals/reindex.py | 8 +-
4 files changed, 158 insertions(+), 3 deletions(-)
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index 7706b2a..de45e48 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -234,6 +234,8 @@ Proposals by number:
311 Tor Relay IPv6 Reachability [DRAFT]
312 Tor Relay Automatic IPv6 Address Discovery [DRAFT]
313 Tor Relay IPv6 Statistics [DRAFT]
+314 Allow Markdown for proposal format [OPEN]
+315 Updating the list of fields required in directory documents [OPEN]
Proposals by status:
@@ -274,6 +276,8 @@ Proposals by status:
299 Preferring IPv4 or IPv6 based on IP Version Failure Count
306 A Tor Implementation of IPv6 Happy Eyeballs
310 Towards load-balancing in Prop 271
+ 314 Allow Markdown for proposal format
+ 315 Updating the list of fields required in directory documents
ACCEPTED:
188 Bridge Guards and other anti-enumeration defenses
249 Allow CREATE cells with >505 bytes of handshake data
diff --git a/proposals/314-allow-markdown-proposals.md b/proposals/314-allow-markdown-proposals.md
new file mode 100644
index 0000000..2d2f653
--- /dev/null
+++ b/proposals/314-allow-markdown-proposals.md
@@ -0,0 +1,38 @@
+```
+Filename: 314-allow-markdown-proposals.md
+Title: Allow Markdown for proposal format.
+Author: Nick Mathewson
+Created: 23 April 2020
+Status: Open
+```
+
+# Introduction
+
+This document proposes a change in our proposal format: to allow
+Markdown.
+
+## Motivation
+
+Many people, particularly researchers, have found it difficult to
+write text in the format that we prefer. Moreover, we have often
+wanted to add more formatting in proposals, and found it nontrivial
+to do so.
+
+Markdown is an emerging "standard" (albeit not actually a
+standardized one), and we're using it in several other places. It
+seems like a natural fit for our purposes here.
+
+# Details
+
+We should pick a particular Markdown dialect. "CommonMark" seems like a
+good choice, since it's the basis of what github and gitlab use.
+
+We should also pick a particular tool to use for validating Markdown
+proposals.
+
+We should continue to allow text proposals.
+
+We should continue to require headers for our proposals, and do so
+using the format at the head of this document: wrapping the headers
+inside triple backticks.
+
diff --git a/proposals/315-update-dir-required-fields.txt b/proposals/315-update-dir-required-fields.txt
new file mode 100644
index 0000000..1ee2e54
--- /dev/null
+++ b/proposals/315-update-dir-required-fields.txt
@@ -0,0 +1,111 @@
+Filename: 315-update-dir-required-fields.txt
+Title: Updating the list of fields required in directory documents
+Author: Nick Mathewson
+Created: 23 April 2020
+Status: Open
+
+1. Introduction
+
+ When we add a new field to a directory document, we must at first
+ describe it as "optional", since older Tor implementations will
+ not generate it. When those implementations are obsolete and
+ unsupported, however, we can safely describe those fields as
+ "required", since they are always included in practice.
+
+ Making fields required is not just a matter of bookkeeping: it
+ helps prevent bugs in two ways. First, it simplifies our code.
+ Second, it makes our code's requirements match our assumptions
+ about the network.
+
+ Here I'll describe a general policy for making fields required
+ when LTS versions become unsupported, and include a list of
+ fields that should become required today.
+
+ This document does not require to us to make all optional fields
+ required -- only those which we intend that all Tor instances
+ should always generate and expect.
+
+ When we speak of making a field "required", we are talking about
+ describing it as "required" in dir-spec.txt, so that any document
+ missing that field is no longer considered well-formed.
+
+2. When fields should become required
+
+ We have three relevant kinds of directory documents: those
+ generated by relays, those generated by authorities, and those
+ generated by onion services.
+
+ Relays generate extrainfo documents and routerdesc documents.
+ For these, we can safely make a field required when it is always
+ generated by all relay versions that the authorities allow to
+ join the network. To avoid partitioning, authorities should
+ start requiring the field before any relays or clients do.
+
+ (If a relay field indicates the presence of a now-required
+ feature, then instead of making the field mandatory, we may
+ change the semantics so that the field is assumed to be
+ present. Later we can remove the option.)
+
+ Authorities generate authority certificates, votes, consensus
+ documents, and microdescriptors. For these, we can safely make a
+ field required once all authorities are generating it, and we are
+ confident that we do not plan to downgrade those authorities.
+
+ Onion services generate service descriptors. Because of the risk
+ of partitioning attacks, we should not make features in service
+ descriptors required without a phased process, described in the
+ following section.
+
+2.1. Phased addition of onion service descriptor changes
+
+ Phase one: we add client and service support for the new field,
+ but have this support disabled by default. By default, services
+ should not generate the new field, and clients should not parse
+ it when it is present. This behavior is controlled by a pair of
+ network parameters. (If the feature is at all complex, the
+ network parameters should describe a _minimum version_ that
+ should enable the feature, so that we can later enable it only in
+ the versions where the feature is not buggy.)
+
+ During this phase, we can manually override the defaults on
+ particular clients and services to test the new field.
+
+ Phase two: authorities use the network parameters to enable the
+ client support and the service support. They should only do this
+ once enough clients and services have upgraded to a version that
+ supports the feature.
+
+ Phase three: once all versions that support the feature are
+ obsolete and unsupported, the feature may be marked as required
+ in the specifications, and the network parameters ignored.
+
+ Phase four: once all versions that used the network parameters
+ are obsolete and unsupported, authorities may stop including
+ those parameters in their votes.
+
+3. Directory fields that should become required.
+
+ These fields in router descriptors should become required:
+ * identity-ed25519
+ * master-key-ed25519
+ * onion-key-crosscert
+ * ntor-onion-key
+ * ntor-onion-key-crosscert
+ * router-sig-ed25519
+ * proto
+
+ These fields in router descriptors should become "assumed present":
+ * hidden-service-dir
+
+ These fields in extra-info documents should become required:
+ * identity-ed25519
+ * router-sig-ed25519
+
+ The following fields in microdescriptors should become
+ required:
+ * ntor-onion-key
+
+ The following fields in votes and consensus documents should
+ become required:
+ * pr
+
diff --git a/proposals/reindex.py b/proposals/reindex.py
index 1f52466..361ea16 100755
--- a/proposals/reindex.py
+++ b/proposals/reindex.py
@@ -37,10 +37,12 @@ def readProposal(fn):
return fields
if line[0].isspace():
fields[lastField] += " %s"%(line.strip())
+ elif line == "```":
+ pass
else:
parts = line.split(":", 1)
if len(parts) != 2:
- raise Error("%s:%s: Neither field nor continuation"%
+ raise Error("%s:%s: Neither field, continuation, nor ```."%
(fn,lineno))
else:
fields[parts[0]] = parts[1].strip()
@@ -93,8 +95,8 @@ def readProposals():
for fn in os.listdir(DIR):
m = FNAME_RE.match(fn)
if not m: continue
- if not fn.endswith(".txt"):
- raise Error("%s doesn't end with .txt"%fn)
+ if not (fn.endswith(".txt") or fn.endswith(".md")):
+ raise Error("%s doesn't end with .txt or .md"%fn)
num = m.group(1)
fields = readProposal(fn)
checkProposal(fn, fields)
More information about the tor-commits
mailing list