Subject: [Gen-art] Gen-ART review of draft-ietf-tls-oob-pubkey-09

From: Christer Holmberg <[email-masked]>
Date: Tue, 6 Aug 2013 14:19:16 +0000

I am the assigned Gen-ART reviewer for this draft. For background on Gen-ART, please see the FAQ at <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>

Document:                         draft-ietf-tls-oob-pubkey-09

Reviewer:                           Christer Holmberg

Review Date:                     6 August 2013

IETF LC End Date:             16 August 2013

IETF Telechat Date:         N/A

Summary:  There some editorial issues, that I personally think would make the document more clear.

Major Issues: None

Minor Issues:

GENERAL:
========

QGEN_1:

The document talks about "raw public keys". I know it is a commonly used term, but it is not defined in RFC 5246, I think it would be good to have a short section which
describes what it is, the advantages compared to certificates etc. I KNOW there is some text in the Security Section, but I think a general description would be useful in
the beginning of the spec also. Note that the security aspects do not need to be described in such section.

QGEN_2:

Some parts of the document talk about "TLS clients and servers", while other parts talk only about "clients and servers". I suggest to use consistant wording.

Section 1:
=======

Q1_1:

s/"using the TLS handshake"/"as part of the TLS handshake procedure"

Q1_2:

s/"TLS handshake and validated"/"TLS handshake and are validated"

Q1_3:

At the end of the section, I would suggest a new paragraph, which says something like:

                             "Section 3 defines the two TLS extensions 'client_certificate_type' and 'server_certificate_type',
                             which can be used as part of an extended TLS handshake when raw public keys are to be used. Section
                             4 defines the TLS handshake extension."

Section 3:
=======

Q3_1:

I would suggest to have an introduction sub-section, and then separate sub-sections for
the 'client_certificate_type' and 'server_certificate_type' usage details, e.g. something like:

                             3.1.                      General
                             3.2.                      'client_certificate_type' usage

                             When used in a Client Hello message, the 'client_certificate_type' is used to blah blah blah
                             When used in a Server Hello message, the 'client_certificate_type' is used to blah blah blah

                             3.3.                      'server_certificate_type' usage

                             When used in a Client Hello message, the 'server_certificate_type' is used to blah blah blah
                             When used in a Server Hello message, the 'server_certificate_type' is used to blah blah blah"

(Of course, if you rather want to devide the sub-sctions based on hello type, I'm fine with that also :)

Q3_2:

The first sentence in the section says:

                             "This section describes the changes to the TLS handshake message contents when raw public keys are to be used."

I think this is a little missleading, as the TLS handshake message is extended in section 4. So, similar to the text I suggested
for section 1, I suggest something like:

                             "This section defines the two TLS extensions 'client_certificate_type' and 'server_certificate_type',
                             which can be used as part of an extended TLS handshake when raw public keys are to be used. Section
                             4 defines the TLS handshake extension."

SECTION 4:
========

Q4_1:

I would suggest an introduction section, e.g. something like:

                             "4.1. General

                             This section extends the ClientHello and ServerHello messages, according
                             to the extension procedures defined in [RFC5246].

                             The specification does not extend or modify any other TLS messages."

...and then remove current sections 4.3. and 4.4.

Section 5:
=======

Q5_1:

I would suggest to have sub-sections for each example, e.g. something like:

                             5.1. TLS client indicates ability to receive and validate raw public keys from the server
                             5.2. TLS client ans server use raw public keys.
                             5.3. Combined usage of raw publis keys and X.509 certificate

Then, each sub-section would start with: "This section shows an example where blah blah blah...".

Q5_2:

The text in the FIRST example says:

                             "The 'client_certificate_type' extension indicates this in [1].  When the
                             TLS server receives the client hello it processes the 'client_certificate_type' extension."

However, in the flow picutre there is no 'client_certificate_type'. Is there some copy/paste error?