target = "https://tools.ietf.org/rfc/rfc8446#section-4.1.2"

# 4.1.2.  Client Hello
#
# When a client first connects to a server, it is REQUIRED to send the
# ClientHello as its first TLS message.  The client will also send a
# ClientHello when the server has responded to its ClientHello with a
# HelloRetryRequest.  In that case, the client MUST send the same
# ClientHello without modification, except as follows:
# 
# -  If a "key_share" extension was supplied in the HelloRetryRequest,
#    replacing the list of shares with a list containing a single
#    KeyShareEntry from the indicated group.
# 
# -  Removing the "early_data" extension (Section 4.2.10) if one was
#    present.  Early data is not permitted after a HelloRetryRequest.
# 
# -  Including a "cookie" extension if one was provided in the
#    HelloRetryRequest.
# 
# -  Updating the "pre_shared_key" extension if present by recomputing
#    the "obfuscated_ticket_age" and binder values and (optionally)
#    removing any PSKs which are incompatible with the server's
#    indicated cipher suite.
# 
# -  Optionally adding, removing, or changing the length of the
#    "padding" extension [RFC7685].
# 
# -  Other modifications that may be allowed by an extension defined in
#    the future and present in the HelloRetryRequest.
# 
# Because TLS 1.3 forbids renegotiation, if a server has negotiated
# TLS 1.3 and receives a ClientHello at any other time, it MUST
# terminate the connection with an "unexpected_message" alert.
# 
# If a server established a TLS connection with a previous version of
# TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST
# retain the previous protocol version.  In particular, it MUST NOT
# negotiate TLS 1.3.
# 
# Structure of this message:
# 
#    uint16 ProtocolVersion;
#    opaque Random[32];
# 
#    uint8 CipherSuite[2];    /* Cryptographic suite selector */
# 
#    struct {
#        ProtocolVersion legacy_version = 0x0303;    /* TLS v1.2 */
#        Random random;
#        opaque legacy_session_id<0..32>;
#        CipherSuite cipher_suites<2..2^16-2>;
#        opaque legacy_compression_methods<1..2^8-1>;
#        Extension extensions<8..2^16-1>;
#    } ClientHello;
# 
# legacy_version:  In previous versions of TLS, this field was used for
#    version negotiation and represented the highest version number
#    supported by the client.  Experience has shown that many servers
#    do not properly implement version negotiation, leading to "version
#    intolerance" in which the server rejects an otherwise acceptable
#    ClientHello with a version number higher than it supports.  In
#    TLS 1.3, the client indicates its version preferences in the
#    "supported_versions" extension (Section 4.2.1) and the
#    legacy_version field MUST be set to 0x0303, which is the version
#    number for TLS 1.2.  TLS 1.3 ClientHellos are identified as having
#    a legacy_version of 0x0303 and a supported_versions extension
#    present with 0x0304 as the highest version indicated therein.
#    (See Appendix D for details about backward compatibility.)
# 
# random:  32 bytes generated by a secure random number generator.  See
#    Appendix C for additional information.
# 
# legacy_session_id:  Versions of TLS before TLS 1.3 supported a
#    "session resumption" feature which has been merged with pre-shared
#    keys in this version (see Section 2.2).  A client which has a
#    cached session ID set by a pre-TLS 1.3 server SHOULD set this
#    field to that value.  In compatibility mode (see Appendix D.4),
#    this field MUST be non-empty, so a client not offering a
#    pre-TLS 1.3 session MUST generate a new 32-byte value.  This value
#    need not be random but SHOULD be unpredictable to avoid
#    implementations fixating on a specific value (also known as
#    ossification).  Otherwise, it MUST be set as a zero-length vector
#    (i.e., a zero-valued single byte length field).
# 
# cipher_suites:  A list of the symmetric cipher options supported by
#    the client, specifically the record protection algorithm
#    (including secret key length) and a hash to be used with HKDF, in
#    descending order of client preference.  Values are defined in
#    Appendix B.4.  If the list contains cipher suites that the server
#    does not recognize, support, or wish to use, the server MUST
#    ignore those cipher suites and process the remaining ones as
#    usual.  If the client is attempting a PSK key establishment, it
#    SHOULD advertise at least one cipher suite indicating a Hash
#    associated with the PSK.
# 
# legacy_compression_methods:  Versions of TLS before 1.3 supported
#    compression with the list of supported compression methods being
#    sent in this field.  For every TLS 1.3 ClientHello, this vector
#    MUST contain exactly one byte, set to zero, which corresponds to
#    the "null" compression method in prior versions of TLS.  If a
#    TLS 1.3 ClientHello is received with any other value in this
#    field, the server MUST abort the handshake with an
#    "illegal_parameter" alert.  Note that TLS 1.3 servers might
#    receive TLS 1.2 or prior ClientHellos which contain other
#    compression methods and (if negotiating such a prior version) MUST
#    follow the procedures for the appropriate prior version of TLS.
# 
# extensions:  Clients request extended functionality from servers by
#    sending data in the extensions field.  The actual "Extension"
#    format is defined in Section 4.2.  In TLS 1.3, the use of certain
#    extensions is mandatory, as functionality has moved into
#    extensions to preserve ClientHello compatibility with previous
#    versions of TLS.  Servers MUST ignore unrecognized extensions.
# 
# All versions of TLS allow an extensions field to optionally follow
# the compression_methods field.  TLS 1.3 ClientHello messages always
# contain extensions (minimally "supported_versions", otherwise, they
# will be interpreted as TLS 1.2 ClientHello messages).  However,
# TLS 1.3 servers might receive ClientHello messages without an
# extensions field from prior versions of TLS.  The presence of
# extensions can be detected by determining whether there are bytes
# following the compression_methods field at the end of the
# ClientHello.  Note that this method of detecting optional data
# differs from the normal TLS method of having a variable-length field,
# but it is used for compatibility with TLS before extensions were
# defined.  TLS 1.3 servers will need to perform this check first and
# only attempt to negotiate TLS 1.3 if the "supported_versions"
# extension is present.  If negotiating a version of TLS prior to 1.3,
# a server MUST check that the message either contains no data after
# legacy_compression_methods or that it contains a valid extensions
# block with no data following.  If not, then it MUST abort the
# handshake with a "decode_error" alert.
# 
# In the event that a client requests additional functionality using
# extensions and this functionality is not supplied by the server, the
# client MAY abort the handshake.
# 
# After sending the ClientHello message, the client waits for a
# ServerHello or HelloRetryRequest message.  If early data is in use,
# the client may transmit early Application Data (Section 2.3) while
# waiting for the next handshake message.

[[spec]]
level = "MUST"
quote = '''
When a client first connects to a server, it is REQUIRED to send the
ClientHello as its first TLS message.
'''

[[spec]]
level = "MUST"
quote = '''
In that case, the client MUST send the same
ClientHello without modification, except as follows:
'''

[[spec]]
level = "MUST"
quote = '''
Because TLS 1.3 forbids renegotiation, if a server has negotiated
TLS 1.3 and receives a ClientHello at any other time, it MUST
terminate the connection with an "unexpected_message" alert.
'''

[[spec]]
level = "MUST"
quote = '''
If a server established a TLS connection with a previous version of
TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST
retain the previous protocol version.
'''

[[spec]]
level = "MUST"
quote = '''
In particular, it MUST NOT
negotiate TLS 1.3.
'''

[[spec]]
level = "MUST"
quote = '''
In
TLS 1.3, the client indicates its version preferences in the
"supported_versions" extension (Section 4.2.1) and the
legacy_version field MUST be set to 0x0303, which is the version
number for TLS 1.2.
'''

[[spec]]
level = "SHOULD"
quote = '''
A client which has a
cached session ID set by a pre-TLS 1.3 server SHOULD set this
field to that value.
'''

[[spec]]
level = "MUST"
quote = '''
In compatibility mode (see Appendix D.4),
this field MUST be non-empty, so a client not offering a
pre-TLS 1.3 session MUST generate a new 32-byte value.
'''

[[spec]]
level = "MUST"
quote = '''
In compatibility mode (see Appendix D.4),
this field MUST be non-empty, so a client not offering a
pre-TLS 1.3 session MUST generate a new 32-byte value.
'''

[[spec]]
level = "SHOULD"
quote = '''
This value
need not be random but SHOULD be unpredictable to avoid
implementations fixating on a specific value (also known as
ossification).
'''

[[spec]]
level = "MUST"
quote = '''
Otherwise, it MUST be set as a zero-length vector
(i.e., a zero-valued single byte length field).
'''

[[spec]]
level = "MUST"
quote = '''
If the list contains cipher suites that the server
does not recognize, support, or wish to use, the server MUST
ignore those cipher suites and process the remaining ones as
usual.
'''

[[spec]]
level = "SHOULD"
quote = '''
If the client is attempting a PSK key establishment, it
SHOULD advertise at least one cipher suite indicating a Hash
associated with the PSK.
'''

[[spec]]
level = "MUST"
quote = '''
For every TLS 1.3 ClientHello, this vector
MUST contain exactly one byte, set to zero, which corresponds to
the "null" compression method in prior versions of TLS.
'''

[[spec]]
level = "MUST"
quote = '''
If a
TLS 1.3 ClientHello is received with any other value in this
field, the server MUST abort the handshake with an
"illegal_parameter" alert.
'''

[[spec]]
level = "MUST"
quote = '''
Note that TLS 1.3 servers might
receive TLS 1.2 or prior ClientHellos which contain other
compression methods and (if negotiating such a prior version) MUST
follow the procedures for the appropriate prior version of TLS.
'''

[[spec]]
level = "MUST"
quote = '''
Servers MUST ignore unrecognized extensions.
'''

[[spec]]
level = "MUST"
quote = '''
If negotiating a version of TLS prior to 1.3,
a server MUST check that the message either contains no data after
legacy_compression_methods or that it contains a valid extensions
block with no data following.
'''

[[spec]]
level = "MUST"
quote = '''
If not, then it MUST abort the
handshake with a "decode_error" alert.
'''

[[spec]]
level = "MAY"
quote = '''
In the event that a client requests additional functionality using
extensions and this functionality is not supplied by the server, the
client MAY abort the handshake.
'''

