From: Stephen Farrell [stephen(_dot_)farrell(_at_)cs(_dot_)tcd(_dot_)ie]
For example, in section 3, the syntax of the "ni" URI scheme is
spelled out with admirable clarity and exactness, including:
Digest Value [Required] The digest value MUST be encoded using the
base64url [RFC4648] encoding.
Hmmm, "the digest value"... The digest value *of what*?
The input to the digest is not defined by this draft, except
in the case of public keys. (See other comments wrt MIME &
Content Type as well.)
True... But what I am looking for is an explicit statement that the
process described in the draft *takes as input a string* which is not
defined in this draft. Ideally, that fact should be stated separately
before the first description of any operation which is applied to the
string. ("When defining a function, you must first state its
signature...")
Going back to section 2 for a moment, there is:
When the input to the hash algorithm is a public key value, as may be
used by various security protocols, the hash SHOULD be calculated
over the public key in an X.509 SubjectPublicKeyInfo structure
(Section 4.1 of [RFC5280]).
I can see what this means, but it's not very clear. A better way to
write it would be:
When the input is intended to be a public key value, as may be
used by various security protocols, the input to the hash SHOULD
be an X.509 SubjectPublicKeyInfo structure (Section 4.1 of
[RFC5280]) containing the public key rather than the public key
value itself.
Have to say I prefer the existing text.
OK... But I dislike the phrase "hash calculated over" -- a hash is a
function, it has an input, and it has an output.
Unfortunately, the example is somewhat incongruous, as "Hello World!"
is not obviously a name or reference to any object.
In this case the object named is just those 12 characters.
Thus while it
still is clear how it can be input to the processes that are described
in the draft, it doesn't seem to be a conceptually typical example.
Well, I could have said a file that contains "Hello World!" (12 chars:-)
But I don't think its much clearer, maybe less.
It all depends on how one creates the input string from the object,
and there are a lot of ways of doing that (object contents, object
locator, etc.). Properly speaking, that is out of scope of this
draft. But the explanatory talks a great deal about "refering to an
object" without providing any details, which leads me assume that the
input strings are the locators of the objects in question, else they
would be references to the objects.
Then we get to:
Given the SubjectPublicKeyInfo in Figure 6 we derive the names shown
in Figure 7 for this value.
I can't tell what this means. What is "this value"? Is it the
immediately preceding URI
(http://example.com/.well-known/ni/sha-256/f4OxZX_x_FO5LcGBSKHWXfwtSx-j1ncoSt3SABJtkGk)?
In what manner does the "given" SubjectPublicKeyInfo affect the names?
No, the input value is the DER encoding of the SPKI as stated earlier.
I guess the following is a little more correct so I've changed it to:
Given the DER-encoded SubjectPublicKeyInfo in Figure 6 we derive
the names shown in Figure 7 for this value.
If the input value was meant to be the SubjectPublicKeyInfo itself,
the sentence would not add "this value", which strongly suggests a
*different* value than the one mentioned just before in the same
sentence. Rather, one would say:
We derive the names shown in Figure 7 from the SubjectPublicKeyInfo
in Figure 6.
I don't get the difference to be honest.
To my ear, the phrase "this value" in the sentence is strongly implied
*not* to be "the SubjectPublicKeyInfo". It's hard to explain why, of
course, but it has something to do with the fact that if they were the
same, a separate noun phrase would not be needed, a simpler sentence
could be used to express the same meaning.
To avoid that effect, I would say:
We derive the names shown in Figure 7 from the SubjectPublicKeyInfo
in Figure 6.
or
From the SubjectPublicKeyInfo in Figure 6, we derive the names
shown in Figure 7.
Dale