commit 29de0da053d1ff3e92d0a7c2dfb3dd7c3407907d
parent 92b46818b0f5a6375781cfb74d551d8c121b0068
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sun, 27 Mar 2022 12:40:48 +0200
may cleanup; what is implementation cleanup
Diffstat:
1 file changed, 53 insertions(+), 49 deletions(-)
diff --git a/draft-schanzen-gns.xml b/draft-schanzen-gns.xml
@@ -193,13 +193,13 @@
</dd>
<dt>Resolver</dt>
<dd>
- The resolver is the part of the GNS implementation which implements
+ The resolver is the part of the GNS implementation which provides
the recursive name resolution logic defined in
<xref target="resolution"/>.
</dd>
<dt>Zone Master</dt>
<dd>
- The zone master is the part of the GNS implementation which implements
+ The zone master is the part of the GNS implementation which provides
local zone management and publication as defined in
<xref target="publish"/>.
</dd>
@@ -309,7 +309,7 @@
<dd>
In order to resolve any given GNS name an initial start zone must be
determined for this name.
- The start zone may already be explicitly defined through a zTLD.
+ The start zone can be explicitly defined through a zTLD.
Otherwise, it is determined through a local suffix-to-zone mapping
(see <xref target="governance"/>).
</dd>
@@ -326,7 +326,8 @@
<name>Overview</name>
<t>
In GNS, any user can create and manage one or more cryptographically
- secured zones (<xref target="zones"/>).
+ secured zones (<xref target="zones"/>) as part of a zone master
+ implementation.
Zones are uniquely identified by a zone key.
Zone contents are signed using blinded private keys and
encrypted using derived secret keys.
@@ -392,7 +393,7 @@
]]></artwork>
</figure>
<t>
- Applications use the GNS implementation to lookup GNS names.
+ Applications use the resolver to lookup GNS names.
Starting from a configurable start zone, names are resolved by following zone
delegations recursively as illustrated in <xref target="figure_arch_resolv"/>.
For each label in a name, the recursive GNS resolver
@@ -437,8 +438,8 @@
<t>
In the remainder of this document, the "implementer" refers to the developer building
- a GNS implementation including, for example, zone management tools and
- name resolution components.
+ a GNS implementation including the resolver, zone master, and
+ supporting configuration such as start zones (<xref target="governance"/>).
</t>
</section>
<section anchor="zones" numbered="true" toc="default">
@@ -525,7 +526,8 @@
<t>
The cryptographic functions of the default ztypes are specified with
their corresponding delegation records in <xref target="gnsrecords_delegation"/>.
- New ztypes may be specified in the future, for example if the
+ In order to support the specification of additional ztypes in the future,
+ for example if the
cryptographic mechanisms used in this document are broken.
</t>
<section anchor="zTLD" numbered="true" toc="default">
@@ -675,7 +677,8 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
must be found that on average have D leading zeroes.
</t>
<t>
- The resulting proofs may then published and disseminated. The concrete
+ The resulting proofs are ready for dissemination.
+ 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
@@ -739,8 +742,8 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
The field <bcp14>SHOULD</bcp14> be set to EPOCH * 1.1.
Given an average number of leading zeros D', then the field value
<bcp14>MAY</bcp14> be increased up to (D'-D) * EPOCH * 1.1.
- Lower or higher values may result in rejection of the revocation
- message when broadcast.
+ Validators <bcp14>MAY</bcp14> reject messages with lower or higher
+ values when received.
The EPOCH is extended by
10% in order to deal with unsynchronized clocks.
</dd>
@@ -847,8 +850,7 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
The validity period added on top of the TIMESTAMP yields the
expiration date.
If the current time is after the expiration date, the
- revocation is considered stale but may still be otherwise
- considered valid.
+ revocation is considered stale.
</t>
<t>
Verified revocations <bcp14>MUST</bcp14> be stored locally.
@@ -861,10 +863,10 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
Should the calculated validity period differ from the TTL field value,
the calculated value <bcp14>MUST</bcp14> be used as TTL field value
when forwarding the revocation message.
- Systems may disagree on the current time, so implementations
+ Systems might disagree on the current time, so implementations
<bcp14>MAY</bcp14> use stale but otherwise valid
revocations but <bcp14>SHOULD NOT</bcp14> broadcast them.
- Forwarded stale revocations may be discarded.
+ Forwarded stale revocations <bcp14>MAY</bcp14> be discarded.
</t>
<t>
Any locally stored revocation <bcp14>MUST</bcp14> be considered during
@@ -943,8 +945,8 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
Flags indicate metadata surrounding the resource record.
An application creating resource records <bcp14>MUST</bcp14> set all bits
to 0 unless it wants to set the respective flag.
- Additional flags may be defined in future protocol versions,
- If an application or implementation encounters a flag which it does not
+ As additional flags can be defined in future protocol versions,
+ if an application or implementation encounters a flag which it does not
recognize, it <bcp14>MUST</bcp14> be ignored.
Any combination of the flags specified below are valid.
<xref target="figure_flag"/>
@@ -973,7 +975,7 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
records of the same record type have expired. Used to allow zone publishers to
facilitate good performance when records change by allowing them to put future
values of records into the storage.
- This way, future values can propagate and may be
+ This way, future values can propagate and can be
cached before the transition becomes active.
</dd>
<dt>SUPPLEMENTAL</dt>
@@ -981,7 +983,7 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
This is a supplemental record. It is provided in addition to the
other records. This flag indicates that this record is not explicitly
managed alongside the other records under the respective name but
- may be useful for the application.
+ might be useful for the application.
</dd>
</dl>
<section anchor="gnsrecords_delegation" numbered="true" toc="default">
@@ -993,7 +995,7 @@ zTLD[126..129].zTLD[63..125].zTLD[0..62]
the GNU Name System Record Types registry (see <xref target="gana"/>).
Not supporting some zone types will result in resolution failures in case
the respective zone type is encountered.
- This may be a valid choice if some zone delegation record types have been
+ This is be a valid choice if some zone delegation record types have been
determined to be cryptographically insecure.
Zone delegation records <bcp14>MUST NOT</bcp14> be stored and published
under the apex label.
@@ -1278,7 +1280,7 @@ ZKDF(zk,label):
<t>
Implementers <bcp14>SHOULD</bcp14> employ a constant time scalar
multiplication for the constructions above to protect against
- timing attacks. Otherwise, timing attacks may leak private key
+ timing attacks. Otherwise, timing attacks could leak private key
material if an attacker can predict when a system starts the
publication process.
<!--Also, implementers
@@ -1428,13 +1430,13 @@ S-Decrypt(zk,label,expiration,ciphertext):
<section anchor="gnsrecords_redirect" numbered="true" toc="default">
<name>Redirection Records</name>
<t>
- Redirect records may be used to redirect resolution.
+ Redirect records are used to redirect resolution.
Any implementation <bcp14>SHOULD</bcp14> support all redirection record types defined here
and <bcp14>MAY</bcp14> support any number of additional redirection records defined in
the GNU Name System Record Types registry (see Section <xref target="gana"/>).
Redirection records <bcp14>MUST</bcp14> have the CRITICAL flag set.
- Not supporting some record types may consequently result in resolution failures.
- This may be a valid choice if some redirection record types have been
+ Not supporting some record types can result in resolution failures.
+ This can be a valid choice if some redirection record types have been
determined to be insecure, or if an application has reasons to not
support redirection to DNS for reasons such as complexity or security.
Redirection records <bcp14>MUST NOT</bcp14> be stored and published under the apex label.
@@ -1468,7 +1470,7 @@ S-Decrypt(zk,label,expiration,ciphertext):
<dt>REDIRECT NAME</dt>
<dd>
The name to continue with.
- The value of a redirect record may be a regular name, or a relative
+ The value of a redirect record can be a regular name, or a relative
name.
Relative GNS names are indicated by an extension label (U+002B, "+")
as rightmost label.
@@ -1515,9 +1517,9 @@ S-Decrypt(zk,label,expiration,ciphertext):
</dd>
<dt>DNS SERVER NAME</dt>
<dd>
- The DNS server to use. May be an IPv4 address in dotted-decimal
+ The DNS server to use. This value can be an IPv4 address in dotted-decimal
form or an IPv6 address in colon-hexadecimal form or a DNS name.
- It may also be a relative GNS name ending with a
+ It can also be a relative GNS name ending with a
"+" as the rightmost label.
The implementation <bcp14>MUST</bcp14> check the string syntactically for
an IP address in the respective notation before checking for a
@@ -1553,8 +1555,8 @@ S-Decrypt(zk,label,expiration,ciphertext):
is required to establish a connection to such a service.
The most common use case is HTTP virtual hosting, where a DNS name must
be supplied in the HTTP "Host"-header.
- Using a GNS name for the "Host"-header may not work as
- it may not be globally unique. Furthermore, even if uniqueness is
+ Using a GNS name for the "Host"-header might not work as
+ it might not be globally unique. Furthermore, even if uniqueness is
not an issue, the legacy service might not even be aware of GNS.
</t>
<t>
@@ -1782,7 +1784,7 @@ q := SHA-512 (ZKDF(zk, label))
encryption scheme.
A GNS implementation publishes RRBLOCKs
in accordance to the properties and recommendations of the underlying
- storage. This may include a periodic refresh operation to ensure the
+ storage. This can include a periodic refresh operation to ensure the
availability of the published RRBLOCKs.
The GNS RRBLOCK wire format is illustrated in
<xref target="figure_record_block"/>.
@@ -2076,9 +2078,10 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
<name>Recursion</name>
<t>
In each step of the recursive name resolution, there is an
- authoritative zone zk and a name to resolve. The name may be empty.
- Initially, the authoritative zone is the start zone. If the name
- is empty, it is interpreted as the apex label "@".
+ authoritative zone zk and a name to resolve.
+ The name <bcp14>MAY</bcp14> be empty.
+ If the name is empty, it is interpreted as the apex label "@".
+ Initially, the authoritative zone is the start zone.
</t>
<t>
From here, the following steps are recursively executed, in order:
@@ -2109,7 +2112,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
To filter records by validity, the resolver
<bcp14>MUST</bcp14> at least check the expiration time and the FLAGS field of the
respective record. In particular, SHADOW and
- SUPPLEMENTAL flags may exclude the record from being considered.
+ SUPPLEMENTAL flags can exclude the record from being considered.
If the resolver encounters a record with the CRITICAL flag set and
does not support the record type the resolution <bcp14>MUST</bcp14> be aborted
and an error <bcp14>MUST</bcp14> be returned. The information that the critical
@@ -2173,7 +2176,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
current zone.
Otherwise, the resulting name is resolved via the
default operating system name resolution process.
- This may in turn trigger a GNS name resolution process depending
+ This can in turn trigger a GNS name resolution process depending
on the system configuration.
In case resolution continues in DNS, the name <bcp14>MUST</bcp14> first be
converted to an IDNA compliant representation <xref target="RFC5890" />.
@@ -2202,7 +2205,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
GNS2DNS records <bcp14>MAY</bcp14>
contain numeric IPv4 or IPv6 addresses, allowing the resolver to
skip this step.
- The DNS server names may themselves be names in GNS or DNS.
+ The DNS server names might themselves be names in GNS or DNS.
If the rightmost label of the DNS server name is the extension label
(U+002B, "+"), the rest of the name is to be
interpreted relative to the zone of the GNS2DNS record.
@@ -2211,7 +2214,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
the GNS zone zk.
</t>
<t>
- Multiple GNS2DNS records may be stored under the same label,
+ Multiple GNS2DNS records can be stored under the same label,
in which case the resolver <bcp14>MUST</bcp14> try all of them.
The resolver <bcp14>MAY</bcp14> try them in any order or even in parallel.
If multiple GNS2DNS records are present, the DNS name <bcp14>MUST</bcp14> be
@@ -2231,7 +2234,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
the DNS name from the GNS2DNS record is appended
to the remainder of the name to be resolved, and
resolved by querying the DNS name server(s).
- The synthesized name may have to be converted to an IDNA compliant
+ The synthesized name has to be converted to an IDNA compliant
representation <xref target="RFC5890" /> for resolution in DNS.
If such a conversion is not possible, the resolution <bcp14>MUST</bcp14> be aborted
and an error <bcp14>MUST</bcp14> be returned. The information that the critical
@@ -2323,7 +2326,7 @@ example.com = zTLD2 := Base32GNS(ztype2||zk2)
<t>
NICK records are only relevant to the recursive resolver
if the record set in question is the final result which is to
- be returned to the application. The encountered NICK records may either
+ be returned to the application. The encountered NICK records can either
be supplemental (see <xref target="rrecords"/>) or
non-supplemental.
If the NICK record is supplemental, the resolver only returns the
@@ -2429,8 +2432,9 @@ NICK: john (Supplemental)
<t>
In terms of crypto-agility, whenever the need for an updated cryptographic
scheme arises to, for example, replace ECDSA over Ed25519 for
- PKEY records it may simply be introduced
- through a new record type. Such a new record type may then replace
+ PKEY records it can simply be introduced
+ through a new record type.
+ Zone administrators can then replace
the delegation record type for future records.
The old record type remains
and zones can iteratively migrate to the updated zone keys.
@@ -2471,7 +2475,7 @@ NICK: john (Supplemental)
be after the last published block.
For records where an absolute expiration time is used, the implementation
<bcp14>MUST</bcp14> ensure that the expiration time is always increased when the record
- data changes. For example, the expiration time on the wire may be increased
+ data changes. For example, the expiration time on the wire could be increased
by a single microsecond even if the user did not request a change.
In case of deletion of all resource records under a label, the
implementation <bcp14>MUST</bcp14> keep track of the last absolute expiration time
@@ -2494,7 +2498,7 @@ NICK: john (Supplemental)
GNS names are UTF-8 strings. Consequently, GNS faces similar issues
with respect to name spoofing as DNS does for internationalized
domain names.
- In DNS, attackers may register similar sounding or looking
+ In DNS, attackers can register similar sounding or looking
names (see above) in order to execute phishing attacks.
GNS zone administrators must take into account this attack vector and
incorporate rules in order to mitigate it.
@@ -2513,7 +2517,7 @@ NICK: john (Supplemental)
<t>
In GNS, zone administrators need to manage and protect their zone
keys. Once a zone key is lost, it cannot be recovered or revoked.
- Revocation messages may be pre-calculated if revocation is
+ Revocation messages can be pre-calculated if revocation is
required in case a zone key is lost.
Zone administrators, and for GNS this includes end-users, are
required to responsibly and diligently protect their cryptographic
@@ -2539,7 +2543,7 @@ NICK: john (Supplemental)
While implementations following this specification will be
interoperable, if two implementations connect to different storages
they are mutually unreachable.
- This may lead to a state where a record may exist in the global
+ This can lead to a state where a record exists in the global
namespace for a particular name, but the implementation is not
communicating with the storage and is hence unable to resolve it.
This situation is similar to a split-horizon DNS configuration.
@@ -2547,8 +2551,8 @@ NICK: john (Supplemental)
it is built for.
The storage used will most likely depend on the specific application
context using GNS resolution.
- For example, one application may be the resolution of hidden services
- within the Tor network, which may suggest using Tor routers for storage.
+ For example, one application is the resolution of hidden services
+ within the Tor network, which would suggest using Tor routers for storage.
<!-- FIXME: add non-normative reference to Tor / Tor hidden services here? -->
Implementations of "aggregated" storages are conceivable, but
are expected to be the exception.
@@ -2578,7 +2582,7 @@ NICK: john (Supplemental)
Zone administrators are advised to pre-generate zone revocations
and to securely store the revocation information in case the zone
key is lost, compromised or replaced in the future.
- Pre-calculated revocations may cease to be valid due to expirations
+ Pre-calculated revocations can cease to be valid due to expirations
or protocol changes such as epoch adjustments.
Consequently, implementers and users must take precautions in order
to manage revocations accordingly.
@@ -2617,7 +2621,7 @@ NICK: john (Supplemental)
within a zone.
Record blocks are published in encrypted form using keys derived from the
zone key and record label. Zone administrators should
- carefully consider if the label and zone key may be public or if
+ carefully consider if the label and zone key is public or if
those should be used and considered as a shared secret.
Unlike zone keys, labels can also be guessed by
an attacker in the network observing queries and responses. Given
