Draft: draft-ietf-tls-tls13

Commentary: you might want to take a look if you have time . Will merge this afternoon 
 All LGTM . I 'm doing a full read - through right now to hunt for editorial issues that have crept in over time , so I 'll have a broader cleanups PR to submit a bit later , as well . 
 Thanks . I did a read through myself but I 'm sure more stuff has crept in as well . ,   wrote :
Paragraph (version A):
These properties should be true even in the face of an attacker who
controls the channel, as described in RFC3552.  See Section [TODO]
for a more formal statement of the relevant security properties.
Paragraph (version A):
A handshake protocol which authenticates the communicating
parties, negotiates cryptographic modes and parameters, and
establishes shared keying material.  The handshake protocol is
designed to resist tampering; an active attacker should not be
able to force the peers to negotiate different parameters than
they would if the connection were not under attack.
Paragraph (version A):
A record protocol which uses the parameters established by the
handshake protocol to protect traffic between the communicating
peers.  The record protocol divides traffic up into a series of
records, each of which is independently protected using the
traffic keys.
Paragraph (version A):
One advantage of TLS is that it is application protocol independent.
Higher-level protocols can layer on top of TLS transparently.  The
TLS standard, however, does not specify how protocols add security
with TLS; the decisions on how to initiate TLS handshaking and how to
interpret the authentication certificates exchanged are left to the
judgment of the designers and implementors of protocols that run on
top of TLS.
Paragraph (version B):
These properties should be true even in the face of an attacker who
controls the channel, as described in RFC3552.  See security-analysis
for a more complete statement of the relevant security properties.
Paragraph (version B):
A handshake protocol (handshake-protocol) which authenticates the
communicating parties, negotiates cryptographic modes and
parameters, and establishes shared keying material.  The handshake
protocol is designed to resist tampering; an active attacker
should not be able to force the peers to negotiate different
parameters than they would if the connection were not under
attack.
Paragraph (version B):
A record protocol (record-protocol) which uses the parameters
established by the handshake protocol to protect traffic between
the communicating peers.  The record protocol divides traffic up
into a series of records, each of which is independently protected
using the traffic keys.
Paragraph (version B):
TLS is application protocol independent; higher-level protocols can
layer on top of TLS transparently.  The TLS standard, however, does
not specify how protocols add security with TLS; the decisions on how
to initiate TLS handshaking and how to interpret the authentication
certificates exchanged are left to the judgment of the designers and
implementors of protocols that run on top of TLS.
Paragraph (version A):
The server processes the ClientHello and determines the appropriate
cryptographic parameters for the connection.  It then responds with
its own ServerHello which indicates the negotiated connection
parameters. [server-hello].  The combination of the ClientHello and
the ServerHello determines the values of ES and SS, as described
above.  If either a pure (EC)DHE or (EC)DHE-PSK cipher suite is in
use, then the ServerHello will contain a "key_share" extension with
the server's ephemeral Diffie-Hellman share which MUST be in the same
group.  If a pure PSK or an (EC)DHE-PSK cipher suite is negotiated,
then the ServerHello will contain a "pre_shared_key" extension
indicating which of the client's offered PSKs was selected.
Paragraph (version B):
The server processes the ClientHello and determines the appropriate
cryptographic parameters for the connection.  It then responds with
its own ServerHello which indicates the negotiated connection
parameters. [server-hello].  The combination of the ClientHello and
the ServerHello determines the shared keys.  If either a pure (EC)DHE
or (EC)DHE-PSK cipher suite is in use, then the ServerHello will
contain a "key_share" extension with the server's ephemeral Diffie-
Hellman share which MUST be in the same group as one of the client's
shares.  If a pure PSK or an (EC)DHE-PSK cipher suite is negotiated,
then the ServerHello will contain a "pre_shared_key" extension
indicating which of the client's offered PSKs was selected.
Paragraph (version A):
If the client has not provided an appropriate "key_share" extension
(e.g. it includes only DHE or ECDHE groups unacceptable or
unsupported by the server), the server corrects the mismatch with a
HelloRetryRequest and the client will need to restart the handshake
with an appropriate "key_share" extension, as shown in Figure 2.  If
no common cryptographic parameters can be negotiated, the server will
send a "handshake_failure" or "insufficient_security" fatal alert
(see alert-protocol).
Paragraph (version B):
If the client has not provided an appropriate "key_share" extension
(e.g., it includes only DHE or ECDHE groups unacceptable or
unsupported by the server), the server corrects the mismatch with a
HelloRetryRequest and the client will need to restart the handshake
with an appropriate "key_share" extension, as shown in Figure 2.  If
no common cryptographic parameters can be negotiated, the server will
send a "handshake_failure" or "insufficient_security" fatal alert
(see alert-protocol).
Paragraph (version A):
Note: the handshake transcript includes the initial ClientHello/
HelloRetryRequest exchange.  It is not reset with the new
ClientHello.
Paragraph (version B):
Note: the handshake transcript includes the initial ClientHello/
HelloRetryRequest exchange; it is not reset with the new ClientHello.
Paragraph (version A):
Although TLS PSKs can be established out of band, PSKs can also be
established in a previous session and then reused ("session
resumption").  Once a handshake has completed, the server can send
the client a PSK identity which corresponds to a key derived from the
initial handshake (See NewSessionTicket).  The client can then use
that PSK identity in future handshakes to negotiate use of the PSK;
if the server accepts it, then the security context of the new
connection is tied to the original connection.  In TLS 1.2 and below,
this functionality was provided by "session resumption" and "session
tickets" RFC5077.  Both mechanisms are obsoleted in TLS 1.3.
Paragraph (version B):
Although TLS PSKs can be established out of band, PSKs can also be
established in a previous session and then reused ("session
resumption").  Once a handshake has completed, the server can send
the client a PSK identity which corresponds to a key derived from the
initial handshake (See NewSessionTicket).  The client can then use
that PSK identity in future handshakes to negotiate use of the PSK;
if the server accepts it, then the security context of the new
connection is tied to the original connection.  In TLS 1.2 and below,
this functionality was provided by "session IDs" and "session
tickets" RFC5077.  Both mechanisms are obsoleted in TLS 1.3.
Paragraph (version A):
The TLS Handshake Protocol is one of the defined higher-level clients
of the TLS Record Protocol.  This protocol is used to negotiate the
secure attributes of a session.  Handshake messages are supplied to
the TLS record layer, where they are encapsulated within one or more
TLSPlaintext or TLSCiphertext structures, which are processed and
transmitted as specified by the current active session state.
Paragraph (version A):
The TLS Handshake Protocol messages are presented below in the order
they MUST be sent; sending handshake messages in an unexpected order
results in an "unexpected_message" fatal error.  Unneeded handshake
messages can be omitted, however.
Paragraph (version B):
The handshake protocol is used to negotiate the secure attributes of
a session.  Handshake messages are supplied to the TLS record layer,
where they are encapsulated within one or more TLSPlaintext or
TLSCiphertext structures, which are processed and transmitted as
specified by the current active session state.
Paragraph (version B):
Protocol messages MUST be sent in the order defined below (and shown
in the diagrams in protocol-overview).  Sending handshake messages in
an unexpected order results in an "unexpected_message" fatal error.
Unneeded handshake messages can be omitted, however.
Paragraph (version A):
The ClientHello message includes a random structure, which is used
later in the protocol.
Paragraph (version A):
The cipher suite list, passed from the client to the server in the
ClientHello message, contains the combinations of cryptographic
algorithms supported by the client in order of the client's
preference (favorite choice first).  Each cipher suite defines a key
exchange algorithm, a record protection algorithm (including secret
key length) and a hash to be used with HKDF.  The server will select
a cipher suite or, if no acceptable choices are presented, return a
"handshake_failure" alert and close the connection.  If the list
contains cipher suites the server does not recognize, support, or
wish to use, the server MUST ignore those cipher suites, and process
the remaining ones as usual.
Paragraph (version A):
This is a list of the cryptographic options supported by the
client, with the client's first preference first.  Values are
defined in cipher-suites.
Paragraph (version B):
This is a list of the cryptographic options supported by the
client, with the client's first preference first.  Each cipher
suite defines a key exchange algorithm, a record protection
algorithm (including secret key length) and a hash to be used with
HKDF.  The server will select a cipher suite or, if no acceptable
choices are presented, return a "handshake_failure" alert and
close the connection.  If the list contains cipher suites the
server does not recognize, support, or wish to use, the server
MUST ignore those cipher suites, and process the remaining ones as
usual.  Values are defined in cipher-suites.
Paragraph (version A):
In prior versions of TLS, the extensions field could be omitted
entirely if not needed, similar to ClientHello.  As of TLS 1.3, all
clients and servers will send at least one extension (at least
"key_share" or "pre_shared_key").
Paragraph (version A):
"illegal_parameter" alert.
Paragraph (version B):
"illegal_parameter" alert.  In prior versions of TLS, the
extensions field could be omitted entirely if not needed, similar
to ClientHello.  As of TLS 1.3, all clients and servers will send
at least one extension (at least "key_share" or "pre_shared_key").
Paragraph (version A):
The server_version, cipher_suite, and extensions fields have the same
meanings as their corresponding values in the ServerHello.  The
server SHOULD send only the extensions necessary for the client to
generate a correct ClientHello pair (currently no such extensions
exist.)  As with ServerHello, a HelloRetryRequest MUST NOT contain
any extensions that were not first offered by the client in its
ClientHello.
Paragraph (version B):
The server_version, cipher_suite, and extensions fields have the same
meanings as their corresponding values in the ServerHello.  [[NOTE:
cipher_suite may disappear. https://github.com/tlswg/tls13-spec/
issues/528]] The server SHOULD send only the extensions necessary for
the client to generate a correct ClientHello pair (currently no such
extensions exist.)  As with ServerHello, a HelloRetryRequest MUST NOT
contain any extensions that were not first offered by the client in
its ClientHello.
Paragraph (version A):
When sent by the client, the "supported_groups" extension indicates
the named groups which the client supports, ordered from most
preferred to least preferred.
Paragraph (version B):
When sent by the client, the "supported_groups" extension indicates
the named groups which the client supports for key exchange, ordered
from most preferred to least preferred.
Paragraph (version A):
Diffie-Hellman DH parameters for both clients and servers are encoded
in the opaque key_exchange field of a KeyShareEntry in a KeyShare
structure.  The opaque value contains the Diffie-Hellman public value
(Y = g^X mod p), encoded as a big-endian integer, padded with zeros
to the size of p.
Paragraph (version B):
Diffie-Hellman DH parameters for both clients and servers are encoded
in the opaque key_exchange field of a KeyShareEntry in a KeyShare
structure.  The opaque value contains the Diffie-Hellman public value
(Y = g^X mod p), encoded as a big-endian integer, padded with zeros
to the size of p in bytes.
Paragraph (version A):
The "obfuscated_ticket_age" parameter in the client's "early_data"
extension SHOULD be used by servers to limit the time over which the
first flight might be replayed.  A server can store the time at which
it sends a server configuration to a client, or encode the time in a
ticket.  Then, each time it receives an "early_data" extension, it
can subtract the base value and check to see if the value used by the
client matches its expectations.
Paragraph (version B):
The "obfuscated_ticket_age" parameter in the client's "early_data"
extension SHOULD be used by servers to limit the time over which the
first flight might be replayed.  A server can store the time at which
it sends a session ticket to the client, or encode the time in the
ticket.  Then, each time it receives an "early_data" extension, it
can subtract the base value and check to see if the value used by the
client matches its expectations.
Paragraph (version A):
A 32-bit value indicating the ways in which this ticket may be
used (as an OR of the flags values).
Paragraph (version B):
A 32-bit value indicating the ways in which this ticket may be
used (as a bitwise OR of the flags values).
Paragraph (version A):
Note that the side which sends its KeyUpdate first needs to retain
the traffic keys (though not the traffic secret) for the previous
generation of keys until it receives the KeyUpdate from the other
side.
Paragraph (version B):
Note that the side which sends its KeyUpdate first needs to retain
its receive traffic keys (though not the traffic secret) for the
previous generation of keys until it receives the KeyUpdate from the
other side.
Paragraph (version A):
Selecting a padding policy that suggests when and how much to pad is
a complex topic, and is beyond the scope of this specification.  If
the application layer protocol atop TLS permits padding, it may be
preferable to pad application_data TLS records within the application
layer.  Padding for encrypted handshake and alert TLS records must
still be handled at the TLS layer, though.  Later documents may
define padding selection algorithms, or define a padding policy
request mechanism through TLS extensions or some other means.
Paragraph (version B):
Selecting a padding policy that suggests when and how much to pad is
a complex topic, and is beyond the scope of this specification.  If
the application layer protocol atop TLS has its own padding padding,
it may be preferable to pad application_data TLS records within the
application layer.  Padding for encrypted handshake and alert TLS
records must still be handled at the TLS layer, though.  Later
documents may define padding selection algorithms, or define a
padding policy request mechanism through TLS extensions or some other
means.
Paragraph (version A):
One of the content types supported by the TLS record layer is the
alert type.  Alert messages convey the severity of the message
(warning or fatal) and a description of the alert.  Alert messages
with a level of fatal result in the immediate termination of the
connection.  In this case, other connections corresponding to the
session may continue, but the session identifier MUST be invalidated,
preventing the failed session from being used to establish new
connections.  Like other messages, alert messages are encrypted as
specified by the current connection state.
Paragraph (version B):
One of the content types supported by the TLS record layer is the
alert type.  Alert messages convey the severity of the message
(warning or fatal) and a description of the alert.  Alert messages
with a level of fatal result in the immediate termination of the
connection.  Like other messages, alert messages are encrypted as
specified by the current connection state.
Paragraph (version A):
Error handling in the TLS Handshake Protocol is very simple.  When an
error is detected, the detecting party sends a message to its peer.
Upon transmission or receipt of a fatal alert message, both parties
immediately close the connection.  Servers and clients MUST forget
keys, and secrets associated with a failed connection.  Stateful
implementations of session tickets (as in many clients) SHOULD
discard tickets associated with failed connections.
Paragraph (version B):
Error handling in TLS is very simple.  When an error is detected, the
detecting party sends a message to its peer.  Upon transmission or
receipt of a fatal alert message, both parties immediately close the
connection.  Servers and clients MUST forget keys, and secrets
associated with a failed connection.  Stateful implementations of
session tickets (as in many clients) SHOULD discard tickets
associated with failed connections.
Paragraph (version A):
If a given secret is not available, then the 0-value consisting of a
string of L zeroes is used.  Note that this does not mean skipping
rounds, so if PSK is not in use Early Secret will still be HKDF-
Extract(0, 0).
Paragraph (version B):
If a given secret is not available, then the 0-value consisting of a
string of Hash.length zeroes is used.  Note that this does not mean
skipping rounds, so if PSK is not in use Early Secret will still be
HKDF-Extract(0, 0).