Subject: I-D ACTION:draft-ietf-secsh-publickeyfile-06.txt

From: [email-masked]
Date: Mon, 21 Mar 2005 15:34:35 -0500

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Secure Shell Working Group of the IETF.

	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
	
This document formally documents the existing public key file format
in use for exchanging public keys between different SECSH
implementations.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-secsh-publickeyfile-06.txt

To remove yourself from the I-D Announcement list, send a message to 
[email-masked] with the word unsubscribe in the body of the message.  
You can also visit https://www1.ietf.org/mailman/listinfo/I-D-announce 
to change your subscription settings.

Internet-Drafts are also available by anonymous FTP. Login with the username
"anonymous" and a password of your e-mail address. After logging in,
type "cd internet-drafts" and then
	"get draft-ietf-secsh-publickeyfile-06.txt".

A list of Internet-Drafts directories can be found in
http://www.ietf.org/shadow.html 
or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

Internet-Drafts can also be obtained by e-mail.

Send a message to:
	[email-masked].
In the body type:
	"FILE /internet-drafts/draft-ietf-secsh-publickeyfile-06.txt".
	
NOTE:	The mail server at ietf.org can return the document in
	MIME-encoded form by using the "mpack" utility.  To use this
	feature, insert the command "ENCODING mime" before the "FILE"
	command.  To decode the response(s), you will need "munpack" or
	a MIME-compliant mail reader.  Different MIME-compliant mail readers
	exhibit different behavior, especially when dealing with
	"multipart" MIME messages (i.e. documents which have been split
	up into multiple messages), so check your local documentation on
	how to manipulate these messages.

Below is the data which will enable a MIME compliant mail reader
implementation to automatically retrieve the ASCII version of the
Internet-Draft.

---

From: Bill Sommerfeld <[email-masked]>
Date: Mon, 21 Mar 2005 17:09:01 -0500

> 	Filename	: draft-ietf-secsh-publickeyfile-06.txt

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. 

This Last Call assumes that the following nits will be corrected in a
new revision submitted in the near future:

1) The draft references:

   [RFC2044]  Yergeau, F., "UTF-8, a Transformation Format of Unicode
              and ISO 10646", October 1996.

which was obsoleted by RFC2279, which was in turn obsoleted by RFC3629. 

2) as discussed on the WG list about a year ago, this format is (alas)
subtly different from the formats documented in rfc1113 and rfc1421 in
two ways:

  a) the BEGIN/END markers start/end with four dashes and a space rather
than five dashes.
since the center part of the markers are also different from other
PEM-type delimeters.

  b) no blank line between comment/header section and the start of the
base64-encoded key.

As there is running code using these formats I don't think it's
worthwhile to spec a migration path to 1421-style delimeters, but since
implementors may want to reuse existing PEM-format code here, we should
explicitly mention the deltas from RFC1421 and cite 1421 as an
informative reference.

Proposed edits:

 1) replace references to RFC2044 with references to RFC3629.

 2) insert a new subsection of section 3 titled "Differences with
RFC1421 PEM formats" containing the following text or equivalent:

Implemetors should take care to notice that while the format is
superficially similar to that specified by PEM [RFC1421] and PGP
[RFC1991], it is not identical; most notably:
 1) The other specifications use different BEGIN/END delimeters (five
dashes, no space rather than four dashes and a space).
 2) there is no blank line before the start of the base64-encoded
contents.

(end proposed edits)

							- Bill

---

From: Joseph Galbraith <[email-masked]>
Date: Tue, 22 Mar 2005 11:47:58 -0700

> new revision submitted in the near future:

I just submitted it.

>  1) replace references to RFC2044 with references to RFC3629.

Done.
>  2) there is no blank line before the start of the base64-encoded

Done.

Thanks,

Joseph

---

From: Bill Sommerfeld <[email-masked]>
Date: Tue, 22 Mar 2005 16:13:47 -0500

On Tue, 2005-03-22 at 13:47, Joseph Galbraith wrote:
> > ...

Excellent.  Thank you!

						- Bill

---

From: Ben Harris <[email-masked]>
Date: Wed, 23 Mar 2005 13:11:16 +0000

>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: [email-masked]
+   Comment: [email-masked]
 
    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

---

From: Joseph Galbraith <[email-masked]>
Date: Wed, 23 Mar 2005 11:26:55 -0700

> things that merit explanation.

Thanks.

> amended if the interim period ever ends.

I have an alternate proposal.  The draft has been around for a while
now; how about we declare the interim period as ended.

I've edited the draft accordingly.

> RFC-822 headers are case-insensitive, I think this spec needs to be clear.

Specified as insensitive.

> fields, or at most one of each in that order.

Removed completely as 'transition period' is now over.

Done.

Done.

> needs to be, but it seems to be usual to at least allocate some namespace

How about:

    New headers that are of the from "x-" are considered experimental,
    and may be used without IETF consensus.

    All other headers are reserved for use only by IETF consensus.

Done.

> is affiliated with ssh.com.

Removed.  I wasn't sure.

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

Thanks... since I don't work on the text, but rather an XML source,
I applied manually.

Hopefully I didn't mess anything up.

Done.

Also removed:

-  Where this document departs from current practice, it also suggests a
-  mechanism for backwards compatibility.

>     key file headers that contain only a Subject field followed by a

Removed this paragraph entirely.

> +   quotation marks, implementations SHOULD remove them before using the value.

Here I did exactly as your patch did and left in the MAY include quotes;
this doesn't seem to be that large a burden to just leave permenantly.

Thanks,

Joseph

PS. I'll wait a day for other comments and then send an updated version.

---

From: Bill Sommerfeld <[email-masked]>
Date: Wed, 23 Mar 2005 13:46:52 -0500

ok, so this is "mission creep", but from looking through the other
expired drafts, it occurred to me that maybe the right thing to do with
the expired (and tiny) draft-ietf-secsh-fingerprint-01.txt is to fold
its content into this draft.

http://tools.ietf.org/wg/secsh/draft-ietf-secsh-fingerprint/draft-ietf-secsh-fingerprint-01.txt

though, given the current status of MD5 we need to defend its use in a
security considerations section.

we should note that (1) use of MD5 in this form is documents existing
practice, (2) the MD5 property which we rely on is 2nd-preimage
resistance, not collision-resistance.

thoughts?

---

From: Joseph Galbraith <[email-masked]>
Date: Wed, 23 Mar 2005 14:35:26 -0700

Done.

Should I hold off a while before assaulting the draft editor with
another version or repost now?

Thanks,

Joseph

---

From: Bill Sommerfeld <[email-masked]>
Date: Wed, 23 Mar 2005 17:04:05 -0500

> > resistance, not collision-resistance.

Excellent.

> another version or repost now?

I would hold off for a day or two to see who else has comments and then
send it in.

						- Bill

---

From: Ben Harris <[email-masked]>
Date: Thu, 24 Mar 2005 12:57:05 +0000

>>  2) there is no blank line before the start of the base64-encoded

Wouldn't it be better to reference OpenPGP (RFC 2440), rather than PGP
(RFC 1991)?

Other differences that might be worth mentioning:
3) there is no CRC at the end of the base64-encoded block.
4) header continuation uses a backslash at the end of the continued line
   rather then whitespace at the start of the next line.

Also, since the PEM and OpenPGP formats are different, "that specified"
should read "those specified".

A random interesting problem I observe with the header continuation format:
there's no way to write a header whose value ends with a backslash.  I don't
think this is worth worrying about.

-- 
Ben Harris

---

From: Joseph Galbraith <[email-masked]>
Date: Thu, 24 Mar 2005 10:21:08 -0700

> Wouldn't it be better to reference OpenPGP (RFC 2440), rather than PGP

Okay.

Done.

Done.

> think this is worth worrying about.

I think you are right in that it isn't worth worrying about it;
the trivial solution would be to specify that '\\' at the end
of a header line signifies a '\' at the end of the value rather
than a continuation.  But I say let's not bother.

Thanks,

Joseph

---

From: Ben Harris <[email-masked]>
Date: Thu, 24 Mar 2005 18:20:35 +0000 (GMT)

> I think you are right in that it isn't worth worrying about it;

Especially since it isn't true.  A trailing backslash can be encoded as 
two backslashes followed by two linefeeds.  Sorry for the false alarm.

Something that does occur to me, though, is that the range of characters 
allowed in header-tags and header-values should perhaps be limited a bit. 
I'd suggest requiring those in header-tags to be printable and not ' ' or 
':', which is what RFC 822 requires.  I'm not sure I know Unicode well 
enough to know what's sensible in header-values, but I feel that at least 
excluding U+0000 would make life easier for C implementations, and it's 
obviously necessary to exclude U+000A and U+000D.

-- 
Ben Harris

---

From: Ben Harris <[email-masked]>
Date: Mon, 28 Mar 2005 14:02:07 +0100

>appropriate, as are comments suggesting changes to the spec. 

I've just noticed another bug: In section 3.1 (Line Termination Characters),
there should be a sentence: "A public key file MUST use the same line
termination convention throughout."  Without this, the spec could be
interpreted as allowing for different line-endings on different lines, which
would make some files ambiguous.

-- 
Ben Harris