Re: WG Chair Nits & start of WG Last Call: draft-ietf-secsh-publickeyfile-06.txt

[Ben Harris <bjh21%bjh21.me.uk@localhost>]

In article <1111442941.5683.257.camel@thunk> you write:
>On Mon, 2005-03-21 at 15:34, Internet-Drafts%ietf.org@localhost wrote:
>> 	Title		: SSH Public Key File Format
>> 	Author(s)	: J. Galbraith, R. Thayer
>> 	Filename	: draft-ietf-secsh-publickeyfile-06.txt
>> 	Pages		: 11
>> 	Date		: 2005-3-21
>
>I am starting an official WG Last Call on this document, for publication
>as an Informational RFC.  This last call period expires on April 4th,
>2005.
>
>During this Last Call period, comments supporting publication are
>appropriate, as are comments suggesting changes to the spec. 

I took a printout with me on a train yesterday, and it's now covered in blue
ink.  Most of my suggestions are in the form of a diff, but there are a few
things that merit explanation.

I think having things specified as being permitted (or encouraged) "for an
interim period," without specifying the length of that period, is pointless. 
My patch removes such references on the assumption that the spec can be
amended if the interim period ever ends.

The case-sensitivity or otherwise of Header-tags is unspecified.  Since
RFC-822 headers are case-insensitive, I think this spec needs to be clear.

   Existing implementations may not correctly handle unrecognized
   fields.  During a transition period, implementations SHOULD generate
   key file headers that contain only a Subject field followed by a
   Comment field.

It's unclear whether this means that implementations SHOULD emit both
fields, or at most one of each in that order.

   Contain a user specified comment which will be displayed when using
   the key.

I think "will" needs to be replaced with "MAY", "SHOULD", or "MUST", but I
don't know which is intended.  The sentence should perhaps also be recast in
the active voice to make it clear who's doing the displaying.

There should perhaps be an example of wrapped lines.

There's no mechanism for defining new headers.  I'm not sure whether there
needs to be, but it seems to be usual to at least allocate some namespace
for private use.

It's traditional to list RFCs in the References section in numerical order.

I don't think the Trademark Notice is required, since neither of the authors
is affiliated with ssh.com.


Now for the dull fixes -- I've avoided rewrapping paragraphs so as to keep
the diff intelligible.

--- draft-ietf-secsh-publickeyfile-06.txt	Mon Mar 21 16:26:06 2005
+++ draft-ietf-secsh-publickeyfile-bjh.txt	Wed Mar 23 12:48:20 2005
@@ -43,7 +43,7 @@
 
 Abstract
 
-   This document formally documents the existing public key file format
+   This document formally documents an existing public key file format
    in use for exchanging public keys between different SSH
    implementations.
 
@@ -61,8 +61,8 @@
    1.  Conventions used in this document  . . . . . . . . . . . . . .  3
    2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
    3.  Key File Format  . . . . . . . . . . . . . . . . . . . . . . .  5
-     3.1   Line termination Characters  . . . . . . . . . . . . . . .  5
+     3.1   Line Termination Characters  . . . . . . . . . . . . . . .  5
-     3.2   Begin and end markers  . . . . . . . . . . . . . . . . . .  5
+     3.2   Begin and End Markers  . . . . . . . . . . . . . . . . . .  5
      3.3   Key File Header  . . . . . . . . . . . . . . . . . . . . .  5
        3.3.1   Subject Header . . . . . . . . . . . . . . . . . . . .  6
        3.3.2   Comment Header . . . . . . . . . . . . . . . . . . . .  6
@@ -172,7 +172,7 @@
 
    In order to use public key authentication, public keys must be
    exchanged between client and server.  This document formally
-   describes the existing public key file format, with few exceptions.
+   describes an existing public key file format.
 
    Where this document departs from current practice, it also suggests a
    mechanism for backwards compatibility.
@@ -226,37 +226,38 @@
 
 3.  Key File Format
 
+   In order to implement public key authentication,
    SSH implementations must share public key files between the client
    and the server in order to interoperate.
 
    A key file is a text file, containing a sequence of lines.  Each line
-   in the file MUST NOT be longer than 72 bytes.
+   in the file MUST NOT be longer than 72 bytes excluding line
+   termination characters.
 
-3.1  Line termination Characters
+3.1  Line Termination Characters
 
-   In order to achieve the goal of being able to exchange public key
-   files between servers, implementations are REQUIRED to read files
+   Implementations are REQUIRED to read files
    using any of the common line termination sequence, <CR>, <LF> or
    <CR><LF>.
 
-   Implementations may generate files using which ever line termination
-   convention is most convenient
+   Implementations may generate files using whichever of these line
+   termination conventions is most convenient.
 
-3.2  Begin and end markers
+3.2  Begin and End Markers
 
    The first line of a conforming key file MUST be a begin marker, which
    is the literal text:
 
    ---- BEGIN SSH2 PUBLIC KEY ----
 
-   The last line of a conforming key file MUST be a end marker, which is
+   The last line of a conforming key file MUST be an end marker, which is
    the literal text:
 
    ---- END SSH2 PUBLIC KEY ----
 
 3.3  Key File Header
 
-   The key file header section consists of multiple RFC822 - style
+   The key file header section consists of multiple RFC822-style
    header fields.  Each field is a line of the following format:
 
    Header-tag ':' ' ' Header-value
@@ -267,10 +268,12 @@
 
    A line is continued if the last character in the line is a '\'.  If
    the last character of a line is a '\', then the logical contents of
-   the line is formed by removing the '\' and appending the contents of
+   the line is formed by removing the '\' and the line termination
+   characters, and appending the contents of
    the next line.
 
-   The Header-tag MUST be US-ASCII.  The Header-value MUST be encoded in
+   The Header-tag MUST be encoded in US-ASCII.  The Header-value MUST be
+   encoded in
    UTF-8. [RFC2044]
 
 
@@ -281,20 +284,20 @@
 
 
    A line that is not a continuation line that has no ':' in it is
-   assumed to be the first line of the base 64 encoded body (Section 8)
+   the first line of the base64-encoded body (Section 3.4).
 
    Compliant implementations MUST ignore unrecognized header fields.
    Implementations SHOULD preserve unrecognized header fields when
    manipulating the key file.
 
    Existing implementations may not correctly handle unrecognized
-   fields.  During a transition period, implementations SHOULD generate
+   fields.  Implementations SHOULD generate
    key file headers that contain only a Subject field followed by a
    Comment field.
 
 3.3.1  Subject Header
 
-   This field currently is used to store the login-name that the key was
+   This field is used to store the login-name that the key was
    generated under.  For example:
 
    Subject: user
@@ -307,26 +310,26 @@
    It is suggested that this field default to user@hostname for the user
    and machine used to generate the key.  For example:
 
-   Comment: user%mycompany.com@localhost
+   Comment: user%example.com@localhost
 
    Currently, common practice is to quote the Header-value of the
-   Comment, and some existing implementations fail if these quotes are
+   Comment by prefixing and suffixing it with '"' characters, and
+   some existing implementations fail if these quotation marks are
    omitted.
 
-   Compliant implementations MUST function correctly if the quotes are
+   Compliant implementations MUST function correctly if the quotation marks are
    omitted.
 
-   During an interim period implementations MAY include the quotes.  If
+   Implementations MAY include the quotation marks.  If
    the first and last characters of the Header-value are matching
-   quotes, implementations SHOULD remove them before using the value.
+   quotation marks, implementations SHOULD remove them before using the value.
 
 3.4  Public Key File Body
 
    The body of a public key file consists of the public key blob as
-   described in the SSH transport draft [I-D.ietf-secsh-transport],
-   section 4.6, "Public Key Algorithms", encoded in base 64 as specified
-   in RFC-2045, section 6.8, "Base64 Content-Transfer-Encoding".
-   [RFC2045]
+   described in [I-D.ietf-secsh-transport],
+   section 4.6, "Public Key Algorithms", encoded in base64 as specified
+   in [RFC2045], section 6.8, "Base64 Content-Transfer-Encoding".
 
 
 
@@ -337,7 +340,7 @@
 
 
    As with all other lines, each line in the body MUST NOT be longer
-   than 72 characters.
+   than 72 characters excluding line termination characters.
 
 3.5  Examples
 
@@ -394,7 +397,7 @@
 
 4.  IANA Considerations
 
-   There are non IANA registries or other considerations associated with
+   There are no IANA registries or other considerations associated with
    this document.
 
 
@@ -477,9 +480,6 @@
 
    [RFC2044]  Yergeau, F., "UTF-8, a Transformation Format of Unicode
               and ISO 10646", October 1996.
-
-   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
-              3", October 1996.
 
    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", March 1997.


-- 
Ben Harris