draft-ietf-tls-tls13-28.txt   rfc8446.txt 
Network Working Group E. Rescorla Internet Engineering Task Force (IETF) E. Rescorla
Internet-Draft RTFM, Inc. Request for Comments: 8446 Mozilla
Obsoletes: 5077, 5246, 6961 (if March 20, 2018 Obsoletes: 5077, 5246, 6961 August 2018
approved) Updates: 5705, 6066
Updates: 4492, 5705, 6066 (if approved) Category: Standards Track
Intended status: Standards Track ISSN: 2070-1721
Expires: September 21, 2018
The Transport Layer Security (TLS) Protocol Version 1.3 The Transport Layer Security (TLS) Protocol Version 1.3
draft-ietf-tls-tls13-28
Abstract Abstract
This document specifies version 1.3 of the Transport Layer Security This document specifies version 1.3 of the Transport Layer Security
(TLS) protocol. TLS allows client/server applications to communicate (TLS) protocol. TLS allows client/server applications to communicate
over the Internet in a way that is designed to prevent eavesdropping, over the Internet in a way that is designed to prevent eavesdropping,
tampering, and message forgery. tampering, and message forgery.
This document updates RFCs 4492, 5705, and 6066 and it obsoletes RFCs This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077,
5077, 5246, and 6961. This document also specifies new requirements 5246, and 6961. This document also specifies new requirements for
for TLS 1.2 implementations. TLS 1.2 implementations.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on September 21, 2018. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc8446.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this 10, 2008. The person(s) controlling the copyright in some of this
skipping to change at page 2, line 25 skipping to change at page 3, line 7
modifications of such material outside the IETF Standards Process. modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction ....................................................6
1.1. Conventions and Terminology . . . . . . . . . . . . . . . 6 1.1. Conventions and Terminology ................................7
1.2. Change Log . . . . . . . . . . . . . . . . . . . . . . . 7 1.2. Major Differences from TLS 1.2 .............................8
1.3. Major Differences from TLS 1.2 . . . . . . . . . . . . . 16 1.3. Updates Affecting TLS 1.2 ..................................9
1.4. Updates Affecting TLS 1.2 . . . . . . . . . . . . . . . . 17 2. Protocol Overview ..............................................10
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 18 2.1. Incorrect DHE Share .......................................14
2.1. Incorrect DHE Share . . . . . . . . . . . . . . . . . . . 21 2.2. Resumption and Pre-Shared Key (PSK) .......................15
2.2. Resumption and Pre-Shared Key (PSK) . . . . . . . . . . . 22 2.3. 0-RTT Data ................................................17
2.3. 0-RTT Data . . . . . . . . . . . . . . . . . . . . . . . 24 3. Presentation Language ..........................................19
3. Presentation Language . . . . . . . . . . . . . . . . . . . . 26 3.1. Basic Block Size ..........................................19
3.1. Basic Block Size . . . . . . . . . . . . . . . . . . . . 26 3.2. Miscellaneous .............................................20
3.2. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . 26 3.3. Numbers ...................................................20
3.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.4. Vectors ...................................................20
3.4. Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.5. Enumerateds ...............................................21
3.5. Enumerateds . . . . . . . . . . . . . . . . . . . . . . . 28 3.6. Constructed Types .........................................22
3.6. Constructed Types . . . . . . . . . . . . . . . . . . . . 29 3.7. Constants .................................................23
3.7. Constants . . . . . . . . . . . . . . . . . . . . . . . . 29 3.8. Variants ..................................................23
3.8. Variants . . . . . . . . . . . . . . . . . . . . . . . . 30 4. Handshake Protocol .............................................24
4. Handshake Protocol . . . . . . . . . . . . . . . . . . . . . 31 4.1. Key Exchange Messages .....................................25
4.1. Key Exchange Messages . . . . . . . . . . . . . . . . . . 32 4.1.1. Cryptographic Negotiation ..........................26
4.1.1. Cryptographic Negotiation . . . . . . . . . . . . . . 32 4.1.2. Client Hello .......................................27
4.1.2. Client Hello . . . . . . . . . . . . . . . . . . . . 33 4.1.3. Server Hello .......................................31
4.1.3. Server Hello . . . . . . . . . . . . . . . . . . . . 36 4.1.4. Hello Retry Request ................................33
4.1.4. Hello Retry Request . . . . . . . . . . . . . . . . . 38 4.2. Extensions ................................................35
4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . 40 4.2.1. Supported Versions .................................39
4.2.1. Supported Versions . . . . . . . . . . . . . . . . . 43 4.2.2. Cookie .............................................40
4.2.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 45 4.2.3. Signature Algorithms ...............................41
4.2.3. Signature Algorithms . . . . . . . . . . . . . . . . 46 4.2.4. Certificate Authorities ............................45
4.2.4. Certificate Authorities . . . . . . . . . . . . . . . 50 4.2.5. OID Filters ........................................45
4.2.5. OID Filters . . . . . . . . . . . . . . . . . . . . . 50 4.2.6. Post-Handshake Client Authentication ...............47
4.2.6. Post-Handshake Client Authentication . . . . . . . . 51 4.2.7. Supported Groups ...................................47
4.2.7. Negotiated Groups . . . . . . . . . . . . . . . . . . 52 4.2.8. Key Share ..........................................48
4.2.8. Key Share . . . . . . . . . . . . . . . . . . . . . . 53 4.2.9. Pre-Shared Key Exchange Modes ......................51
4.2.9. Pre-Shared Key Exchange Modes . . . . . . . . . . . . 56 4.2.10. Early Data Indication .............................52
4.2.10. Early Data Indication . . . . . . . . . . . . . . . . 57 4.2.11. Pre-Shared Key Extension ..........................55
4.2.11. Pre-Shared Key Extension . . . . . . . . . . . . . . 60 4.3. Server Parameters .........................................59
4.3. Server Parameters . . . . . . . . . . . . . . . . . . . . 63 4.3.1. Encrypted Extensions ...............................60
4.3.1. Encrypted Extensions . . . . . . . . . . . . . . . . 63 4.3.2. Certificate Request ................................60
4.3.2. Certificate Request . . . . . . . . . . . . . . . . . 64 4.4. Authentication Messages ...................................61
4.4. Authentication Messages . . . . . . . . . . . . . . . . . 65 4.4.1. The Transcript Hash ................................63
4.4.1. The Transcript Hash . . . . . . . . . . . . . . . . . 66 4.4.2. Certificate ........................................64
4.4.2. Certificate . . . . . . . . . . . . . . . . . . . . . 67 4.4.3. Certificate Verify .................................69
4.4.3. Certificate Verify . . . . . . . . . . . . . . . . . 72 4.4.4. Finished ...........................................71
4.4.4. Finished . . . . . . . . . . . . . . . . . . . . . . 74 4.5. End of Early Data .........................................72
4.5. End of Early Data . . . . . . . . . . . . . . . . . . . . 75 4.6. Post-Handshake Messages ...................................73
4.6. Post-Handshake Messages . . . . . . . . . . . . . . . . . 76 4.6.1. New Session Ticket Message .........................73
4.6.1. New Session Ticket Message . . . . . . . . . . . . . 76 4.6.2. Post-Handshake Authentication ......................75
4.6.2. Post-Handshake Authentication . . . . . . . . . . . . 78 4.6.3. Key and Initialization Vector Update ...............76
4.6.3. Key and IV Update . . . . . . . . . . . . . . . . . . 79 5. Record Protocol ................................................77
5. Record Protocol . . . . . . . . . . . . . . . . . . . . . . . 80 5.1. Record Layer ..............................................78
5.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 81 5.2. Record Payload Protection .................................80
5.2. Record Payload Protection . . . . . . . . . . . . . . . . 83 5.3. Per-Record Nonce ..........................................82
5.3. Per-Record Nonce . . . . . . . . . . . . . . . . . . . . 85 5.4. Record Padding ............................................83
5.4. Record Padding . . . . . . . . . . . . . . . . . . . . . 86 5.5. Limits on Key Usage .......................................84
5.5. Limits on Key Usage . . . . . . . . . . . . . . . . . . . 87 6. Alert Protocol .................................................85
6. Alert Protocol . . . . . . . . . . . . . . . . . . . . . . . 87 6.1. Closure Alerts ............................................87
6.1. Closure Alerts . . . . . . . . . . . . . . . . . . . . . 89 6.2. Error Alerts ..............................................88
6.2. Error Alerts . . . . . . . . . . . . . . . . . . . . . . 90 7. Cryptographic Computations .....................................90
7. Cryptographic Computations . . . . . . . . . . . . . . . . . 93 7.1. Key Schedule ..............................................91
7.1. Key Schedule . . . . . . . . . . . . . . . . . . . . . . 93 7.2. Updating Traffic Secrets ..................................94
7.2. Updating Traffic Secrets . . . . . . . . . . . . . . . . 96 7.3. Traffic Key Calculation ...................................95
7.3. Traffic Key Calculation . . . . . . . . . . . . . . . . . 97 7.4. (EC)DHE Shared Secret Calculation .........................95
7.4. (EC)DHE Shared Secret Calculation . . . . . . . . . . . . 98 7.4.1. Finite Field Diffie-Hellman ........................95
7.4.1. Finite Field Diffie-Hellman . . . . . . . . . . . . . 98 7.4.2. Elliptic Curve Diffie-Hellman ......................96
7.4.2. Elliptic Curve Diffie-Hellman . . . . . . . . . . . . 98 7.5. Exporters .................................................97
7.5. Exporters . . . . . . . . . . . . . . . . . . . . . . . . 99 8. 0-RTT and Anti-Replay ..........................................98
8. 0-RTT and Anti-Replay . . . . . . . . . . . . . . . . . . . . 99 8.1. Single-Use Tickets ........................................99
8.1. Single-Use Tickets . . . . . . . . . . . . . . . . . . . 101 8.2. Client Hello Recording ....................................99
8.2. Client Hello Recording . . . . . . . . . . . . . . . . . 101 8.3. Freshness Checks .........................................101
8.3. Freshness Checks . . . . . . . . . . . . . . . . . . . . 102 9. Compliance Requirements .......................................102
9. Compliance Requirements . . . . . . . . . . . . . . . . . . . 104 9.1. Mandatory-to-Implement Cipher Suites .....................102
9.1. Mandatory-to-Implement Cipher Suites . . . . . . . . . . 104 9.2. Mandatory-to-Implement Extensions ........................103
9.2. Mandatory-to-Implement Extensions . . . . . . . . . . . . 104 9.3. Protocol Invariants ......................................104
9.3. Protocol Invariants . . . . . . . . . . . . . . . . . . . 105 10. Security Considerations ......................................106
10. Security Considerations . . . . . . . . . . . . . . . . . . . 106 11. IANA Considerations ..........................................106
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 107 12. References ...................................................109
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 108 12.1. Normative References ....................................109
12.1. Normative References . . . . . . . . . . . . . . . . . . 108 12.2. Informative References ..................................112
12.2. Informative References . . . . . . . . . . . . . . . . . 111 Appendix A. State Machine ........................................120
Appendix A. State Machine . . . . . . . . . . . . . . . . . . . 119 A.1. Client ....................................................120
A.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 119 A.2. Server ....................................................121
A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 120 Appendix B. Protocol Data Structures and Constant Values .........122
Appendix B. Protocol Data Structures and Constant Values . . . . 120 B.1. Record Layer ..............................................122
B.1. Record Layer . . . . . . . . . . . . . . . . . . . . . . 121 B.2. Alert Messages ............................................123
B.2. Alert Messages . . . . . . . . . . . . . . . . . . . . . 121 B.3. Handshake Protocol ........................................124
B.3. Handshake Protocol . . . . . . . . . . . . . . . . . . . 123 B.3.1. Key Exchange Messages .................................125
B.3.1. Key Exchange Messages . . . . . . . . . . . . . . . . 123 B.3.2. Server Parameters Messages ............................131
B.3.2. Server Parameters Messages . . . . . . . . . . . . . 128 B.3.3. Authentication Messages ...............................132
B.3.3. Authentication Messages . . . . . . . . . . . . . . . 129 B.3.4. Ticket Establishment ..................................132
B.3.4. Ticket Establishment . . . . . . . . . . . . . . . . 130 B.3.5. Updating Keys .........................................133
B.3.5. Updating Keys . . . . . . . . . . . . . . . . . . . . 131 B.4. Cipher Suites .............................................133
B.4. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . 131
Appendix C. Implementation Notes . . . . . . . . . . . . . . . . 132
C.1. Random Number Generation and Seeding . . . . . . . . . . 132
C.2. Certificates and Authentication . . . . . . . . . . . . . 133
C.3. Implementation Pitfalls . . . . . . . . . . . . . . . . . 133
C.4. Client Tracking Prevention . . . . . . . . . . . . . . . 134
C.5. Unauthenticated Operation . . . . . . . . . . . . . . . . 135
Appendix D. Backward Compatibility . . . . . . . . . . . . . . . 135
D.1. Negotiating with an older server . . . . . . . . . . . . 136
D.2. Negotiating with an older client . . . . . . . . . . . . 137
D.3. 0-RTT backwards compatibility . . . . . . . . . . . . . . 137
D.4. Middlebox Compatibility Mode . . . . . . . . . . . . . . 137
D.5. Backwards Compatibility Security Restrictions . . . . . . 138
Appendix E. Overview of Security Properties . . . . . . . . . . 139
E.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 139
E.1.1. Key Derivation and HKDF . . . . . . . . . . . . . . . 142
E.1.2. Client Authentication . . . . . . . . . . . . . . . . 143
E.1.3. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 143
E.1.4. Exporter Independence . . . . . . . . . . . . . . . . 143
E.1.5. Post-Compromise Security . . . . . . . . . . . . . . 144
E.1.6. External References . . . . . . . . . . . . . . . . . 144
E.2. Record Layer . . . . . . . . . . . . . . . . . . . . . . 144
E.2.1. External References . . . . . . . . . . . . . . . . . 145
E.3. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 145
E.4. Side Channel Attacks . . . . . . . . . . . . . . . . . . 146
E.5. Replay Attacks on 0-RTT . . . . . . . . . . . . . . . . . 147
E.5.1. Replay and Exporters . . . . . . . . . . . . . . . . 148
E.6. PSK Identity Exposure . . . . . . . . . . . . . . . . . . 149
E.7. Attacks on Static RSA . . . . . . . . . . . . . . . . . . 149
Appendix F. Working Group Information . . . . . . . . . . . . . 149
Appendix G. Contributors . . . . . . . . . . . . . . . . . . . . 149
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 156
1. Introduction Appendix C. Implementation Notes .................................134
C.1. Random Number Generation and Seeding ......................134
C.2. Certificates and Authentication ...........................135
C.3. Implementation Pitfalls ...................................135
C.4. Client Tracking Prevention ................................137
C.5. Unauthenticated Operation .................................137
Appendix D. Backward Compatibility ...............................138
D.1. Negotiating with an Older Server ..........................139
D.2. Negotiating with an Older Client ..........................139
D.3. 0-RTT Backward Compatibility ..............................140
D.4. Middlebox Compatibility Mode ..............................140
D.5. Security Restrictions Related to Backward Compatibility ...141
Appendix E. Overview of Security Properties ......................142
E.1. Handshake .................................................142
E.1.1. Key Derivation and HKDF ...............................145
E.1.2. Client Authentication .................................146
E.1.3. 0-RTT .................................................146
E.1.4. Exporter Independence .................................146
E.1.5. Post-Compromise Security ..............................146
E.1.6. External References ...................................147
E.2. Record Layer ..............................................147
E.2.1. External References ...................................148
E.3. Traffic Analysis ..........................................148
E.4. Side-Channel Attacks ......................................149
E.5. Replay Attacks on 0-RTT ...................................150
E.5.1. Replay and Exporters ..................................151
E.6. PSK Identity Exposure .....................................152
E.7. Sharing PSKs ..............................................152
E.8. Attacks on Static RSA .....................................152
Contributors .....................................................153
Author's Address .................................................160
RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH The source for this 1. Introduction
draft is maintained in GitHub. Suggested changes should be submitted
as pull requests at https://github.com/tlswg/tls13-spec.
Instructions are on that page as well. Editorial changes can be
managed in GitHub, but any substantive change should be discussed on
the TLS mailing list.
The primary goal of TLS is to provide a secure channel between two The primary goal of TLS is to provide a secure channel between two
communicating peers; the only requirement from the underlying communicating peers; the only requirement from the underlying
transport is a reliable, in-order, data stream. Specifically, the transport is a reliable, in-order data stream. Specifically, the
secure channel should provide the following properties: secure channel should provide the following properties:
- Authentication: The server side of the channel is always - Authentication: The server side of the channel is always
authenticated; the client side is optionally authenticated. authenticated; the client side is optionally authenticated.
Authentication can happen via asymmetric cryptography (e.g., RSA Authentication can happen via asymmetric cryptography (e.g., RSA
[RSA], ECDSA [ECDSA], EdDSA [RFC8032]) or a pre-shared key (PSK). [RSA], the Elliptic Curve Digital Signature Algorithm (ECDSA)
[ECDSA], or the Edwards-Curve Digital Signature Algorithm (EdDSA)
[RFC8032]) or a symmetric pre-shared key (PSK).
- Confidentiality: Data sent over the channel after establishment is - Confidentiality: Data sent over the channel after establishment is
only visible to the endpoints. TLS does not hide the length of only visible to the endpoints. TLS does not hide the length of
the data it transmits, though endpoints are able to pad TLS the data it transmits, though endpoints are able to pad TLS
records in order to obscure lengths and improve protection against records in order to obscure lengths and improve protection against
traffic analysis techniques. traffic analysis techniques.
- Integrity: Data sent over the channel after establishment cannot - Integrity: Data sent over the channel after establishment cannot
be modified by attackers. be modified by attackers without detection.
These properties should be true even in the face of an attacker who These properties should be true even in the face of an attacker who
has complete control of the network, as described in [RFC3552]. See has complete control of the network, as described in [RFC3552]. See
Appendix E for a more complete statement of the relevant security Appendix E for a more complete statement of the relevant security
properties. properties.
TLS consists of two primary components: TLS consists of two primary components:
- A handshake protocol (Section 4) that authenticates the - A handshake protocol (Section 4) that authenticates the
communicating parties, negotiates cryptographic modes and communicating parties, negotiates cryptographic modes and
skipping to change at page 6, line 18 skipping to change at page 7, line 18
handshaking and how to interpret the authentication certificates handshaking and how to interpret the authentication certificates
exchanged are left to the judgment of the designers and implementors exchanged are left to the judgment of the designers and implementors
of protocols that run on top of TLS. of protocols that run on top of TLS.
This document defines TLS version 1.3. While TLS 1.3 is not directly This document defines TLS version 1.3. While TLS 1.3 is not directly
compatible with previous versions, all versions of TLS incorporate a compatible with previous versions, all versions of TLS incorporate a
versioning mechanism which allows clients and servers to versioning mechanism which allows clients and servers to
interoperably negotiate a common version if one is supported by both interoperably negotiate a common version if one is supported by both
peers. peers.
This document supersedes and obsoletes previous versions of TLS This document supersedes and obsoletes previous versions of TLS,
including version 1.2 [RFC5246]. It also obsoletes the TLS ticket including version 1.2 [RFC5246]. It also obsoletes the TLS ticket
mechanism defined in [RFC5077] and replaces it with the mechanism mechanism defined in [RFC5077] and replaces it with the mechanism
defined in Section 2.2. Section 4.2.7 updates [RFC4492] by modifying defined in Section 2.2. Because TLS 1.3 changes the way keys are
the protocol attributes used to negotiate Elliptic Curves. Because derived, it updates [RFC5705] as described in Section 7.5. It also
TLS 1.3 changes the way keys are derived, it updates [RFC5705] as changes how Online Certificate Status Protocol (OCSP) messages are
described in Section 7.5. It also changes how OCSP messages are
carried and therefore updates [RFC6066] and obsoletes [RFC6961] as carried and therefore updates [RFC6066] and obsoletes [RFC6961] as
described in section Section 4.4.2.1. described in Section 4.4.2.1.
1.1. Conventions and Terminology 1.1. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The following terms are used: The following terms are used:
client: The endpoint initiating the TLS connection. client: The endpoint initiating the TLS connection.
connection: A transport-layer connection between two endpoints.
endpoint: Either the client or server of the connection.
handshake: An initial negotiation between client and server that
establishes the parameters of their subsequent interactions within
TLS.
peer: An endpoint. When discussing a particular endpoint, "peer"
refers to the endpoint that is not the primary subject of discussion.
receiver: An endpoint that is receiving records.
sender: An endpoint that is transmitting records.
server: The endpoint which did not initiate the TLS connection.
1.2. Change Log
RFC EDITOR PLEASE DELETE THIS SECTION.
(*) indicates changes to the wire protocol which may require
implementations to update.
draft-28
Add a section on exposure of PSK identities.
draft-27
- SHOULD->MUST for being able to process "supported_versions"
without 0x0304.
- Much editorial cleanup.
draft-26
- Clarify that you can't negotiate pre-TLS 1.3 with
supported_versions.
draft-25
- Add the header to additional data (*)
- Minor clarifications.
- IANA cleanup.
draft-24
- Require that CH2 have version 0303 (*)
- Some clarifications
draft-23
- Renumber key_share (*)
- Add a new extension and new code points to allow negotiating PSS
separately for certificates and CertificateVerify (*)
- Slightly restrict when CCS must be accepted to make implementation
easier.
- Document protocol invariants
- Add some text on the security of static RSA.
draft-22
- Implement changes for improved middlebox penetration (*)
- Move server_certificate_type to encrypted extensions (*)
- Allow resumption with a different SNI (*)
- Padding extension can change on HRR (*)
- Allow an empty ticket_nonce (*)
- Remove requirement to immediately respond to close_notify with
close_notify (allowing half-close)
draft-21
- Add a per-ticket nonce so that each ticket is associated with a
different PSK (*).
- Clarify that clients should send alerts with the handshake key if
possible.
- Update state machine to show rekeying events
- Add discussion of 0-RTT and replay. Recommend that
implementations implement some anti-replay mechanism.
draft-20
- Add "post_handshake_auth" extension to negotiate post-handshake
authentication (*).
- Shorten labels for HKDF-Expand-Label so that we can fit within one
compression block (*).
- Define how RFC 7250 works (*).
- Re-enable post-handshake client authentication even when you do
PSK. The previous prohibition was editorial error.
- Remove cert_type and user_mapping, which don't work on TLS 1.3
anyway.
- Added the no_application_protocol alert from [RFC7301] to the list
of extensions.
- Added discussion of traffic analysis and side channel attacks.
draft-19
- Hash context_value input to Exporters (*)
- Add an additional Derive-Secret stage to Exporters (*).
- Hash ClientHello1 in the transcript when HRR is used. This
reduces the state that needs to be carried in cookies. (*)
- Restructure CertificateRequest to have the selectors in
extensions. This also allowed defining a
"certificate_authorities" extension which can be used by the
client instead of trusted_ca_keys (*).
- Tighten record framing requirements and require checking of them
(*).
- Consolidate "ticket_early_data_info" and "early_data" into a
single extension (*).
- Change end_of_early_data to be a handshake message (*).
- Add pre-extract Derive-Secret stages to key schedule (*).
- Remove spurious requirement to implement "pre_shared_key".
- Clarify location of "early_data" from server (it goes in EE, as
indicated by the table in S 10).
- Require peer public key validation
- Add state machine diagram.
draft-18
- Remove unnecessary resumption_psk which is the only thing expanded
from the resumption master secret. (*).
- Fix signature_algorithms entry in extensions table.
- Restate rule from RFC 6066 that you can't resume unless SNI is the
same.
draft-17
- Remove 0-RTT Finished and resumption_context, and replace with a
psk_binder field in the PSK itself (*)
- Restructure PSK key exchange negotiation modes (*)
- Add max_early_data_size field to TicketEarlyDataInfo (*)
- Add a 0-RTT exporter and change the transcript for the regular
exporter (*)
- Merge TicketExtensions and Extensions registry. Changes
ticket_early_data_info code point (*)
- Replace Client.key_shares in response to HRR (*)
- Remove redundant labels for traffic key derivation (*)
- Harmonize requirements about cipher suite matching: for resumption
you need to match KDF but for 0-RTT you need whole cipher suite.
This allows PSKs to actually negotiate cipher suites. (*)
- Move SCT and OCSP into Certificate.extensions (*)
- Explicitly allow non-offered extensions in NewSessionTicket
- Explicitly allow predicting client Finished for NST
- Clarify conditions for allowing 0-RTT with PSK
draft-16
- Revise version negotiation (*)
- Change RSASSA-PSS and EdDSA SignatureScheme codepoints for better
backwards compatibility (*)
- Move HelloRetryRequest.selected_group to an extension (*)
- Clarify the behavior of no exporter context and make it the same
as an empty context.(*)
- New KeyUpdate format that allows for requesting/not-requesting an
answer. This also means changes to the key schedule to support
independent updates (*)
- New certificate_required alert (*)
- Forbid CertificateRequest with 0-RTT and PSK.
- Relax requirement to check SNI for 0-RTT.
draft-15
- New negotiation syntax as discussed in Berlin (*)
- Require CertificateRequest.context to be empty during handshake
(*)
- Forbid empty tickets (*)
- Forbid application data messages in between post-handshake
messages from the same flight (*)
- Clean up alert guidance (*)
- Clearer guidance on what is needed for TLS 1.2.
- Guidance on 0-RTT time windows.
- Rename a bunch of fields.
- Remove old PRNG text.
- Explicitly require checking that handshake records not span key
changes.
draft-14
- Allow cookies to be longer (*)
- Remove the "context" from EarlyDataIndication as it was undefined
and nobody used it (*)
- Remove 0-RTT EncryptedExtensions and replace the ticket_age
extension with an obfuscated version. Also necessitates a change
to NewSessionTicket (*).
- Move the downgrade sentinel to the end of ServerHello.Random to
accommodate tlsdate (*).
- Define ecdsa_sha1 (*).
- Allow resumption even after fatal alerts. This matches current
practice.
- Remove non-closure warning alerts. Require treating unknown
alerts as fatal.
- Make the rules for accepting 0-RTT less restrictive.
- Clarify 0-RTT backward-compatibility rules.
- Clarify how 0-RTT and PSK identities interact.
- Add a section describing the data limits for each cipher.
- Major editorial restructuring.
- Replace the Security Analysis section with a WIP draft.
draft-13
- Allow server to send SupportedGroups.
- Remove 0-RTT client authentication
- Remove (EC)DHE 0-RTT.
- Flesh out 0-RTT PSK mode and shrink EarlyDataIndication
- Turn PSK-resumption response into an index to save room
- Move CertificateStatus to an extension
- Extra fields in NewSessionTicket.
- Restructure key schedule and add a resumption_context value.
- Require DH public keys and secrets to be zero-padded to the size
of the group.
- Remove the redundant length fields in KeyShareEntry.
- Define a cookie field for HRR.
draft-12
- Provide a list of the PSK cipher suites.
- Remove the ability for the ServerHello to have no extensions (this
aligns the syntax with the text).
- Clarify that the server can send application data after its first
flight (0.5 RTT data)
- Revise signature algorithm negotiation to group hash, signature
algorithm, and curve together. This is backwards compatible.
- Make ticket lifetime mandatory and limit it to a week.
- Make the purpose strings lower-case. This matches how people are
implementing for interop.
- Define exporters.
- Editorial cleanup
draft-11
- Port the CFRG curves & signatures work from RFC4492bis.
- Remove sequence number and version from additional_data, which is
now empty.
- Reorder values in HkdfLabel.
- Add support for version anti-downgrade mechanism.
- Update IANA considerations section and relax some of the policies.
- Unify authentication modes. Add post-handshake client
authentication.
- Remove early_handshake content type. Terminate 0-RTT data with an
alert.
- Reset sequence number upon key change (as proposed by Fournet et
al.)
draft-10
- Remove ClientCertificateTypes field from CertificateRequest and
add extensions.
- Merge client and server key shares into a single extension.
draft-09
- Change to RSA-PSS signatures for handshake messages.
- Remove support for DSA.
- Update key schedule per suggestions by Hugo, Hoeteck, and Bjoern
Tackmann.
- Add support for per-record padding.
- Switch to encrypted record ContentType.
- Change HKDF labeling to include protocol version and value
lengths.
- Shift the final decision to abort a handshake due to incompatible
certificates to the client rather than having servers abort early.
- Deprecate SHA-1 with signatures.
- Add MTI algorithms.
draft-08
- Remove support for weak and lesser used named curves.
- Remove support for MD5 and SHA-224 hashes with signatures.
- Update lists of available AEAD cipher suites and error alerts.
- Reduce maximum permitted record expansion for AEAD from 2048 to
256 octets.
- Require digital signatures even when a previous configuration is
used.
- Merge EarlyDataIndication and KnownConfiguration.
- Change code point for server_configuration to avoid collision with
server_hello_done.
- Relax certificate_list ordering requirement to match current
practice.
draft-07
- Integration of semi-ephemeral DH proposal.
- Add initial 0-RTT support.
- Remove resumption and replace with PSK + tickets.
- Move ClientKeyShare into an extension.
- Move to HKDF.
draft-06
- Prohibit RC4 negotiation for backwards compatibility.
- Freeze & deprecate record layer version field.
- Update format of signatures with context.
- Remove explicit IV.
draft-05
- Prohibit SSL negotiation for backwards compatibility.
- Fix which MS is used for exporters.
draft-04
- Modify key computations to include session hash.
- Remove ChangeCipherSpec.
- Renumber the new handshake messages to be somewhat more consistent
with existing convention and to remove a duplicate registration.
- Remove renegotiation.
- Remove point format negotiation.
draft-03
- Remove GMT time.
- Merge in support for ECC from RFC 4492 but without explicit
curves.
- Remove the unnecessary length field from the AD input to AEAD
ciphers.
- Rename {Client,Server}KeyExchange to {Client,Server}KeyShare.
- Add an explicit HelloRetryRequest to reject the client's. connection: A transport-layer connection between two endpoints.
- Increment version number. endpoint: Either the client or server of the connection.
- Rework handshake to provide 1-RTT mode. handshake: An initial negotiation between client and server that
establishes the parameters of their subsequent interactions
within TLS.
- Remove custom DHE groups. peer: An endpoint. When discussing a particular endpoint, "peer"
refers to the endpoint that is not the primary subject of
discussion.
- Remove support for compression. receiver: An endpoint that is receiving records.
- Remove support for static RSA and DH key exchange. sender: An endpoint that is transmitting records.
- Remove support for non-AEAD ciphers. server: The endpoint that did not initiate the TLS connection.
1.3. Major Differences from TLS 1.2 1.2. Major Differences from TLS 1.2
The following is a list of the major functional differences between The following is a list of the major functional differences between
TLS 1.2 and TLS 1.3. It is not intended to be exhaustive and there TLS 1.2 and TLS 1.3. It is not intended to be exhaustive, and there
are many minor differences. are many minor differences.
- The list of supported symmetric algorithms has been pruned of all - The list of supported symmetric encryption algorithms has been
algorithms that are considered legacy. Those that remain all use pruned of all algorithms that are considered legacy. Those that
Authenticated Encryption with Associated Data (AEAD) algorithms. remain are all Authenticated Encryption with Associated Data
The ciphersuite concept has been changed to separate the (AEAD) algorithms. The cipher suite concept has been changed to
authentication and key exchange mechanisms from the record separate the authentication and key exchange mechanisms from the
protection algorithm (including secret key length) and a hash to record protection algorithm (including secret key length) and a
be used with the key derivation function and HMAC. hash to be used with both the key derivation function and
handshake message authentication code (MAC).
- A 0-RTT mode was added, saving a round-trip at connection setup - A zero round-trip time (0-RTT) mode was added, saving a round trip
for some application data, at the cost of certain security at connection setup for some application data, at the cost of
properties. certain security properties.
- Static RSA and Diffie-Hellman cipher suites have been removed; all - Static RSA and Diffie-Hellman cipher suites have been removed; all
public-key based key exchange mechanisms now provide forward public-key based key exchange mechanisms now provide forward
secrecy. secrecy.
- All handshake messages after the ServerHello are now encrypted. - All handshake messages after the ServerHello are now encrypted.
The newly introduced EncryptedExtension message allows various The newly introduced EncryptedExtensions message allows various
extensions previously sent in clear in the ServerHello to also extensions previously sent in the clear in the ServerHello to also
enjoy confidentiality protection from active attackers. enjoy confidentiality protection.
- The key derivation functions have been re-designed. The new - The key derivation functions have been redesigned. The new design
design allows easier analysis by cryptographers due to their allows easier analysis by cryptographers due to their improved key
improved key separation properties. The HMAC-based Extract-and- separation properties. The HMAC-based Extract-and-Expand Key
Expand Key Derivation Function (HKDF) is used as an underlying Derivation Function (HKDF) is used as an underlying primitive.
primitive.
- The handshake state machine has been significantly restructured to - The handshake state machine has been significantly restructured to
be more consistent and to remove superfluous messages such as be more consistent and to remove superfluous messages such as
ChangeCipherSpec (except when needed for middlebox compatibility). ChangeCipherSpec (except when needed for middlebox compatibility).
- Elliptic curve algorithms are now in the base spec and new - Elliptic curve algorithms are now in the base spec, and new
signature algorithms, such as ed25519 and ed448, are included. signature algorithms, such as EdDSA, are included. TLS 1.3
TLS 1.3 removed point format negotiation in favor of a single removed point format negotiation in favor of a single point format
point format for each curve. for each curve.
- Other cryptographic improvements including the removal of - Other cryptographic improvements were made, including changing the
compression and custom DHE groups, changing the RSA padding to use RSA padding to use the RSA Probabilistic Signature Scheme
RSASSA-PSS, and the removal of DSA. (RSASSA-PSS), and the removal of compression, the Digital
Signature Algorithm (DSA), and custom Ephemeral Diffie-Hellman
(DHE) groups.
- The TLS 1.2 version negotiation mechanism has been deprecated in - The TLS 1.2 version negotiation mechanism has been deprecated in
favor of a version list in an extension. This increases favor of a version list in an extension. This increases
compatibility with existing servers that incorrectly implemented compatibility with existing servers that incorrectly implemented
version negotiation. version negotiation.
- Session resumption with and without server-side state as well as - Session resumption with and without server-side state as well as
the PSK-based ciphersuites of earlier TLS versions have been the PSK-based cipher suites of earlier TLS versions have been
replaced by a single new PSK exchange. replaced by a single new PSK exchange.
- Updated references to point to the updated versions of RFCs, as - References have been updated to point to the updated versions of
appropriate (e.g., RFC 5280 rather than RFC 3280). RFCs, as appropriate (e.g., RFC 5280 rather than RFC 3280).
1.4. Updates Affecting TLS 1.2 1.3. Updates Affecting TLS 1.2
This document defines several changes that optionally affect This document defines several changes that optionally affect
implementations of TLS 1.2, including those which do not also support implementations of TLS 1.2, including those which do not also support
TLS 1.3: TLS 1.3:
- A version downgrade protection mechanism is described in - A version downgrade protection mechanism is described in
Section 4.1.3. Section 4.1.3.
- RSASSA-PSS signature schemes are defined in Section 4.2.3. - RSASSA-PSS signature schemes are defined in Section 4.2.3.
- The "supported_versions" ClientHello extension can be used to - The "supported_versions" ClientHello extension can be used to
negotiate the version of TLS to use, in preference to the negotiate the version of TLS to use, in preference to the
legacy_version field of the ClientHello. legacy_version field of the ClientHello.
- The "signature_algorithms_cert" extension allows a client to - The "signature_algorithms_cert" extension allows a client to
indicate which signature algorithms it can validate in X.509 indicate which signature algorithms it can validate in X.509
certificates certificates.
Additionally, this document clarifies some compliance requirements Additionally, this document clarifies some compliance requirements
for earlier versions of TLS; see Section 9.3. for earlier versions of TLS; see Section 9.3.
2. Protocol Overview 2. Protocol Overview
The cryptographic parameters used by the secure channel are produced The cryptographic parameters used by the secure channel are produced
by the TLS handshake protocol. This sub-protocol of TLS is used by by the TLS handshake protocol. This sub-protocol of TLS is used by
the client and server when first communicating with each other. The the client and server when first communicating with each other. The
handshake protocol allows peers to negotiate a protocol version, handshake protocol allows peers to negotiate a protocol version,
select cryptographic algorithms, optionally authenticate each other, select cryptographic algorithms, optionally authenticate each other,
and establish shared secret keying material. Once the handshake is and establish shared secret keying material. Once the handshake is
complete, the peers use the established keys to protect the complete, the peers use the established keys to protect the
application layer traffic. application-layer traffic.
A failure of the handshake or other protocol error triggers the A failure of the handshake or other protocol error triggers the
termination of the connection, optionally preceded by an alert termination of the connection, optionally preceded by an alert
message (Section 6). message (Section 6).
TLS supports three basic key exchange modes: TLS supports three basic key exchange modes:
- (EC)DHE (Diffie-Hellman over either finite fields or elliptic - (EC)DHE (Diffie-Hellman over either finite fields or elliptic
curves) curves)
skipping to change at page 18, line 28 skipping to change at page 11, line 4
message (Section 6). message (Section 6).
TLS supports three basic key exchange modes: TLS supports three basic key exchange modes:
- (EC)DHE (Diffie-Hellman over either finite fields or elliptic - (EC)DHE (Diffie-Hellman over either finite fields or elliptic
curves) curves)
- PSK-only - PSK-only
- PSK with (EC)DHE - PSK with (EC)DHE
Figure 1 below shows the basic full TLS handshake: Figure 1 below shows the basic full TLS handshake:
Client Server Client Server
Key ^ ClientHello Key ^ ClientHello
Exch | + key_share* Exch | + key_share*
| + signature_algorithms* | + signature_algorithms*
| + psk_key_exchange_modes* | + psk_key_exchange_modes*
v + pre_shared_key* --------> v + pre_shared_key* -------->
ServerHello ^ Key ServerHello ^ Key
+ key_share* | Exch + key_share* | Exch
+ pre_shared_key* v + pre_shared_key* v
{EncryptedExtensions} ^ Server {EncryptedExtensions} ^ Server
{CertificateRequest*} v Params {CertificateRequest*} v Params
{Certificate*} ^ {Certificate*} ^
{CertificateVerify*} | Auth {CertificateVerify*} | Auth
{Finished} v {Finished} v
<-------- [Application Data*] <-------- [Application Data*]
^ {Certificate*} ^ {Certificate*}
Auth | {CertificateVerify*} Auth | {CertificateVerify*}
v {Finished} --------> v {Finished} -------->
[Application Data] <-------> [Application Data] [Application Data] <-------> [Application Data]
+ Indicates noteworthy extensions sent in the + Indicates noteworthy extensions sent in the
previously noted message. previously noted message.
* Indicates optional or situation-dependent * Indicates optional or situation-dependent
messages/extensions that are not always sent. messages/extensions that are not always sent.
{} Indicates messages protected using keys {} Indicates messages protected using keys
derived from a [sender]_handshake_traffic_secret. derived from a [sender]_handshake_traffic_secret.
[] Indicates messages protected using keys [] Indicates messages protected using keys
derived from [sender]_application_traffic_secret_N derived from [sender]_application_traffic_secret_N.
Figure 1: Message flow for full TLS Handshake Figure 1: Message Flow for Full TLS Handshake
The handshake can be thought of as having three phases (indicated in The handshake can be thought of as having three phases (indicated in
the diagram above): the diagram above):
- Key Exchange: Establish shared keying material and select the - Key Exchange: Establish shared keying material and select the
cryptographic parameters. Everything after this phase is cryptographic parameters. Everything after this phase is
encrypted. encrypted.
- Server Parameters: Establish other handshake parameters (whether - Server Parameters: Establish other handshake parameters
the client is authenticated, application layer protocol support, (whether the client is authenticated, application-layer protocol
etc.). support, etc.).
- Authentication: Authenticate the server (and optionally the - Authentication: Authenticate the server (and, optionally, the
client) and provide key confirmation and handshake integrity. client) and provide key confirmation and handshake integrity.
In the Key Exchange phase, the client sends the ClientHello In the Key Exchange phase, the client sends the ClientHello
(Section 4.1.2) message, which contains a random nonce (Section 4.1.2) message, which contains a random nonce
(ClientHello.random); its offered protocol versions; a list of (ClientHello.random); its offered protocol versions; a list of
symmetric cipher/HKDF hash pairs; either a set of Diffie-Hellman key symmetric cipher/HKDF hash pairs; either a set of Diffie-Hellman key
shares (in the "key_share" extension Section 4.2.8), a set of pre- shares (in the "key_share" (Section 4.2.8) extension), a set of
shared key labels (in the "pre_shared_key" extension Section 4.2.11) pre-shared key labels (in the "pre_shared_key" (Section 4.2.11)
or both; and potentially additional extensions. Additional fields extension), or both; and potentially additional extensions.
and/or messages may also be present for middlebox compatibility. Additional fields and/or messages may also be present for middlebox
compatibility.
The server processes the ClientHello and determines the appropriate The server processes the ClientHello and determines the appropriate
cryptographic parameters for the connection. It then responds with cryptographic parameters for the connection. It then responds with
its own ServerHello (Section 4.1.3), which indicates the negotiated its own ServerHello (Section 4.1.3), which indicates the negotiated
connection parameters. The combination of the ClientHello and the connection parameters. The combination of the ClientHello and the
ServerHello determines the shared keys. If (EC)DHE key establishment ServerHello determines the shared keys. If (EC)DHE key establishment
is in use, then the ServerHello contains a "key_share" extension with is in use, then the ServerHello contains a "key_share" extension with
the server's ephemeral Diffie-Hellman share; the server's share MUST the server's ephemeral Diffie-Hellman share; the server's share MUST
be in the same group as one of the client's shares. If PSK key be in the same group as one of the client's shares. If PSK key
establishment is in use, then the ServerHello contains a establishment is in use, then the ServerHello contains a
skipping to change at page 20, line 45 skipping to change at page 13, line 10
CertificateRequest: if certificate-based client authentication is CertificateRequest: if certificate-based client authentication is
desired, the desired parameters for that certificate. This desired, the desired parameters for that certificate. This
message is omitted if client authentication is not desired. message is omitted if client authentication is not desired.
[Section 4.3.2] [Section 4.3.2]
Finally, the client and server exchange Authentication messages. TLS Finally, the client and server exchange Authentication messages. TLS
uses the same set of messages every time that certificate-based uses the same set of messages every time that certificate-based
authentication is needed. (PSK-based authentication happens as a authentication is needed. (PSK-based authentication happens as a
side effect of key exchange.) Specifically: side effect of key exchange.) Specifically:
Certificate: the certificate of the endpoint and any per-certificate Certificate: The certificate of the endpoint and any per-certificate
extensions. This message is omitted by the server if not extensions. This message is omitted by the server if not
authenticating with a certificate and by the client if the server authenticating with a certificate and by the client if the server
did not send CertificateRequest (thus indicating that the client did not send CertificateRequest (thus indicating that the client
should not authenticate with a certificate). Note that if raw should not authenticate with a certificate). Note that if raw
public keys [RFC7250] or the cached information extension public keys [RFC7250] or the cached information extension
[RFC7924] are in use, then this message will not contain a [RFC7924] are in use, then this message will not contain a
certificate but rather some other value corresponding to the certificate but rather some other value corresponding to the
server's long-term key. [Section 4.4.2] server's long-term key. [Section 4.4.2]
CertificateVerify: a signature over the entire handshake using the CertificateVerify: A signature over the entire handshake using the
private key corresponding to the public key in the Certificate private key corresponding to the public key in the Certificate
message. This message is omitted if the endpoint is not message. This message is omitted if the endpoint is not
authenticating via a certificate. [Section 4.4.3] authenticating via a certificate. [Section 4.4.3]
Finished: a MAC (Message Authentication Code) over the entire Finished: A MAC (Message Authentication Code) over the entire
handshake. This message provides key confirmation, binds the handshake. This message provides key confirmation, binds the
endpoint's identity to the exchanged keys, and in PSK mode also endpoint's identity to the exchanged keys, and in PSK mode also
authenticates the handshake. [Section 4.4.4] authenticates the handshake. [Section 4.4.4]
Upon receiving the server's messages, the client responds with its Upon receiving the server's messages, the client responds with its
Authentication messages, namely Certificate and CertificateVerify (if Authentication messages, namely Certificate and CertificateVerify (if
requested), and Finished. requested), and Finished.
At this point, the handshake is complete, and the client and server At this point, the handshake is complete, and the client and server
derive the keying material required by the record layer to exchange derive the keying material required by the record layer to exchange
application-layer data protected through authenticated encryption. application-layer data protected through authenticated encryption.
Application data MUST NOT be sent prior to sending the Finished Application Data MUST NOT be sent prior to sending the Finished
message, except as specified in [Section 2.3]. Note that while the message, except as specified in Section 2.3. Note that while the
server may send application data prior to receiving the client's server may send Application Data prior to receiving the client's
Authentication messages, any data sent at that point is, of course, Authentication messages, any data sent at that point is, of course,
being sent to an unauthenticated peer. being sent to an unauthenticated peer.
2.1. Incorrect DHE Share 2.1. Incorrect DHE Share
If the client has not provided a sufficient "key_share" extension If the client has not provided a sufficient "key_share" extension
(e.g., it includes only DHE or ECDHE groups unacceptable to or (e.g., it includes only DHE or ECDHE groups unacceptable to or
unsupported by the server), the server corrects the mismatch with a unsupported by the server), the server corrects the mismatch with a
HelloRetryRequest and the client needs to restart the handshake with HelloRetryRequest and the client needs to restart the handshake with
an appropriate "key_share" extension, as shown in Figure 2. If no an appropriate "key_share" extension, as shown in Figure 2. If no
common cryptographic parameters can be negotiated, the server MUST common cryptographic parameters can be negotiated, the server MUST
abort the handshake with an appropriate alert. abort the handshake with an appropriate alert.
Client Server Client Server
ClientHello ClientHello
+ key_share --------> + key_share -------->
HelloRetryRequest HelloRetryRequest
<-------- + key_share <-------- + key_share
ClientHello ClientHello
+ key_share --------> + key_share -------->
ServerHello ServerHello
+ key_share + key_share
{EncryptedExtensions} {EncryptedExtensions}
{CertificateRequest*} {CertificateRequest*}
{Certificate*} {Certificate*}
{CertificateVerify*} {CertificateVerify*}
{Finished} {Finished}
<-------- [Application Data*] <-------- [Application Data*]
{Certificate*} {Certificate*}
{CertificateVerify*} {CertificateVerify*}
{Finished} --------> {Finished} -------->
[Application Data] <-------> [Application Data] [Application Data] <-------> [Application Data]
Figure 2: Message flow for a full handshake with mismatched Figure 2: Message Flow for a Full Handshake with
parameters Mismatched Parameters
Note: The handshake transcript incorporates the initial ClientHello/ Note: The handshake transcript incorporates the initial
HelloRetryRequest exchange; it is not reset with the new ClientHello. ClientHello/HelloRetryRequest exchange; it is not reset with the
new ClientHello.
TLS also allows several optimized variants of the basic handshake, as TLS also allows several optimized variants of the basic handshake, as
described in the following sections. described in the following sections.
2.2. Resumption and Pre-Shared Key (PSK) 2.2. Resumption and Pre-Shared Key (PSK)
Although TLS PSKs can be established out of band, PSKs can also be Although TLS PSKs can be established out of band, PSKs can also be
established in a previous connection and then used to establish a new established in a previous connection and then used to establish a new
connection ("session resumption" or "resuming" with a PSK). Once a connection ("session resumption" or "resuming" with a PSK). Once a
handshake has completed, the server can send to the client a PSK handshake has completed, the server can send the client a PSK
identity that corresponds to a unique key derived from the initial identity that corresponds to a unique key derived from the initial
handshake (see Section 4.6.1). The client can then use that PSK handshake (see Section 4.6.1). The client can then use that PSK
identity in future handshakes to negotiate the use of the associated identity in future handshakes to negotiate the use of the associated
PSK. If the server accepts the PSK, then the security context of the PSK. If the server accepts the PSK, then the security context of the
new connection is cryptographically tied to the original connection new connection is cryptographically tied to the original connection
and the key derived from the initial handshake is used to bootstrap and the key derived from the initial handshake is used to bootstrap
the cryptographic state instead of a full handshake. In TLS 1.2 and the cryptographic state instead of a full handshake. In TLS 1.2 and
below, this functionality was provided by "session IDs" and "session below, this functionality was provided by "session IDs" and "session
tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3. tickets" [RFC5077]. Both mechanisms are obsoleted in TLS 1.3.
PSKs can be used with (EC)DHE key exchange in order to provide PSKs can be used with (EC)DHE key exchange in order to provide
forward secrecy in combination with shared keys, or can be used forward secrecy in combination with shared keys, or can be used
alone, at the cost of losing forward secrecy for the application alone, at the cost of losing forward secrecy for the application
data. data.
Figure 3 shows a pair of handshakes in which the first establishes a Figure 3 shows a pair of handshakes in which the first handshake
PSK and the second uses it: establishes a PSK and the second handshake uses it:
Client Server Client Server
Initial Handshake: Initial Handshake:
ClientHello ClientHello
+ key_share --------> + key_share -------->
ServerHello ServerHello
+ key_share + key_share
{EncryptedExtensions} {EncryptedExtensions}
{CertificateRequest*} {CertificateRequest*}
skipping to change at page 23, line 42 skipping to change at page 16, line 40
+ pre_shared_key --------> + pre_shared_key -------->
ServerHello ServerHello
+ pre_shared_key + pre_shared_key
+ key_share* + key_share*
{EncryptedExtensions} {EncryptedExtensions}
{Finished} {Finished}
<-------- [Application Data*] <-------- [Application Data*]
{Finished} --------> {Finished} -------->
[Application Data] <-------> [Application Data] [Application Data] <-------> [Application Data]
Figure 3: Message flow for resumption and PSK Figure 3: Message Flow for Resumption and PSK
As the server is authenticating via a PSK, it does not send a As the server is authenticating via a PSK, it does not send a
Certificate or a CertificateVerify message. When a client offers Certificate or a CertificateVerify message. When a client offers
resumption via PSK, it SHOULD also supply a "key_share" extension to resumption via a PSK, it SHOULD also supply a "key_share" extension
the server to allow the server to decline resumption and fall back to to the server to allow the server to decline resumption and fall back
a full handshake, if needed. The server responds with a to a full handshake, if needed. The server responds with a
"pre_shared_key" extension to negotiate use of PSK key establishment "pre_shared_key" extension to negotiate the use of PSK key
and can (as shown here) respond with a "key_share" extension to do establishment and can (as shown here) respond with a "key_share"
(EC)DHE key establishment, thus providing forward secrecy. extension to do (EC)DHE key establishment, thus providing forward
secrecy.
When PSKs are provisioned out of band, the PSK identity and the KDF When PSKs are provisioned out of band, the PSK identity and the KDF
hash algorithm to be used with the PSK MUST also be provisioned. hash algorithm to be used with the PSK MUST also be provisioned.
Note: When using an out-of-band provisioned pre-shared secret, a Note: When using an out-of-band provisioned pre-shared secret, a
critical consideration is using sufficient entropy during the key critical consideration is using sufficient entropy during the key
generation, as discussed in [RFC4086]. Deriving a shared secret generation, as discussed in [RFC4086]. Deriving a shared secret
from a password or other low-entropy sources is not secure. A from a password or other low-entropy sources is not secure. A
low-entropy secret, or password, is subject to dictionary attacks low-entropy secret, or password, is subject to dictionary attacks
based on the PSK binder. The specified PSK authentication is not based on the PSK binder. The specified PSK authentication is not
skipping to change at page 25, line 5 skipping to change at page 18, line 5
When clients and servers share a PSK (either obtained externally or When clients and servers share a PSK (either obtained externally or
via a previous handshake), TLS 1.3 allows clients to send data on the via a previous handshake), TLS 1.3 allows clients to send data on the
first flight ("early data"). The client uses the PSK to authenticate first flight ("early data"). The client uses the PSK to authenticate
the server and to encrypt the early data. the server and to encrypt the early data.
As shown in Figure 4, the 0-RTT data is just added to the 1-RTT As shown in Figure 4, the 0-RTT data is just added to the 1-RTT
handshake in the first flight. The rest of the handshake uses the handshake in the first flight. The rest of the handshake uses the
same messages as for a 1-RTT handshake with PSK resumption. same messages as for a 1-RTT handshake with PSK resumption.
Client Server Client Server
ClientHello ClientHello
+ early_data + early_data
+ key_share* + key_share*
+ psk_key_exchange_modes + psk_key_exchange_modes
+ pre_shared_key + pre_shared_key
(Application Data*) --------> (Application Data*) -------->
ServerHello ServerHello
+ pre_shared_key + pre_shared_key
+ key_share* + key_share*
{EncryptedExtensions} {EncryptedExtensions}
+ early_data* + early_data*
{Finished} {Finished}
<-------- [Application Data*] <-------- [Application Data*]
(EndOfEarlyData) (EndOfEarlyData)
{Finished} --------> {Finished} -------->
[Application Data] <-------> [Application Data] [Application Data] <-------> [Application Data]
+ Indicates noteworthy extensions sent in the + Indicates noteworthy extensions sent in the
previously noted message. previously noted message.
* Indicates optional or situation-dependent * Indicates optional or situation-dependent
messages/extensions that are not always sent. messages/extensions that are not always sent.
() Indicates messages protected using keys () Indicates messages protected using keys
derived from client_early_traffic_secret. derived from a client_early_traffic_secret.
{} Indicates messages protected using keys {} Indicates messages protected using keys
derived from a [sender]_handshake_traffic_secret. derived from a [sender]_handshake_traffic_secret.
[] Indicates messages protected using keys [] Indicates messages protected using keys
derived from [sender]_application_traffic_secret_N derived from [sender]_application_traffic_secret_N.
Figure 4: Message flow for a zero round trip handshake Figure 4: Message Flow for a 0-RTT Handshake
IMPORTANT NOTE: The security properties for 0-RTT data are weaker IMPORTANT NOTE: The security properties for 0-RTT data are weaker
than those for other kinds of TLS data. Specifically: than those for other kinds of TLS data. Specifically:
1. This data is not forward secret, as it is encrypted solely under 1. This data is not forward secret, as it is encrypted solely under
keys derived using the offered PSK. keys derived using the offered PSK.
2. There are no guarantees of non-replay between connections. 2. There are no guarantees of non-replay between connections.
Protection against replay for ordinary TLS 1.3 1-RTT data is Protection against replay for ordinary TLS 1.3 1-RTT data is
provided via the server's Random value, but 0-RTT data does not provided via the server's Random value, but 0-RTT data does not
depend on the ServerHello and therefore has weaker guarantees. depend on the ServerHello and therefore has weaker guarantees.
This is especially relevant if the data is authenticated either This is especially relevant if the data is authenticated either
with TLS client authentication or inside the application with TLS client authentication or inside the application
protocol. The same warnings apply to any use of the protocol. The same warnings apply to any use of the
early_exporter_master_secret. early_exporter_master_secret.
0-RTT data cannot be duplicated within a connection (i.e., the server 0-RTT data cannot be duplicated within a connection (i.e., the server
will not process the same data twice for the same connection) and an will not process the same data twice for the same connection), and an
attacker will not be able to make 0-RTT data appear to be 1-RTT data attacker will not be able to make 0-RTT data appear to be 1-RTT data
(because it is protected with different keys.) Appendix E.5 contains (because it is protected with different keys). Appendix E.5 contains
a description of potential attacks and Section 8 describes mechanisms a description of potential attacks, and Section 8 describes
which the server can use to limit the impact of replay. mechanisms which the server can use to limit the impact of replay.
3. Presentation Language 3. Presentation Language
This document deals with the formatting of data in an external This document deals with the formatting of data in an external
representation. The following very basic and somewhat casually representation. The following very basic and somewhat casually
defined presentation syntax will be used. defined presentation syntax will be used.
3.1. Basic Block Size 3.1. Basic Block Size
The representation of all data items is explicitly specified. The The representation of all data items is explicitly specified. The
basic data block size is one byte (i.e., 8 bits). Multiple byte data basic data block size is one byte (i.e., 8 bits). Multiple-byte data
items are concatenations of bytes, from left to right, from top to items are concatenations of bytes, from left to right, from top to
bottom. From the byte stream, a multi-byte item (a numeric in the bottom. From the byte stream, a multi-byte item (a numeric in the
example) is formed (using C notation) by: following example) is formed (using C notation) by:
value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) |
... | byte[n-1]; ... | byte[n-1];
This byte ordering for multi-byte values is the commonplace network This byte ordering for multi-byte values is the commonplace network
byte order or big-endian format. byte order or big-endian format.
3.2. Miscellaneous 3.2. Miscellaneous
Comments begin with "/*" and end with "*/". Comments begin with "/*" and end with "*/".
Optional components are denoted by enclosing them in "[[ ]]" double Optional components are denoted by enclosing them in "[[ ]]" (double
brackets. brackets).
Single-byte entities containing uninterpreted data are of type Single-byte entities containing uninterpreted data are of
opaque. type opaque.
A type alias T' for an existing type T is defined by: A type alias T' for an existing type T is defined by:
T T'; T T';
3.3. Numbers 3.3. Numbers
The basic numeric data type is an unsigned byte (uint8). All larger The basic numeric data type is an unsigned byte (uint8). All larger
numeric data types are formed from fixed-length series of bytes numeric data types are constructed from a fixed-length series of
concatenated as described in Section 3.1 and are also unsigned. The bytes concatenated as described in Section 3.1 and are also unsigned.
following numeric types are predefined. The following numeric types are predefined.
uint8 uint16[2]; uint8 uint16[2];
uint8 uint24[3]; uint8 uint24[3];
uint8 uint32[4]; uint8 uint32[4];
uint8 uint64[8]; uint8 uint64[8];
All values, here and elsewhere in the specification, are transmitted All values, here and elsewhere in the specification, are transmitted
in network byte (big-endian) order; the uint32 represented by the hex in network byte (big-endian) order; the uint32 represented by the hex
bytes 01 02 03 04 is equivalent to the decimal value 16909060. bytes 01 02 03 04 is equivalent to the decimal value 16909060.
skipping to change at page 27, line 41 skipping to change at page 21, line 10
Here, T' occupies n bytes in the data stream, where n is a multiple Here, T' occupies n bytes in the data stream, where n is a multiple
of the size of T. The length of the vector is not included in the of the size of T. The length of the vector is not included in the
encoded stream. encoded stream.
In the following example, Datum is defined to be three consecutive In the following example, Datum is defined to be three consecutive
bytes that the protocol does not interpret, while Data is three bytes that the protocol does not interpret, while Data is three
consecutive Datum, consuming a total of nine bytes. consecutive Datum, consuming a total of nine bytes.
opaque Datum[3]; /* three uninterpreted bytes */ opaque Datum[3]; /* three uninterpreted bytes */
Datum Data[9]; /* 3 consecutive 3-byte vectors */ Datum Data[9]; /* three consecutive 3-byte vectors */
Variable-length vectors are defined by specifying a subrange of legal Variable-length vectors are defined by specifying a subrange of legal
lengths, inclusively, using the notation <floor..ceiling>. When lengths, inclusively, using the notation <floor..ceiling>. When
these are encoded, the actual length precedes the vector's contents these are encoded, the actual length precedes the vector's contents
in the byte stream. The length will be in the form of a number in the byte stream. The length will be in the form of a number
consuming as many bytes as required to hold the vector's specified consuming as many bytes as required to hold the vector's specified
maximum (ceiling) length. A variable-length vector with an actual maximum (ceiling) length. A variable-length vector with an actual
length field of zero is referred to as an empty vector. length field of zero is referred to as an empty vector.
T T'<floor..ceiling>; T T'<floor..ceiling>;
In the following example, mandatory is a vector that must contain In the following example, "mandatory" is a vector that must contain
between 300 and 400 bytes of type opaque. It can never be empty. between 300 and 400 bytes of type opaque. It can never be empty.
The actual length field consumes two bytes, a uint16, which is The actual length field consumes two bytes, a uint16, which is
sufficient to represent the value 400 (see Section 3.3). Similarly, sufficient to represent the value 400 (see Section 3.3). Similarly,
longer can represent up to 800 bytes of data, or 400 uint16 elements, "longer" can represent up to 800 bytes of data, or 400 uint16
and it may be empty. Its encoding will include a two-byte actual elements, and it may be empty. Its encoding will include a two-byte
length field prepended to the vector. The length of an encoded actual length field prepended to the vector. The length of an
vector must be an exact multiple of the length of a single element encoded vector must be an exact multiple of the length of a single
(e.g., a 17-byte vector of uint16 would be illegal). element (e.g., a 17-byte vector of uint16 would be illegal).
opaque mandatory<300..400>; opaque mandatory<300..400>;
/* length field is 2 bytes, cannot be empty */ /* length field is two bytes, cannot be empty */
uint16 longer<0..800>; uint16 longer<0..800>;
/* zero to 400 16-bit unsigned integers */ /* zero to 400 16-bit unsigned integers */
3.5. Enumerateds 3.5. Enumerateds
An additional sparse data type is available called enum or An additional sparse data type, called "enum" or "enumerated", is
enumerated. Each definition is a different type. Only enumerateds available. Each definition is a different type. Only enumerateds of
of the same type may be assigned or compared. Every element of an the same type may be assigned or compared. Every element of an
enumerated must be assigned a value, as demonstrated in the following enumerated must be assigned a value, as demonstrated in the following
example. Since the elements of the enumerated are not ordered, they example. Since the elements of the enumerated are not ordered, they
can be assigned any unique value, in any order. can be assigned any unique value, in any order.
enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te;
Future extensions or additions to the protocol may define new values. Future extensions or additions to the protocol may define new values.
Implementations need to be able to parse and ignore unknown values Implementations need to be able to parse and ignore unknown values
unless the definition of the field states otherwise. unless the definition of the field states otherwise.
skipping to change at page 29, line 22 skipping to change at page 22, line 41
applies. The value includes the minimum and maximum inclusive values applies. The value includes the minimum and maximum inclusive values
in that range, separated by two period characters. This is in that range, separated by two period characters. This is
principally useful for reserving regions of the space. principally useful for reserving regions of the space.
enum { sad(0), meh(1..254), happy(255) } Mood; enum { sad(0), meh(1..254), happy(255) } Mood;
3.6. Constructed Types 3.6. Constructed Types
Structure types may be constructed from primitive types for Structure types may be constructed from primitive types for
convenience. Each specification declares a new, unique type. The convenience. Each specification declares a new, unique type. The
syntax for definition is much like that of C. syntax used for definitions is much like that of C.
struct { struct {
T1 f1; T1 f1;
T2 f2; T2 f2;
... ...
Tn fn; Tn fn;
} T; } T;
Fixed- and variable-length vector fields are allowed using the Fixed- and variable-length vector fields are allowed using the
standard vector syntax. Structures V1 and V2 in the variants example standard vector syntax. Structures V1 and V2 in the variants example
below demonstrate this. (Section 3.8) demonstrate this.
The fields within a structure may be qualified using the type's name, The fields within a structure may be qualified using the type's name,
with a syntax much like that available for enumerateds. For example, with a syntax much like that available for enumerateds. For example,
T.f2 refers to the second field of the previous declaration. T.f2 refers to the second field of the previous declaration.
3.7. Constants 3.7. Constants
Fields and variables may be assigned a fixed value using "=", as in: Fields and variables may be assigned a fixed value using "=", as in:
struct { struct {
T1 f1 = 8; /* T.f1 must always be 8 */ T1 f1 = 8; /* T.f1 must always be 8 */
T2 f2; T2 f2;
} T; } T;
3.8. Variants 3.8. Variants
Defined structures may have variants based on some knowledge that is Defined structures may have variants based on some knowledge that is
available within the environment. The selector must be an enumerated available within the environment. The selector must be an enumerated
type that defines the possible variants the structure defines. Each type that defines the possible variants the structure defines. Each
arm of the select specifies the type of that variant's field and an arm of the select (below) specifies the type of that variant's field
optional field label. The mechanism by which the variant is selected and an optional field label. The mechanism by which the variant is
at runtime is not prescribed by the presentation language. selected at runtime is not prescribed by the presentation language.
struct { struct {
T1 f1; T1 f1;
T2 f2; T2 f2;
.... ....
Tn fn; Tn fn;
select (E) { select (E) {
case e1: Te1 [[fe1]]; case e1: Te1 [[fe1]];
case e2: Te2 [[fe2]]; case e2: Te2 [[fe2]];
.... ....
skipping to change at page 31, line 10 skipping to change at page 24, line 32
case apple: V1; case apple: V1;
case orange: V2; case orange: V2;
}; };
} VariantRecord; } VariantRecord;
4. Handshake Protocol 4. Handshake Protocol
The handshake protocol is used to negotiate the security parameters The handshake protocol is used to negotiate the security parameters
of a connection. Handshake messages are supplied to the TLS record of a connection. Handshake messages are supplied to the TLS record
layer, where they are encapsulated within one or more TLSPlaintext or layer, where they are encapsulated within one or more TLSPlaintext or
TLSCiphertext structures, which are processed and transmitted as TLSCiphertext structures which are processed and transmitted as
specified by the current active connection state. specified by the current active connection state.
enum { enum {
client_hello(1), client_hello(1),
server_hello(2), server_hello(2),
new_session_ticket(4), new_session_ticket(4),
end_of_early_data(5), end_of_early_data(5),
encrypted_extensions(8), encrypted_extensions(8),
certificate(11), certificate(11),
certificate_request(13), certificate_request(13),
certificate_verify(15), certificate_verify(15),
finished(20), finished(20),
key_update(24), key_update(24),
message_hash(254), message_hash(254),
(255) (255)
} HandshakeType; } HandshakeType;
struct { struct {
HandshakeType msg_type; /* handshake type */ HandshakeType msg_type; /* handshake type */
uint24 length; /* bytes in message */ uint24 length; /* remaining bytes in message */
select (Handshake.msg_type) { select (Handshake.msg_type) {
case client_hello: ClientHello; case client_hello: ClientHello;
case server_hello: ServerHello; case server_hello: ServerHello;
case end_of_early_data: EndOfEarlyData; case end_of_early_data: EndOfEarlyData;
case encrypted_extensions: EncryptedExtensions; case encrypted_extensions: EncryptedExtensions;
case certificate_request: CertificateRequest; case certificate_request: CertificateRequest;
case certificate: Certificate; case certificate: Certificate;
case certificate_verify: CertificateVerify; case certificate_verify: CertificateVerify;
case finished: Finished; case finished: Finished;
case new_session_ticket: NewSessionTicket; case new_session_ticket: NewSessionTicket;
skipping to change at page 32, line 9 skipping to change at page 25, line 49
handshake message in an unexpected order MUST abort the handshake handshake message in an unexpected order MUST abort the handshake
with an "unexpected_message" alert. with an "unexpected_message" alert.
New handshake message types are assigned by IANA as described in New handshake message types are assigned by IANA as described in
Section 11. Section 11.
4.1. Key Exchange Messages 4.1. Key Exchange Messages
The key exchange messages are used to determine the security The key exchange messages are used to determine the security
capabilities of the client and the server and to establish shared capabilities of the client and the server and to establish shared
secrets including the traffic keys used to protect the rest of the secrets, including the traffic keys used to protect the rest of the
handshake and the data. handshake and the data.
4.1.1. Cryptographic Negotiation 4.1.1. Cryptographic Negotiation
In TLS, the cryptographic negotiation proceeds by the client offering In TLS, the cryptographic negotiation proceeds by the client offering
the following four sets of options in its ClientHello: the following four sets of options in its ClientHello:
- A list of cipher suites which indicates the AEAD algorithm/HKDF - A list of cipher suites which indicates the AEAD algorithm/HKDF
hash pairs which the client supports. hash pairs which the client supports.
- A "supported_groups" (Section 4.2.7) extension which indicates the - A "supported_groups" (Section 4.2.7) extension which indicates the
(EC)DHE groups which the client supports and a "key_share" (EC)DHE groups which the client supports and a "key_share"
(Section 4.2.8) extension which contains (EC)DHE shares for some (Section 4.2.8) extension which contains (EC)DHE shares for some
or all of these groups. or all of these groups.
- A "signature_algorithms" (Section 4.2.3) extension which indicates - A "signature_algorithms" (Section 4.2.3) extension which indicates
the signature algorithms which the client can accept. the signature algorithms which the client can accept. A
"signature_algorithms_cert" extension (Section 4.2.3) may also be
added to indicate certificate-specific signature algorithms.
- A "pre_shared_key" (Section 4.2.11) extension which contains a - A "pre_shared_key" (Section 4.2.11) extension which contains a
list of symmetric key identities known to the client and a list of symmetric key identities known to the client and a
"psk_key_exchange_modes" (Section 4.2.9) extension which indicates "psk_key_exchange_modes" (Section 4.2.9) extension which indicates
the key exchange modes that may be used with PSKs. the key exchange modes that may be used with PSKs.
If the server does not select a PSK, then the first three of these If the server does not select a PSK, then the first three of these
options are entirely orthogonal: the server independently selects a options are entirely orthogonal: the server independently selects a
cipher suite, an (EC)DHE group and key share for key establishment, cipher suite, an (EC)DHE group and key share for key establishment,
and a signature algorithm/certificate pair to authenticate itself to and a signature algorithm/certificate pair to authenticate itself to
the client. If there is no overlap between the received the client. If there is no overlap between the received
"supported_groups" and the groups supported by the server then the "supported_groups" and the groups supported by the server, then the
server MUST abort the handshake with a "handshake_failure" or an server MUST abort the handshake with a "handshake_failure" or an
"insufficient_security" alert. "insufficient_security" alert.
If the server selects a PSK, then it MUST also select a key If the server selects a PSK, then it MUST also select a key
establishment mode from the set indicated by client's establishment mode from the set indicated by the client's
"psk_key_exchange_modes" extension (at present, PSK alone or with "psk_key_exchange_modes" extension (at present, PSK alone or with
(EC)DHE). Note that if the PSK can be used without (EC)DHE then non- (EC)DHE). Note that if the PSK can be used without (EC)DHE, then
overlap in the "supported_groups" parameters need not be fatal, as it non-overlap in the "supported_groups" parameters need not be fatal,
is in the non-PSK case discussed in the previous paragraph. as it is in the non-PSK case discussed in the previous paragraph.
If the server selects an (EC)DHE group and the client did not offer a If the server selects an (EC)DHE group and the client did not offer a
compatible "key_share" extension in the initial ClientHello, the compatible "key_share" extension in the initial ClientHello, the
server MUST respond with a HelloRetryRequest (Section 4.1.4) message. server MUST respond with a HelloRetryRequest (Section 4.1.4) message.
If the server successfully selects parameters and does not require a If the server successfully selects parameters and does not require a
HelloRetryRequest, it indicates the selected parameters in the HelloRetryRequest, it indicates the selected parameters in the
ServerHello as follows: ServerHello as follows:
- If PSK is being used, then the server will send a "pre_shared_key" - If PSK is being used, then the server will send a "pre_shared_key"
extension indicating the selected key. extension indicating the selected key.
- If PSK is not being used, then (EC)DHE and certificate-based
authentication are always used.
- When (EC)DHE is in use, the server will also provide a "key_share" - When (EC)DHE is in use, the server will also provide a "key_share"
extension. extension. If PSK is not being used, then (EC)DHE and
certificate-based authentication are always used.
- When authenticating via a certificate, the server will send the - When authenticating via a certificate, the server will send the
Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3) Certificate (Section 4.4.2) and CertificateVerify (Section 4.4.3)
messages. In TLS 1.3 as defined by this document, either a PSK or messages. In TLS 1.3 as defined by this document, either a PSK or
a certificate is always used, but not both. Future documents may a certificate is always used, but not both. Future documents may
define how to use them together. define how to use them together.
If the server is unable to negotiate a supported set of parameters If the server is unable to negotiate a supported set of parameters
(i.e., there is no overlap between the client and server parameters), (i.e., there is no overlap between the client and server parameters),
it MUST abort the handshake with either a "handshake_failure" or it MUST abort the handshake with either a "handshake_failure" or
"insufficient_security" fatal alert (see Section 6). "insufficient_security" fatal alert (see Section 6).
4.1.2. Client Hello 4.1.2. Client Hello
When a client first connects to a server, it is REQUIRED to send the 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 as its first TLS message. The client will also send a
ClientHello when the server has responded to its ClientHello with a ClientHello when the server has responded to its ClientHello with a
HelloRetryRequest. In that case, the client MUST send the same HelloRetryRequest. In that case, the client MUST send the same
ClientHello without modification, except: ClientHello without modification, except as follows:
- If a "key_share" extension was supplied in the HelloRetryRequest, - If a "key_share" extension was supplied in the HelloRetryRequest,
replacing the list of shares with a list containing a single replacing the list of shares with a list containing a single
KeyShareEntry from the indicated group. KeyShareEntry from the indicated group.
- Removing the "early_data" extension (Section 4.2.10) if one was - Removing the "early_data" extension (Section 4.2.10) if one was
present. Early data is not permitted after HelloRetryRequest. present. Early data is not permitted after a HelloRetryRequest.
- Including a "cookie" extension if one was provided in the - Including a "cookie" extension if one was provided in the
HelloRetryRequest. HelloRetryRequest.
- Updating the "pre_shared_key" extension if present by recomputing - Updating the "pre_shared_key" extension if present by recomputing
the "obfuscated_ticket_age" and binder values and (optionally) the "obfuscated_ticket_age" and binder values and (optionally)
removing any PSKs which are incompatible with the server's removing any PSKs which are incompatible with the server's
indicated cipher suite. indicated cipher suite.
- Optionally adding, removing, or changing the length of the - Optionally adding, removing, or changing the length of the
"padding" extension [RFC7685]. "padding" extension [RFC7685].
- Other modifications that may be allowed by an extension defined in - Other modifications that may be allowed by an extension defined in
the future and present in the HelloRetryRequest. the future and present in the HelloRetryRequest.
Because TLS 1.3 forbids renegotiation, if a server has negotiated TLS Because TLS 1.3 forbids renegotiation, if a server has negotiated
1.3 and receives a ClientHello at any other time, it MUST terminate TLS 1.3 and receives a ClientHello at any other time, it MUST
the connection with an "unexpected_message" alert. terminate the connection with an "unexpected_message" alert.
If a server established a TLS connection with a previous version of 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 TLS and receives a TLS 1.3 ClientHello in a renegotiation, it MUST
retain the previous protocol version. In particular, it MUST NOT retain the previous protocol version. In particular, it MUST NOT
negotiate TLS 1.3. negotiate TLS 1.3.
Structure of this message: Structure of this message:
uint16 ProtocolVersion; uint16 ProtocolVersion;
opaque Random[32]; opaque Random[32];
skipping to change at page 34, line 36 skipping to change at page 29, line 5
struct { struct {
ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
Random random; Random random;
opaque legacy_session_id<0..32>; opaque legacy_session_id<0..32>;
CipherSuite cipher_suites<2..2^16-2>; CipherSuite cipher_suites<2..2^16-2>;
opaque legacy_compression_methods<1..2^8-1>; opaque legacy_compression_methods<1..2^8-1>;
Extension extensions<8..2^16-1>; Extension extensions<8..2^16-1>;
} ClientHello; } ClientHello;
legacy_version In previous versions of TLS, this field was used for legacy_version: In previous versions of TLS, this field was used for
version negotiation and represented the highest version number version negotiation and represented the highest version number
supported by the client. Experience has shown that many servers supported by the client. Experience has shown that many servers
do not properly implement version negotiation, leading to "version do not properly implement version negotiation, leading to "version
intolerance" in which the server rejects an otherwise acceptable intolerance" in which the server rejects an otherwise acceptable
ClientHello with a version number higher than it supports. In TLS ClientHello with a version number higher than it supports. In
1.3, the client indicates its version preferences in the TLS 1.3, the client indicates its version preferences in the
"supported_versions" extension (Section 4.2.1) and the "supported_versions" extension (Section 4.2.1) and the
legacy_version field MUST be set to 0x0303, which is the version legacy_version field MUST be set to 0x0303, which is the version
number for TLS 1.2. (See Appendix D for details about backward number for TLS 1.2. TLS 1.3 ClientHellos are identified as having
compatibility.) 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 random: 32 bytes generated by a secure random number generator. See
Appendix C for additional information. Appendix C for additional information.
legacy_session_id Versions of TLS before TLS 1.3 supported a legacy_session_id: Versions of TLS before TLS 1.3 supported a
"session resumption" feature which has been merged with Pre-Shared "session resumption" feature which has been merged with pre-shared
Keys in this version (see Section 2.2). A client which has a 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 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) 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 this field MUST be non-empty, so a client not offering a
1.3 session MUST generate a new 32-byte value. This value need pre-TLS 1.3 session MUST generate a new 32-byte value. This value
not be random but SHOULD be unpredictable to avoid implementations need not be random but SHOULD be unpredictable to avoid
fixating on a specific value (also known as ossification). implementations fixating on a specific value (also known as
Otherwise, it MUST be set as a zero length vector (i.e., a single ossification). Otherwise, it MUST be set as a zero-length vector
zero byte length field). (i.e., a zero-valued single byte length field).
cipher_suites This is a list of the symmetric cipher options cipher_suites: A list of the symmetric cipher options supported by
supported by the client, specifically the record protection the client, specifically the record protection algorithm
algorithm (including secret key length) and a hash to be used with (including secret key length) and a hash to be used with HKDF, in
HKDF, in descending order of client preference. If the list descending order of client preference. Values are defined in
contains cipher suites that the server does not recognize, support Appendix B.4. If the list contains cipher suites that the server
or wish to use, the server MUST ignore those cipher suites and does not recognize, support, or wish to use, the server MUST
process the remaining ones as usual. Values are defined in ignore those cipher suites and process the remaining ones as
Appendix B.4. If the client is attempting a PSK key usual. If the client is attempting a PSK key establishment, it
establishment, it SHOULD advertise at least one cipher suite SHOULD advertise at least one cipher suite indicating a Hash
indicating a Hash associated with the PSK. associated with the PSK.
legacy_compression_methods Versions of TLS before 1.3 supported legacy_compression_methods: Versions of TLS before 1.3 supported
compression with the list of supported compression methods being compression with the list of supported compression methods being
sent in this field. For every TLS 1.3 ClientHello, this vector sent in this field. For every TLS 1.3 ClientHello, this vector
MUST contain exactly one byte, set to zero, which corresponds to MUST contain exactly one byte, set to zero, which corresponds to
the "null" compression method in prior versions of TLS. If a TLS the "null" compression method in prior versions of TLS. If a
1.3 ClientHello is received with any other value in this field, TLS 1.3 ClientHello is received with any other value in this
the server MUST abort the handshake with an "illegal_parameter" field, the server MUST abort the handshake with an
alert. Note that TLS 1.3 servers might receive TLS 1.2 or prior "illegal_parameter" alert. Note that TLS 1.3 servers might
ClientHellos which contain other compression methods and (if receive TLS 1.2 or prior ClientHellos which contain other
negotiating such a prior version) MUST follow the procedures for compression methods and (if negotiating such a prior version) MUST
the appropriate prior version of TLS. TLS 1.3 ClientHellos are follow the procedures for the appropriate prior version of TLS.
identified as having a legacy_version of 0x0303 and a
supported_versions extension present with 0x0304 as the highest
version indicated therein.
extensions Clients request extended functionality from servers by extensions: Clients request extended functionality from servers by
sending data in the extensions field. The actual "Extension" sending data in the extensions field. The actual "Extension"
format is defined in Section 4.2. In TLS 1.3, use of certain format is defined in Section 4.2. In TLS 1.3, the use of certain
extensions is mandatory, as functionality is moved into extensions extensions is mandatory, as functionality has moved into
to preserve ClientHello compatibility with previous versions of extensions to preserve ClientHello compatibility with previous
TLS. Servers MUST ignore unrecognized extensions. versions of TLS. Servers MUST ignore unrecognized extensions.
All versions of TLS allow an extensions field to optionally follow All versions of TLS allow an extensions field to optionally follow
the compression_methods field. TLS 1.3 ClientHello messages always the compression_methods field. TLS 1.3 ClientHello messages always
contain extensions (minimally "supported_versions", otherwise they contain extensions (minimally "supported_versions", otherwise, they
will be interpreted as TLS 1.2 ClientHello messages). However, TLS will be interpreted as TLS 1.2 ClientHello messages). However,
1.3 servers might receive ClientHello messages without an extensions TLS 1.3 servers might receive ClientHello messages without an
field from prior versions of TLS. The presence of extensions can be extensions field from prior versions of TLS. The presence of
detected by determining whether there are bytes following the extensions can be detected by determining whether there are bytes
compression_methods field at the end of the ClientHello. Note that following the compression_methods field at the end of the
this method of detecting optional data differs from the normal TLS ClientHello. Note that this method of detecting optional data
method of having a variable-length field, but it is used for differs from the normal TLS method of having a variable-length field,
compatibility with TLS before extensions were defined. TLS 1.3 but it is used for compatibility with TLS before extensions were
servers will need to perform this check first and only attempt to defined. TLS 1.3 servers will need to perform this check first and
negotiate TLS 1.3 if the "supported_versions" extension is present. only attempt to negotiate TLS 1.3 if the "supported_versions"
If negotiating a version of TLS prior to 1.3, a server MUST check extension is present. If negotiating a version of TLS prior to 1.3,
that the message either contains no data after a server MUST check that the message either contains no data after
legacy_compression_methods or that it contains a valid extensions legacy_compression_methods or that it contains a valid extensions
block with no data following. If not, then it MUST abort the block with no data following. If not, then it MUST abort the
handshake with a "decode_error" alert. handshake with a "decode_error" alert.
In the event that a client requests additional functionality using In the event that a client requests additional functionality using
extensions, and this functionality is not supplied by the server, the extensions and this functionality is not supplied by the server, the
client MAY abort the handshake. client MAY abort the handshake.
After sending the ClientHello message, the client waits for a After sending the ClientHello message, the client waits for a
ServerHello or HelloRetryRequest message. If early data is in use, ServerHello or HelloRetryRequest message. If early data is in use,
the client may transmit early application data (Section 2.3) while the client may transmit early Application Data (Section 2.3) while
waiting for the next handshake message. waiting for the next handshake message.
4.1.3. Server Hello 4.1.3. Server Hello
The server will send this message in response to a ClientHello The server will send this message in response to a ClientHello
message to proceed with the handshake if it is able to negotiate an message to proceed with the handshake if it is able to negotiate an
acceptable set of handshake parameters based on the ClientHello. acceptable set of handshake parameters based on the ClientHello.
Structure of this message: Structure of this message:
struct { struct {
ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */ ProtocolVersion legacy_version = 0x0303; /* TLS v1.2 */
Random random; Random random;
opaque legacy_session_id_echo<0..32>; opaque legacy_session_id_echo<0..32>;
CipherSuite cipher_suite; CipherSuite cipher_suite;
uint8 legacy_compression_method = 0; uint8 legacy_compression_method = 0;
Extension extensions<6..2^16-1>; Extension extensions<6..2^16-1>;
} ServerHello; } ServerHello;
legacy_version In previous versions of TLS, this field was used for legacy_version: In previous versions of TLS, this field was used for
version negotiation and represented the selected version number version negotiation and represented the selected version number
for the connection. Unfortunately, some middleboxes fail when for the connection. Unfortunately, some middleboxes fail when
presented with new values. In TLS 1.3, the TLS server indicates presented with new values. In TLS 1.3, the TLS server indicates
its version using the "supported_versions" extension its version using the "supported_versions" extension
(Section 4.2.1), and the legacy_version field MUST be set to (Section 4.2.1), and the legacy_version field MUST be set to
0x0303, which is the version number for TLS 1.2. (See Appendix D 0x0303, which is the version number for TLS 1.2. (See Appendix D
for details about backward compatibility.) for details about backward compatibility.)
random 32 bytes generated by a secure random number generator. See random: 32 bytes generated by a secure random number generator. See
Appendix C for additional information. The last eight bytes MUST Appendix C for additional information. The last 8 bytes MUST be
be overwritten as described below if negotiating TLS 1.2 or TLS overwritten as described below if negotiating TLS 1.2 or TLS 1.1,
1.1, but the remaining bytes MUST be random. This structure is but the remaining bytes MUST be random. This structure is
generated by the server and MUST be generated independently of the generated by the server and MUST be generated independently of the
ClientHello.random. ClientHello.random.
legacy_session_id_echo The contents of the client's legacy_session_id_echo: The contents of the client's
legacy_session_id field. Note that this field is echoed even if legacy_session_id field. Note that this field is echoed even if
the client's value corresponded to a cached pre-TLS 1.3 session the client's value corresponded to a cached pre-TLS 1.3 session
which the server has chosen not to resume. A client which which the server has chosen not to resume. A client which
receives a legacy_session_id_echo field that does not match what receives a legacy_session_id_echo field that does not match what
it sent in the ClientHello MUST abort the handshake with an it sent in the ClientHello MUST abort the handshake with an
"illegal_parameter" alert. "illegal_parameter" alert.
cipher_suite The single cipher suite selected by the server from the cipher_suite: The single cipher suite selected by the server from
list in ClientHello.cipher_suites. A client which receives a the list in ClientHello.cipher_suites. A client which receives a
cipher suite that was not offered MUST abort the handshake with an cipher suite that was not offered MUST abort the handshake with an
"illegal_parameter" alert. "illegal_parameter" alert.
legacy_compression_method A single byte which MUST have the value 0. legacy_compression_method: A single byte which MUST have the
value 0.
extensions A list of extensions. The ServerHello MUST only include extensions: A list of extensions. The ServerHello MUST only include
extensions which are required to establish the cryptographic extensions which are required to establish the cryptographic
context and negotiate the protocol version. All TLS 1.3 context and negotiate the protocol version. All TLS 1.3
ServerHello messages MUST contain the "supported_versions" ServerHello messages MUST contain the "supported_versions"
extension. Current ServerHello messages additionally contain extension. Current ServerHello messages additionally contain
either the "pre_shared_key" or "key_share" extensions, or both either the "pre_shared_key" extension or the "key_share"
when using a PSK with (EC)DHE key establishment. Other extensions extension, or both (when using a PSK with (EC)DHE key
are sent separately in the EncryptedExtensions message. establishment). Other extensions (see Section 4.2) are sent
separately in the EncryptedExtensions message.
For reasons of backward compatibility with middleboxes (see For reasons of backward compatibility with middleboxes (see
Appendix D.4) the HelloRetryRequest message uses the same structure Appendix D.4), the HelloRetryRequest message uses the same structure
as the ServerHello, but with Random set to the special value of the as the ServerHello, but with Random set to the special value of the
SHA-256 of "HelloRetryRequest": SHA-256 of "HelloRetryRequest":
CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91 CF 21 AD 74 E5 9A 61 11 BE 1D 8C 02 1E 65 B8 91
C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C C2 A2 11 16 7A BB 8C 5E 07 9E 09 E2 C8 A8 33 9C
Upon receiving a message with type server_hello, implementations MUST Upon receiving a message with type server_hello, implementations MUST
first examine the Random value and if it matches this value, process first examine the Random value and, if it matches this value, process
it as described in Section 4.1.4). it as described in Section 4.1.4).
TLS 1.3 has a downgrade protection mechanism embedded in the server's TLS 1.3 has a downgrade protection mechanism embedded in the server's
random value. TLS 1.3 servers which negotiate TLS 1.2 or below in random value. TLS 1.3 servers which negotiate TLS 1.2 or below in
response to a ClientHello MUST set the last eight bytes of their response to a ClientHello MUST set the last 8 bytes of their Random
Random value specially. value specially in their ServerHello.
If negotiating TLS 1.2, TLS 1.3 servers MUST set the last eight bytes If negotiating TLS 1.2, TLS 1.3 servers MUST set the last 8 bytes of
of their Random value to the bytes: their Random value to the bytes:
44 4F 57 4E 47 52 44 01 44 4F 57 4E 47 52 44 01
If negotiating TLS 1.1 or below, TLS 1.3 servers MUST and TLS 1.2 If negotiating TLS 1.1 or below, TLS 1.3 servers MUST, and TLS 1.2
servers SHOULD set the last eight bytes of their Random value to the servers SHOULD, set the last 8 bytes of their ServerHello.Random
bytes: value to the bytes:
44 4F 57 4E 47 52 44 00 44 4F 57 4E 47 52 44 00
TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below TLS 1.3 clients receiving a ServerHello indicating TLS 1.2 or below
MUST check that the last eight bytes are not equal to either of these MUST check that the last 8 bytes are not equal to either of these
values. TLS 1.2 clients SHOULD also check that the last eight bytes values. TLS 1.2 clients SHOULD also check that the last 8 bytes are
are not equal to the second value if the ServerHello indicates TLS not equal to the second value if the ServerHello indicates TLS 1.1 or
1.1 or below. If a match is found, the client MUST abort the below. If a match is found, the client MUST abort the handshake with
handshake with an "illegal_parameter" alert. This mechanism provides an "illegal_parameter" alert. This mechanism provides limited
limited protection against downgrade attacks over and above what is protection against downgrade attacks over and above what is provided
provided by the Finished exchange: because the ServerKeyExchange, a by the Finished exchange: because the ServerKeyExchange, a message
message present in TLS 1.2 and below, includes a signature over both present in TLS 1.2 and below, includes a signature over both random
random values, it is not possible for an active attacker to modify values, it is not possible for an active attacker to modify the
the random values without detection as long as ephemeral ciphers are random values without detection as long as ephemeral ciphers are
used. It does not provide downgrade protection when static RSA is used. It does not provide downgrade protection when static RSA
used. is used.
Note: This is a change from [RFC5246], so in practice many TLS 1.2 Note: This is a change from [RFC5246], so in practice many TLS 1.2
clients and servers will not behave as specified above. clients and servers will not behave as specified above.
A legacy TLS client performing renegotiation with TLS 1.2 or prior A legacy TLS client performing renegotiation with TLS 1.2 or prior
and which receives a TLS 1.3 ServerHello during renegotiation MUST and which receives a TLS 1.3 ServerHello during renegotiation MUST
abort the handshake with a "protocol_version" alert. Note that abort the handshake with a "protocol_version" alert. Note that
renegotiation is not possible when TLS 1.3 has been negotiated. renegotiation is not possible when TLS 1.3 has been negotiated.
RFC EDITOR: PLEASE REMOVE THE FOLLOWING PARAGRAPH Implementations of
draft versions (see Section 4.2.1.1) of this specification SHOULD NOT
implement this mechanism on either client and server. A pre-RFC
client connecting to RFC servers, or vice versa, will appear to
downgrade to TLS 1.2. With the mechanism enabled, this will cause an
interoperability failure.
4.1.4. Hello Retry Request 4.1.4. Hello Retry Request
The server will send this message in response to a ClientHello The server will send this message in response to a ClientHello
message if it is able to find an acceptable set of parameters but the message if it is able to find an acceptable set of parameters but the
ClientHello does not contain sufficient information to proceed with ClientHello does not contain sufficient information to proceed with
the handshake. As discussed in Section 4.1.3, the HelloRetryRequest the handshake. As discussed in Section 4.1.3, the HelloRetryRequest
has the same format as a ServerHello message, and the legacy_version, has the same format as a ServerHello message, and the legacy_version,
legacy_session_id_echo, cipher_suite, and legacy_compression methods legacy_session_id_echo, cipher_suite, and legacy_compression_method
fields have the same meaning. However, for convenience we discuss fields have the same meaning. However, for convenience we discuss
HelloRetryRequest throughout this document as if it were a distinct "HelloRetryRequest" throughout this document as if it were a distinct
message. message.
The server's extensions MUST contain "supported_versions" and The server's extensions MUST contain "supported_versions".
otherwise the server SHOULD send only the extensions necessary for Additionally, it SHOULD contain the minimal set of extensions
the client to generate a correct ClientHello pair. As with necessary for the client to generate a correct ClientHello pair. As
ServerHello, a HelloRetryRequest MUST NOT contain any extensions that with the ServerHello, a HelloRetryRequest MUST NOT contain any
were not first offered by the client in its ClientHello, with the extensions that were not first offered by the client in its
exception of optionally the "cookie" (see Section 4.2.2) extension. ClientHello, with the exception of optionally the "cookie" (see
Section 4.2.2) extension.
Upon receipt of a HelloRetryRequest, the client MUST check the Upon receipt of a HelloRetryRequest, the client MUST check the
legacy_version, legacy_session_id_echo, cipher_suite, and legacy_version, legacy_session_id_echo, cipher_suite, and
legacy_compression_method as specified in Section 4.1.3 and then legacy_compression_method as specified in Section 4.1.3 and then
process the extensions, starting with determining the version using process the extensions, starting with determining the version using
"supported_versions". Clients MUST abort the handshake with an "supported_versions". Clients MUST abort the handshake with an
"illegal_parameter" alert if the HelloRetryRequest would not result "illegal_parameter" alert if the HelloRetryRequest would not result
in any change in the ClientHello. If a client receives a second in any change in the ClientHello. If a client receives a second
HelloRetryRequest in the same connection (i.e., where the ClientHello HelloRetryRequest in the same connection (i.e., where the ClientHello
was itself in response to a HelloRetryRequest), it MUST abort the was itself in response to a HelloRetryRequest), it MUST abort the
skipping to change at page 39, line 36 skipping to change at page 34, line 15
Otherwise, the client MUST process all extensions in the Otherwise, the client MUST process all extensions in the
HelloRetryRequest and send a second updated ClientHello. The HelloRetryRequest and send a second updated ClientHello. The
HelloRetryRequest extensions defined in this specification are: HelloRetryRequest extensions defined in this specification are:
- supported_versions (see Section 4.2.1) - supported_versions (see Section 4.2.1)
- cookie (see Section 4.2.2) - cookie (see Section 4.2.2)
- key_share (see Section 4.2.8) - key_share (see Section 4.2.8)
A client which receives a cipher suite that was not offered MUST
abort the handshake. Servers MUST ensure that they negotiate the
same cipher suite when receiving a conformant updated ClientHello (if
the server selects the cipher suite as the first step in the
negotiation, then this will happen automatically). Upon receiving
the ServerHello, clients MUST check that the cipher suite supplied in
the ServerHello is the same as that in the HelloRetryRequest and
otherwise abort the handshake with an "illegal_parameter" alert.
In addition, in its updated ClientHello, the client SHOULD NOT offer In addition, in its updated ClientHello, the client SHOULD NOT offer
any pre-shared keys associated with a hash other than that of the any pre-shared keys associated with a hash other than that of the
selected cipher suite. This allows the client to avoid having to selected cipher suite. This allows the client to avoid having to
compute partial hash transcripts for multiple hashes in the second compute partial hash transcripts for multiple hashes in the second
ClientHello. A client which receives a cipher suite that was not ClientHello.
offered MUST abort the handshake. Servers MUST ensure that they
negotiate the same cipher suite when receiving a conformant updated
ClientHello (if the server selects the cipher suite as the first step
in the negotiation, then this will happen automatically). Upon
receiving the ServerHello, clients MUST check that the cipher suite
supplied in the ServerHello is the same as that in the
HelloRetryRequest and otherwise abort the handshake with an
"illegal_parameter" alert.
The value of selected_version in the HelloRetryRequest The value of selected_version in the HelloRetryRequest
"supported_versions" extension MUST be retained in the ServerHello, "supported_versions" extension MUST be retained in the ServerHello,
and a client MUST abort the handshake with an "illegal_parameter" and a client MUST abort the handshake with an "illegal_parameter"
alert if the value changes. alert if the value changes.
4.2. Extensions 4.2. Extensions
A number of TLS messages contain tag-length-value encoded extensions A number of TLS messages contain tag-length-value encoded extensions
structures. structures.
struct { struct {
ExtensionType extension_type; ExtensionType extension_type;
opaque extension_data<0..2^16-1>; opaque extension_data<0..2^16-1>;
} Extension; } Extension;
enum { enum {
server_name(0), /* RFC 6066 */ server_name(0), /* RFC 6066 */
max_fragment_length(1), /* RFC 6066 */ max_fragment_length(1), /* RFC 6066 */
status_request(5), /* RFC 6066 */ status_request(5), /* RFC 6066 */
supported_groups(10), /* RFC 4492, 7919 */ supported_groups(10), /* RFC 8422, 7919 */
signature_algorithms(13), /* [[this document]] */ signature_algorithms(13), /* RFC 8446 */
use_srtp(14), /* RFC 5764 */ use_srtp(14), /* RFC 5764 */
heartbeat(15), /* RFC 6520 */ heartbeat(15), /* RFC 6520 */
application_layer_protocol_negotiation(16), /* RFC 7301 */ application_layer_protocol_negotiation(16), /* RFC 7301 */
signed_certificate_timestamp(18), /* RFC 6962 */ signed_certificate_timestamp(18), /* RFC 6962 */
client_certificate_type(19), /* RFC 7250 */ client_certificate_type(19), /* RFC 7250 */
server_certificate_type(20), /* RFC 7250 */ server_certificate_type(20), /* RFC 7250 */
padding(21), /* RFC 7685 */ padding(21), /* RFC 7685 */
pre_shared_key(41), /* [[this document]] */ pre_shared_key(41), /* RFC 8446 */
early_data(42), /* [[this document]] */ early_data(42), /* RFC 8446 */
supported_versions(43), /* [[this document]] */ supported_versions(43), /* RFC 8446 */
cookie(44), /* [[this document]] */ cookie(44), /* RFC 8446 */
psk_key_exchange_modes(45), /* [[this document]] */ psk_key_exchange_modes(45), /* RFC 8446 */
certificate_authorities(47), /* [[this document]] */ certificate_authorities(47), /* RFC 8446 */
oid_filters(48), /* [[this document]] */ oid_filters(48), /* RFC 8446 */
post_handshake_auth(49), /* [[this document]] */ post_handshake_auth(49), /* RFC 8446 */
signature_algorithms_cert(50), /* [[this document]] */ signature_algorithms_cert(50), /* RFC 8446 */
key_share(51), /* [[this document]] */ key_share(51), /* RFC 8446 */
(65535) (65535)
} ExtensionType; } ExtensionType;
Here: Here:
- "extension_type" identifies the particular extension type. - "extension_type" identifies the particular extension type.
- "extension_data" contains information specific to the particular - "extension_data" contains information specific to the particular
extension type. extension type.
The list of extension types is maintained by IANA as described in The list of extension types is maintained by IANA as described in
Section 11. Section 11.
Extensions are generally structured in a request/response fashion, Extensions are generally structured in a request/response fashion,
though some extensions are just indications with no corresponding though some extensions are just indications with no corresponding
response. The client sends its extension requests in the ClientHello response. The client sends its extension requests in the ClientHello
message and the server sends its extension responses in the message, and the server sends its extension responses in the
ServerHello, EncryptedExtensions, HelloRetryRequest and Certificate ServerHello, EncryptedExtensions, HelloRetryRequest, and Certificate
messages. The server sends extension requests in the messages. The server sends extension requests in the
CertificateRequest message which a client MAY respond to with a CertificateRequest message which a client MAY respond to with a
Certificate message. The server MAY also send unsolicited extensions Certificate message. The server MAY also send unsolicited extensions
in the NewSessionTicket, though the client does not respond directly in the NewSessionTicket, though the client does not respond directly
to these. to these.
Implementations MUST NOT send extension responses if the remote Implementations MUST NOT send extension responses if the remote
endpoint did not send the corresponding extension requests, with the endpoint did not send the corresponding extension requests, with the
exception of the "cookie" extension in HelloRetryRequest. Upon exception of the "cookie" extension in the HelloRetryRequest. Upon
receiving such an extension, an endpoint MUST abort the handshake receiving such an extension, an endpoint MUST abort the handshake
with an "unsupported_extension" alert. with an "unsupported_extension" alert.
The table below indicates the messages where a given extension may The table below indicates the messages where a given extension may
appear, using the following notation: CH (ClientHello), SH appear, using the following notation: CH (ClientHello),
(ServerHello), EE (EncryptedExtensions), CT (Certificate), CR SH (ServerHello), EE (EncryptedExtensions), CT (Certificate),
(CertificateRequest), NST (NewSessionTicket) and HRR CR (CertificateRequest), NST (NewSessionTicket), and
(HelloRetryRequest). If an implementation receives an extension HRR (HelloRetryRequest). If an implementation receives an extension
which it recognizes and which is not specified for the message in which it recognizes and which is not specified for the message in
which it appears it MUST abort the handshake with an which it appears, it MUST abort the handshake with an
"illegal_parameter" alert. "illegal_parameter" alert.
+--------------------------------------------------+-------------+ +--------------------------------------------------+-------------+
| Extension | TLS 1.3 | | Extension | TLS 1.3 |
+--------------------------------------------------+-------------+ +--------------------------------------------------+-------------+
| server_name [RFC6066] | CH, EE | | server_name [RFC6066] | CH, EE |
| | | | | |
| max_fragment_length [RFC6066] | CH, EE | | max_fragment_length [RFC6066] | CH, EE |
| | | | | |
| status_request [RFC6066] | CH, CR, CT | | status_request [RFC6066] | CH, CR, CT |
| | | | | |
| supported_groups [RFC7919] | CH, EE | | supported_groups [RFC7919] | CH, EE |
| | | | | |
| signature_algorithms [RFC5246] | CH, CR | | signature_algorithms (RFC 8446) | CH, CR |
| | | | | |
| use_srtp [RFC5764] | CH, EE | | use_srtp [RFC5764] | CH, EE |
| | | | | |
| heartbeat [RFC6520] | CH, EE | | heartbeat [RFC6520] | CH, EE |
| | | | | |
| application_layer_protocol_negotiation [RFC7301] | CH, EE | | application_layer_protocol_negotiation [RFC7301] | CH, EE |
| | | | | |
| signed_certificate_timestamp [RFC6962] | CH, CR, CT | | signed_certificate_timestamp [RFC6962] | CH, CR, CT |
| | | | | |
| client_certificate_type [RFC7250] | CH, EE | | client_certificate_type [RFC7250] | CH, EE |
| | | | | |
| server_certificate_type [RFC7250] | CH, EE | | server_certificate_type [RFC7250] | CH, EE |
| | | | | |
| padding [RFC7685] | CH | | padding [RFC7685] | CH |
| | | | | |
| key_share [[this document]] | CH, SH, HRR | | key_share (RFC 8446) | CH, SH, HRR |
| | | | | |
| pre_shared_key [[this document]] | CH, SH | | pre_shared_key (RFC 8446) | CH, SH |
| | | | | |
| psk_key_exchange_modes [[this document]] | CH | | psk_key_exchange_modes (RFC 8446) | CH |
| | | | | |
| early_data [[this document]] | CH, EE, NST | | early_data (RFC 8446) | CH, EE, NST |
| | | | | |
| cookie [[this document]] | CH, HRR | | cookie (RFC 8446) | CH, HRR |
| | | | | |
| supported_versions [[this document]] | CH, SH, HRR | | supported_versions (RFC 8446) | CH, SH, HRR |
| | | | | |
| certificate_authorities [[this document]] | CH, CR | | certificate_authorities (RFC 8446) | CH, CR |
| | | | | |
| oid_filters [[this document]] | CR | | oid_filters (RFC 8446) | CR |
| | | | | |
| post_handshake_auth [[this document]] | CH | | post_handshake_auth (RFC 8446) | CH |
| | | | | |
| signature_algorithms_cert [[this document]] | CH, CR | | signature_algorithms_cert (RFC 8446) | CH, CR |
+--------------------------------------------------+-------------+ +--------------------------------------------------+-------------+
When multiple extensions of different types are present, the When multiple extensions of different types are present, the
extensions MAY appear in any order, with the exception of extensions MAY appear in any order, with the exception of
"pre_shared_key" Section 4.2.11 which MUST be the last extension in "pre_shared_key" (Section 4.2.11) which MUST be the last extension in
the ClientHello. There MUST NOT be more than one extension of the the ClientHello (but can appear anywhere in the ServerHello
extensions block). There MUST NOT be more than one extension of the
same type in a given extension block. same type in a given extension block.
In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each In TLS 1.3, unlike TLS 1.2, extensions are negotiated for each
handshake even when in resumption-PSK mode. However, 0-RTT handshake even when in resumption-PSK mode. However, 0-RTT
parameters are those negotiated in the previous handshake; mismatches parameters are those negotiated in the previous handshake; mismatches
may require rejecting 0-RTT (see Section 4.2.10). may require rejecting 0-RTT (see Section 4.2.10).
There are subtle (and not so subtle) interactions that may occur in There are subtle (and not so subtle) interactions that may occur in
this protocol between new features and existing features which may this protocol between new features and existing features which may
result in a significant reduction in overall security. The following result in a significant reduction in overall security. The following
skipping to change at page 44, line 16 skipping to change at page 39, line 28
which versions of TLS it supports and by the server to indicate which which versions of TLS it supports and by the server to indicate which
version it is using. The extension contains a list of supported version it is using. The extension contains a list of supported
versions in preference order, with the most preferred version first. versions in preference order, with the most preferred version first.
Implementations of this specification MUST send this extension in the Implementations of this specification MUST send this extension in the
ClientHello containing all versions of TLS which they are prepared to ClientHello containing all versions of TLS which they are prepared to
negotiate (for this specification, that means minimally 0x0304, but negotiate (for this specification, that means minimally 0x0304, but
if previous versions of TLS are allowed to be negotiated, they MUST if previous versions of TLS are allowed to be negotiated, they MUST
be present as well). be present as well).
If this extension is not present, servers which are compliant with If this extension is not present, servers which are compliant with
this specification, and which also support TLS 1.2, MUST negotiate this specification and which also support TLS 1.2 MUST negotiate
TLS 1.2 or prior as specified in [RFC5246], even if TLS 1.2 or prior as specified in [RFC5246], even if
ClientHello.legacy_version is 0x0304 or later. Servers MAY abort the ClientHello.legacy_version is 0x0304 or later. Servers MAY abort the
handshake upon receiving a ClientHello with legacy_version 0x0304 or handshake upon receiving a ClientHello with legacy_version 0x0304 or
later. later.
If this extension is present in the ClientHello, servers MUST NOT use If this extension is present in the ClientHello, servers MUST NOT use
the ClientHello.legacy_version value for version negotiation and MUST the ClientHello.legacy_version value for version negotiation and MUST
use only the "supported_versions" extension to determine client use only the "supported_versions" extension to determine client
preferences. Servers MUST only select a version of TLS present in preferences. Servers MUST only select a version of TLS present in
that extension and MUST ignore any unknown versions that are present that extension and MUST ignore any unknown versions that are present
skipping to change at page 44, line 46 skipping to change at page 40, line 9
extension. A server which negotiates TLS 1.3 MUST respond by sending extension. A server which negotiates TLS 1.3 MUST respond by sending
a "supported_versions" extension containing the selected version a "supported_versions" extension containing the selected version
value (0x0304). It MUST set the ServerHello.legacy_version field to value (0x0304). It MUST set the ServerHello.legacy_version field to
0x0303 (TLS 1.2). Clients MUST check for this extension prior to 0x0303 (TLS 1.2). Clients MUST check for this extension prior to
processing the rest of the ServerHello (although they will have to processing the rest of the ServerHello (although they will have to
parse the ServerHello in order to read the extension). If this parse the ServerHello in order to read the extension). If this
extension is present, clients MUST ignore the extension is present, clients MUST ignore the
ServerHello.legacy_version value and MUST use only the ServerHello.legacy_version value and MUST use only the
"supported_versions" extension to determine the selected version. If "supported_versions" extension to determine the selected version. If
the "supported_versions" extension in the ServerHello contains a the "supported_versions" extension in the ServerHello contains a
version not offered by the client or contains a version prior to TLS version not offered by the client or contains a version prior to
1.3, the client MUST abort the handshake with an "illegal_parameter" TLS 1.3, the client MUST abort the handshake with an
alert. "illegal_parameter" alert.
4.2.1.1. Draft Version Indicator
RFC EDITOR: PLEASE REMOVE THIS SECTION
While the eventual version indicator for the RFC version of TLS 1.3
will be 0x0304, implementations of draft versions of this
specification SHOULD instead advertise 0x7f00 | draft_version in the
ServerHello and HelloRetryRequest "supported_versions" extension.
For instance, draft-17 would be encoded as the 0x7f11. This allows
pre-RFC implementations to safely negotiate with each other, even if
they would otherwise be incompatible.
4.2.2. Cookie 4.2.2. Cookie
struct { struct {
opaque cookie<1..2^16-1>; opaque cookie<1..2^16-1>;
} Cookie; } Cookie;
Cookies serve two primary purposes: Cookies serve two primary purposes:
- Allowing the server to force the client to demonstrate - Allowing the server to force the client to demonstrate
reachability at their apparent network address (thus providing a reachability at their apparent network address (thus providing a
measure of DoS protection). This is primarily useful for non- measure of DoS protection). This is primarily useful for
connection-oriented transports (see [RFC6347] for an example of non-connection-oriented transports (see [RFC6347] for an example
this). of this).
- Allowing the server to offload state to the client, thus allowing - Allowing the server to offload state to the client, thus allowing
it to send a HelloRetryRequest without storing any state. The it to send a HelloRetryRequest without storing any state. The
server can do this by storing the hash of the ClientHello in the server can do this by storing the hash of the ClientHello in the
HelloRetryRequest cookie (protected with some suitable integrity HelloRetryRequest cookie (protected with some suitable integrity
algorithm). protection algorithm).
When sending a HelloRetryRequest, the server MAY provide a "cookie" When sending a HelloRetryRequest, the server MAY provide a "cookie"
extension to the client (this is an exception to the usual rule that extension to the client (this is an exception to the usual rule that
the only extensions that may be sent are those that appear in the the only extensions that may be sent are those that appear in the
ClientHello). When sending the new ClientHello, the client MUST copy ClientHello). When sending the new ClientHello, the client MUST copy
the contents of the extension received in the HelloRetryRequest into the contents of the extension received in the HelloRetryRequest into
a "cookie" extension in the new ClientHello. Clients MUST NOT use a "cookie" extension in the new ClientHello. Clients MUST NOT use
cookies in their initial ClientHello in subsequent connections. cookies in their initial ClientHello in subsequent connections.
When a server is operating statelessly it may receive an unprotected When a server is operating statelessly, it may receive an unprotected
record of type change_cipher_spec between the first and second record of type change_cipher_spec between the first and second
ClientHello (see Section 5). Since the server is not storing any ClientHello (see Section 5). Since the server is not storing any
state this will appear as if it were the first message to be state, this will appear as if it were the first message to be
received. Servers operating statelessly MUST ignore these records. received. Servers operating statelessly MUST ignore these records.
4.2.3. Signature Algorithms 4.2.3. Signature Algorithms
TLS 1.3 provides two extensions for indicating which signature TLS 1.3 provides two extensions for indicating which signature
algorithms may be used in digital signatures. The algorithms may be used in digital signatures. The
"signature_algorithms_cert" extension applies to signatures in "signature_algorithms_cert" extension applies to signatures in
certificates and the "signature_algorithms" extension, which certificates, and the "signature_algorithms" extension, which
originally appeared in TLS 1.2, applies to signatures in originally appeared in TLS 1.2, applies to signatures in
CertificateVerify messages. The keys found in certificates MUST also CertificateVerify messages. The keys found in certificates MUST also
be of appropriate type for the signature algorithms they are used be of appropriate type for the signature algorithms they are used
with. This is a particular issue for RSA keys and PSS signatures, as with. This is a particular issue for RSA keys and PSS signatures, as
described below. If no "signature_algorithms_cert" extension is described below. If no "signature_algorithms_cert" extension is
present, then the "signature_algorithms" extension also applies to present, then the "signature_algorithms" extension also applies to
signatures appearing in certificates. Clients which desire the signatures appearing in certificates. Clients which desire the
server to authenticate itself via a certificate MUST send server to authenticate itself via a certificate MUST send the
"signature_algorithms". If a server is authenticating via a "signature_algorithms" extension. If a server is authenticating via
certificate and the client has not sent a "signature_algorithms" a certificate and the client has not sent a "signature_algorithms"
extension, then the server MUST abort the handshake with a extension, then the server MUST abort the handshake with a
"missing_extension" alert (see Section 9.2). "missing_extension" alert (see Section 9.2).
The "signature_algorithms_cert" extension was added to allow The "signature_algorithms_cert" extension was added to allow
implementations which supported different sets of algorithms for implementations which supported different sets of algorithms for
certificates and in TLS itself to clearly signal their capabilities. certificates and in TLS itself to clearly signal their capabilities.
TLS 1.2 implementations SHOULD also process this extension. TLS 1.2 implementations SHOULD also process this extension.
Implementations which have the same policy in both cases MAY omit the Implementations which have the same policy in both cases MAY omit the
"signature_algorithms_cert" extension. "signature_algorithms_cert" extension.
skipping to change at page 48, line 7 skipping to change at page 43, line 14
Each SignatureScheme value lists a single signature algorithm that Each SignatureScheme value lists a single signature algorithm that
the client is willing to verify. The values are indicated in the client is willing to verify. The values are indicated in
descending order of preference. Note that a signature algorithm descending order of preference. Note that a signature algorithm
takes as input an arbitrary-length message, rather than a digest. takes as input an arbitrary-length message, rather than a digest.
Algorithms which traditionally act on a digest should be defined in Algorithms which traditionally act on a digest should be defined in
TLS to first hash the input with a specified hash algorithm and then TLS to first hash the input with a specified hash algorithm and then
proceed as usual. The code point groups listed above have the proceed as usual. The code point groups listed above have the
following meanings: following meanings:
RSASSA-PKCS1-v1_5 algorithms Indicates a signature algorithm using RSASSA-PKCS1-v1_5 algorithms: Indicates a signature algorithm using
RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm RSASSA-PKCS1-v1_5 [RFC8017] with the corresponding hash algorithm
as defined in [SHS]. These values refer solely to signatures as defined in [SHS]. These values refer solely to signatures
which appear in certificates (see Section 4.4.2.2) and are not which appear in certificates (see Section 4.4.2.2) and are not
defined for use in signed TLS handshake messages, although they defined for use in signed TLS handshake messages, although they
MAY appear in "signature_algorithms" and MAY appear in "signature_algorithms" and
"signature_algorithms_cert" for backward compatibility with TLS "signature_algorithms_cert" for backward compatibility with
1.2, TLS 1.2.
ECDSA algorithms Indicates a signature algorithm using ECDSA ECDSA algorithms: Indicates a signature algorithm using ECDSA
[ECDSA], the corresponding curve as defined in ANSI X9.62 [X962] [ECDSA], the corresponding curve as defined in ANSI X9.62 [ECDSA]
and FIPS 186-4 [DSS], and the corresponding hash algorithm as and FIPS 186-4 [DSS], and the corresponding hash algorithm as
defined in [SHS]. The signature is represented as a DER-encoded defined in [SHS]. The signature is represented as a DER-encoded
[X690] ECDSA-Sig-Value structure. [X690] ECDSA-Sig-Value structure.
RSASSA-PSS RSAE algorithms Indicates a signature algorithm using RSASSA-PSS RSAE algorithms: Indicates a signature algorithm using
RSASSA-PSS [RFC8017] with mask generation function 1. The digest RSASSA-PSS [RFC8017] with mask generation function 1. The digest
used in the mask generation function and the digest being signed used in the mask generation function and the digest being signed
are both the corresponding hash algorithm as defined in [SHS]. are both the corresponding hash algorithm as defined in [SHS].
The length of the salt MUST be equal to the length of the output The length of the Salt MUST be equal to the length of the output
of the digest algorithm. If the public key is carried in an X.509 of the digest algorithm. If the public key is carried in an X.509
certificate, it MUST use the rsaEncryption OID [RFC5280]. certificate, it MUST use the rsaEncryption OID [RFC5280].
EdDSA algorithms Indicates a signature algorithm using EdDSA as EdDSA algorithms: Indicates a signature algorithm using EdDSA as
defined in [RFC8032] or its successors. Note that these defined in [RFC8032] or its successors. Note that these
correspond to the "PureEdDSA" algorithms and not the "prehash" correspond to the "PureEdDSA" algorithms and not the "prehash"
variants. variants.
RSASSA-PSS PSS algorithms Indicates a signature algorithm using RSASSA-PSS PSS algorithms: Indicates a signature algorithm using
RSASSA-PSS [RFC8017] with mask generation function 1. The digest RSASSA-PSS [RFC8017] with mask generation function 1. The digest
used in the mask generation function and the digest being signed used in the mask generation function and the digest being signed
are both the corresponding hash algorithm as defined in [SHS]. are both the corresponding hash algorithm as defined in [SHS].
The length of the salt MUST be equal to the length of the digest The length of the Salt MUST be equal to the length of the digest
algorithm. If the public key is carried in an X.509 certificate, algorithm. If the public key is carried in an X.509 certificate,
it MUST use the RSASSA-PSS OID [RFC5756]. When used in it MUST use the RSASSA-PSS OID [RFC5756]. When used in
certificate signatures, the algorithm parameters MUST be DER certificate signatures, the algorithm parameters MUST be DER
encoded. If the corresponding public key's parameters are encoded. If the corresponding public key's parameters are
present, then the parameters in the signature MUST be identical to present, then the parameters in the signature MUST be identical to
those in the public key. those in the public key.
Legacy algorithms Indicates algorithms which are being deprecated Legacy algorithms: Indicates algorithms which are being deprecated
because they use algorithms with known weaknesses, specifically because they use algorithms with known weaknesses, specifically
SHA-1 which is used in this context with either with RSA using SHA-1 which is used in this context with either (1) RSA using
RSASSA-PKCS1-v1_5 or ECDSA. These values refer solely to RSASSA-PKCS1-v1_5 or (2) ECDSA. These values refer solely to
signatures which appear in certificates (see Section 4.4.2.2) and signatures which appear in certificates (see Section 4.4.2.2) and
are not defined for use in signed TLS handshake messages, although are not defined for use in signed TLS handshake messages, although
they MAY appear in "signature_algorithms" and they MAY appear in "signature_algorithms" and
"signature_algorithms_cert" for backward compatibility with TLS "signature_algorithms_cert" for backward compatibility with
1.2, Endpoints SHOULD NOT negotiate these algorithms but are TLS 1.2. Endpoints SHOULD NOT negotiate these algorithms but are
permitted to do so solely for backward compatibility. Clients permitted to do so solely for backward compatibility. Clients
offering these values MUST list them as the lowest priority offering these values MUST list them as the lowest priority
(listed after all other algorithms in SignatureSchemeList). TLS (listed after all other algorithms in SignatureSchemeList).
1.3 servers MUST NOT offer a SHA-1 signed certificate unless no TLS 1.3 servers MUST NOT offer a SHA-1 signed certificate unless
valid certificate chain can be produced without it (see no valid certificate chain can be produced without it (see
Section 4.4.2.2). Section 4.4.2.2).
The signatures on certificates that are self-signed or certificates The signatures on certificates that are self-signed or certificates
that are trust anchors are not validated since they begin a that are trust anchors are not validated, since they begin a
certification path (see [RFC5280], Section 3.2). A certificate that certification path (see [RFC5280], Section 3.2). A certificate that
begins a certification path MAY use a signature algorithm that is not begins a certification path MAY use a signature algorithm that is not
advertised as being supported in the "signature_algorithms" advertised as being supported in the "signature_algorithms"
extension. extension.
Note that TLS 1.2 defines this extension differently. TLS 1.3 Note that TLS 1.2 defines this extension differently. TLS 1.3
implementations willing to negotiate TLS 1.2 MUST behave in implementations willing to negotiate TLS 1.2 MUST behave in
accordance with the requirements of [RFC5246] when negotiating that accordance with the requirements of [RFC5246] when negotiating that
version. In particular: version. In particular:
- TLS 1.2 ClientHellos MAY omit this extension. - TLS 1.2 ClientHellos MAY omit this extension.
- In TLS 1.2, the extension contained hash/signature pairs. The - In TLS 1.2, the extension contained hash/signature pairs. The
pairs are encoded in two octets, so SignatureScheme values have pairs are encoded in two octets, so SignatureScheme values have
been allocated to align with TLS 1.2's encoding. Some legacy been allocated to align with TLS 1.2's encoding. Some legacy
pairs are left unallocated. These algorithms are deprecated as of pairs are left unallocated. These algorithms are deprecated as of
TLS 1.3. They MUST NOT be offered or negotiated by any TLS 1.3. They MUST NOT be offered or negotiated by any
implementation. In particular, MD5 [SLOTH], SHA-224, and DSA MUST implementation. In particular, MD5 [SLOTH], SHA-224, and DSA
NOT be used. MUST NOT be used.
- ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature - ECDSA signature schemes align with TLS 1.2's ECDSA hash/signature
pairs. However, the old semantics did not constrain the signing pairs. However, the old semantics did not constrain the signing
curve. If TLS 1.2 is negotiated, implementations MUST be prepared curve. If TLS 1.2 is negotiated, implementations MUST be prepared
to accept a signature that uses any curve that they advertised in to accept a signature that uses any curve that they advertised in
the "supported_groups" extension. the "supported_groups" extension.
- Implementations that advertise support for RSASSA-PSS (which is - Implementations that advertise support for RSASSA-PSS (which is
mandatory in TLS 1.3), MUST be prepared to accept a signature mandatory in TLS 1.3) MUST be prepared to accept a signature using
using that scheme even when TLS 1.2 is negotiated. In TLS 1.2, that scheme even when TLS 1.2 is negotiated. In TLS 1.2,
RSASSA-PSS is used with RSA cipher suites. RSASSA-PSS is used with RSA cipher suites.
4.2.4. Certificate Authorities 4.2.4. Certificate Authorities
The "certificate_authorities" extension is used to indicate the The "certificate_authorities" extension is used to indicate the
certificate authorities which an endpoint supports and which SHOULD certificate authorities (CAs) which an endpoint supports and which
be used by the receiving endpoint to guide certificate selection. SHOULD be used by the receiving endpoint to guide certificate
selection.
The body of the "certificate_authorities" extension consists of a The body of the "certificate_authorities" extension consists of a
CertificateAuthoritiesExtension structure. CertificateAuthoritiesExtension structure.
opaque DistinguishedName<1..2^16-1>; opaque DistinguishedName<1..2^16-1>;
struct { struct {
DistinguishedName authorities<3..2^16-1>; DistinguishedName authorities<3..2^16-1>;
} CertificateAuthoritiesExtension; } CertificateAuthoritiesExtension;
authorities A list of the distinguished names [X501] of acceptable authorities: A list of the distinguished names [X501] of acceptable
certificate authorities, represented in DER-encoded [X690] format. certificate authorities, represented in DER-encoded [X690] format.
These distinguished names specify a desired distinguished name for These distinguished names specify a desired distinguished name for
trust anchor or subordinate CA; thus, this message can be used to a trust anchor or subordinate CA; thus, this message can be used
describe known trust anchors as well as a desired authorization to describe known trust anchors as well as a desired authorization
space. space.
The client MAY send the "certificate_authorities" extension in the The client MAY send the "certificate_authorities" extension in the
ClientHello message. The server MAY send it in the ClientHello message. The server MAY send it in the
CertificateRequest message. CertificateRequest message.
The "trusted_ca_keys" extension, which serves a similar purpose The "trusted_ca_keys" extension [RFC6066], which serves a similar
[RFC6066], but is more complicated, is not used in TLS 1.3 (although purpose but is more complicated, is not used in TLS 1.3 (although it
it may appear in ClientHello messages from clients which are offering may appear in ClientHello messages from clients which are offering
prior versions of TLS). prior versions of TLS).
4.2.5. OID Filters 4.2.5. OID Filters
The "oid_filters" extension allows servers to provide a set of OID/ The "oid_filters" extension allows servers to provide a set of
value pairs which it would like the client's certificate to match. OID/value pairs which it would like the client's certificate to
This extension, if provided by the server, MUST only be sent in the match. This extension, if provided by the server, MUST only be sent
CertificateRequest message. in the CertificateRequest message.
struct { struct {
opaque certificate_extension_oid<1..2^8-1>; opaque certificate_extension_oid<1..2^8-1>;
opaque certificate_extension_values<0..2^16-1>; opaque certificate_extension_values<0..2^16-1>;
} OIDFilter; } OIDFilter;
struct { struct {
OIDFilter filters<0..2^16-1>; OIDFilter filters<0..2^16-1>;
} OIDFilterExtension; } OIDFilterExtension;
filters A list of certificate extension OIDs [RFC5280] with their filters: A list of certificate extension OIDs [RFC5280] with their
allowed value(s) and represented in DER-encoded [X690] format. allowed value(s) and represented in DER-encoded [X690] format.
Some certificate extension OIDs allow multiple values (e.g., Some certificate extension OIDs allow multiple values (e.g.,
Extended Key Usage). If the server has included a non-empty Extended Key Usage). If the server has included a non-empty
filters list, the client certificate included in the response MUST filters list, the client certificate included in the response MUST
contain all of the specified extension OIDs that the client contain all of the specified extension OIDs that the client
recognizes. For each extension OID recognized by the client, all recognizes. For each extension OID recognized by the client, all
of the specified values MUST be present in the client certificate of the specified values MUST be present in the client certificate
(but the certificate MAY have other values as well). However, the (but the certificate MAY have other values as well). However, the
client MUST ignore and skip any unrecognized certificate extension client MUST ignore and skip any unrecognized certificate extension
OIDs. If the client ignored some of the required certificate OIDs. If the client ignored some of the required certificate
extension OIDs and supplied a certificate that does not satisfy extension OIDs and supplied a certificate that does not satisfy
the request, the server MAY at its discretion either continue the the request, the server MAY at its discretion either continue the
connection without client authentication, or abort the handshake connection without client authentication or abort the handshake
with an "unsupported_certificate" alert. Any given OID MUST NOT with an "unsupported_certificate" alert. Any given OID MUST NOT
appear more than once in the filters list. appear more than once in the filters list.
PKIX RFCs define a variety of certificate extension OIDs and their PKIX RFCs define a variety of certificate extension OIDs and their
corresponding value types. Depending on the type, matching corresponding value types. Depending on the type, matching
certificate extension values are not necessarily bitwise-equal. It certificate extension values are not necessarily bitwise-equal. It
is expected that TLS implementations will rely on their PKI libraries is expected that TLS implementations will rely on their PKI libraries
to perform certificate selection using certificate extension OIDs. to perform certificate selection using certificate extension OIDs.
This document defines matching rules for two standard certificate This document defines matching rules for two standard certificate
skipping to change at page 52, line 8 skipping to change at page 47, line 18
is willing to perform post-handshake authentication (Section 4.6.2). is willing to perform post-handshake authentication (Section 4.6.2).
Servers MUST NOT send a post-handshake CertificateRequest to clients Servers MUST NOT send a post-handshake CertificateRequest to clients
which do not offer this extension. Servers MUST NOT send this which do not offer this extension. Servers MUST NOT send this
extension. extension.
struct {} PostHandshakeAuth; struct {} PostHandshakeAuth;
The "extension_data" field of the "post_handshake_auth" extension is The "extension_data" field of the "post_handshake_auth" extension is
zero length. zero length.
4.2.7. Negotiated Groups 4.2.7. Supported Groups
When sent by the client, the "supported_groups" extension indicates When sent by the client, the "supported_groups" extension indicates
the named groups which the client supports for key exchange, ordered the named groups which the client supports for key exchange, ordered
from most preferred to least preferred. from most preferred to least preferred.
Note: In versions of TLS prior to TLS 1.3, this extension was named Note: In versions of TLS prior to TLS 1.3, this extension was named
"elliptic_curves" and only contained elliptic curve groups. See "elliptic_curves" and only contained elliptic curve groups. See
[RFC4492] and [RFC7919]. This extension was also used to negotiate [RFC8422] and [RFC7919]. This extension was also used to negotiate
ECDSA curves. Signature algorithms are now negotiated independently ECDSA curves. Signature algorithms are now negotiated independently
(see Section 4.2.3). (see Section 4.2.3).
The "extension_data" field of this extension contains a The "extension_data" field of this extension contains a
"NamedGroupList" value: "NamedGroupList" value:
enum { enum {
/* Elliptic Curve Groups (ECDHE) */ /* Elliptic Curve Groups (ECDHE) */
secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019),
skipping to change at page 52, line 43 skipping to change at page 48, line 5
/* Reserved Code Points */ /* Reserved Code Points */
ffdhe_private_use(0x01FC..0x01FF), ffdhe_private_use(0x01FC..0x01FF),
ecdhe_private_use(0xFE00..0xFEFF), ecdhe_private_use(0xFE00..0xFEFF),
(0xFFFF) (0xFFFF)
} NamedGroup; } NamedGroup;
struct { struct {
NamedGroup named_group_list<2..2^16-1>; NamedGroup named_group_list<2..2^16-1>;
} NamedGroupList; } NamedGroupList;
Elliptic Curve Groups (ECDHE) Indicates support for the Elliptic Curve Groups (ECDHE): Indicates support for the
corresponding named curve, defined either in FIPS 186-4 [DSS] or corresponding named curve, defined in either FIPS 186-4 [DSS] or
in [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for [RFC7748]. Values 0xFE00 through 0xFEFF are reserved for
private use. Private Use [RFC8126].
Finite Field Groups (DHE) Indicates support of the corresponding Finite Field Groups (DHE): Indicates support for the corresponding
finite field group, defined in [RFC7919]. Values 0x01FC through finite field group, defined in [RFC7919]. Values 0x01FC through
0x01FF are reserved for private use. 0x01FF are reserved for Private Use.
Items in named_group_list are ordered according to the client's Items in named_group_list are ordered according to the sender's
preferences (most preferred choice first). preferences (most preferred choice first).
As of TLS 1.3, servers are permitted to send the "supported_groups" As of TLS 1.3, servers are permitted to send the "supported_groups"
extension to the client. Clients MUST NOT act upon any information extension to the client. Clients MUST NOT act upon any information
found in "supported_groups" prior to successful completion of the found in "supported_groups" prior to successful completion of the
handshake but MAY use the information learned from a successfully handshake but MAY use the information learned from a successfully
completed handshake to change what groups they use in their completed handshake to change what groups they use in their
"key_share" extension in subsequent connections. If the server has a "key_share" extension in subsequent connections. If the server has a
group it prefers to the ones in the "key_share" extension but is group it prefers to the ones in the "key_share" extension but is
still willing to accept the ClientHello, it SHOULD send still willing to accept the ClientHello, it SHOULD send
"supported_groups" to update the client's view of its preferences; "supported_groups" to update the client's view of its preferences;
this extension SHOULD contain all groups the server supports, this extension SHOULD contain all groups the server supports,
regardless of whether they are currently supported by the client. regardless of whether they are currently supported by the client.
4.2.8. Key Share 4.2.8. Key Share
The "key_share" extension contains the endpoint's cryptographic The "key_share" extension contains the endpoint's cryptographic
parameters. parameters.
Clients MAY send an empty client_shares vector in order to request Clients MAY send an empty client_shares vector in order to request
group selection from the server at the cost of an additional round group selection from the server, at the cost of an additional round
trip. (see Section 4.1.4) trip (see Section 4.1.4).
struct { struct {
NamedGroup group; NamedGroup group;
opaque key_exchange<1..2^16-1>; opaque key_exchange<1..2^16-1>;
} KeyShareEntry; } KeyShareEntry;
group The named group for the key being exchanged. group: The named group for the key being exchanged.
key_exchange Key exchange information. The contents of this field key_exchange: Key exchange information. The contents of this field
are determined by the specified group and its corresponding are determined by the specified group and its corresponding
definition. Finite Field Diffie-Hellman [DH] parameters are definition. Finite Field Diffie-Hellman [DH76] parameters are
described in Section 4.2.8.1; Elliptic Curve Diffie-Hellman described in Section 4.2.8.1; Elliptic Curve Diffie-Hellman
parameters are described in Section 4.2.8.2. parameters are described in Section 4.2.8.2.
In the ClientHello message, the "extension_data" field of this In the ClientHello message, the "extension_data" field of this
extension contains a "KeyShareClientHello" value: extension contains a "KeyShareClientHello" value:
struct { struct {
KeyShareEntry client_shares<0..2^16-1>; KeyShareEntry client_shares<0..2^16-1>;
} KeyShareClientHello; } KeyShareClientHello;
client_shares A list of offered KeyShareEntry values in descending client_shares: A list of offered KeyShareEntry values in descending
order of client preference. order of client preference.
This vector MAY be empty if the client is requesting a This vector MAY be empty if the client is requesting a
HelloRetryRequest. Each KeyShareEntry value MUST correspond to a HelloRetryRequest. Each KeyShareEntry value MUST correspond to a
group offered in the "supported_groups" extension and MUST appear in group offered in the "supported_groups" extension and MUST appear in
the same order. However, the values MAY be a non-contiguous subset the same order. However, the values MAY be a non-contiguous subset
of the "supported_groups" extension and MAY omit the most preferred of the "supported_groups" extension and MAY omit the most preferred
groups. Such a situation could arise if the most preferred groups groups. Such a situation could arise if the most preferred groups
are new and unlikely to be supported in enough places to make are new and unlikely to be supported in enough places to make
pregenerating key shares for them efficient. pregenerating key shares for them efficient.
skipping to change at page 54, line 32 skipping to change at page 49, line 42
Servers MAY check for violations of these rules and abort the Servers MAY check for violations of these rules and abort the
handshake with an "illegal_parameter" alert if one is violated. handshake with an "illegal_parameter" alert if one is violated.
In a HelloRetryRequest message, the "extension_data" field of this In a HelloRetryRequest message, the "extension_data" field of this
extension contains a KeyShareHelloRetryRequest value: extension contains a KeyShareHelloRetryRequest value:
struct { struct {
NamedGroup selected_group; NamedGroup selected_group;
} KeyShareHelloRetryRequest; } KeyShareHelloRetryRequest;
selected_group The mutually supported group the server intends to selected_group: The mutually supported group the server intends to
negotiate and is requesting a retried ClientHello/KeyShare for. negotiate and is requesting a retried ClientHello/KeyShare for.
Upon receipt of this extension in a HelloRetryRequest, the client Upon receipt of this extension in a HelloRetryRequest, the client
MUST verify that (1) the selected_group field corresponds to a group MUST verify that (1) the selected_group field corresponds to a group
which was provided in the "supported_groups" extension in the which was provided in the "supported_groups" extension in the
original ClientHello; and (2) the selected_group field does not original ClientHello and (2) the selected_group field does not
correspond to a group which was provided in the "key_share" extension correspond to a group which was provided in the "key_share" extension
in the original ClientHello. If either of these checks fails, then in the original ClientHello. If either of these checks fails, then
the client MUST abort the handshake with an "illegal_parameter" the client MUST abort the handshake with an "illegal_parameter"
alert. Otherwise, when sending the new ClientHello, the client MUST alert. Otherwise, when sending the new ClientHello, the client MUST
replace the original "key_share" extension with one containing only a replace the original "key_share" extension with one containing only a
new KeyShareEntry for the group indicated in the selected_group field new KeyShareEntry for the group indicated in the selected_group field
of the triggering HelloRetryRequest. of the triggering HelloRetryRequest.
In a ServerHello message, the "extension_data" field of this In a ServerHello message, the "extension_data" field of this
extension contains a KeyShareServerHello value: extension contains a KeyShareServerHello value:
struct { struct {
KeyShareEntry server_share; KeyShareEntry server_share;
} KeyShareServerHello; } KeyShareServerHello;
server_share A single KeyShareEntry value that is in the same group server_share: A single KeyShareEntry value that is in the same group
as one of the client's shares. as one of the client's shares.
If using (EC)DHE key establishment, servers offer exactly one If using (EC)DHE key establishment, servers offer exactly one
KeyShareEntry in the ServerHello. This value MUST be in the same KeyShareEntry in the ServerHello. This value MUST be in the same
group as the KeyShareEntry value offered by the client that the group as the KeyShareEntry value offered by the client that the
server has selected for the negotiated key exchange. Servers MUST server has selected for the negotiated key exchange. Servers
NOT send a KeyShareEntry for any group not indicated in the MUST NOT send a KeyShareEntry for any group not indicated in the
"supported_groups" extension and MUST NOT send a KeyShareEntry when client's "supported_groups" extension and MUST NOT send a
using the "psk_ke" PskKeyExchangeMode. If using (EC)DHE key KeyShareEntry when using the "psk_ke" PskKeyExchangeMode. If using
establishment, and a HelloRetryRequest containing a "key_share" (EC)DHE key establishment and a HelloRetryRequest containing a
extension was received by the client, the client MUST verify that the "key_share" extension was received by the client, the client MUST
selected NamedGroup in the ServerHello is the same as that in the verify that the selected NamedGroup in the ServerHello is the same as
HelloRetryRequest. If this check fails, the client MUST abort the that in the HelloRetryRequest. If this check fails, the client MUST
handshake with an "illegal_parameter" alert. abort the handshake with an "illegal_parameter" alert.
4.2.8.1. Diffie-Hellman Parameters 4.2.8.1. Diffie-Hellman Parameters
Diffie-Hellman [DH] parameters for both clients and servers are Diffie-Hellman [DH76] parameters for both clients and servers are
encoded in the opaque key_exchange field of a KeyShareEntry in a encoded in the opaque key_exchange field of a KeyShareEntry in a
KeyShare structure. The opaque value contains the Diffie-Hellman KeyShare structure. The opaque value contains the Diffie-Hellman
public value (Y = g^X mod p) for the specified group (see [RFC7919] public value (Y = g^X mod p) for the specified group (see [RFC7919]
for group definitions) encoded as a big-endian integer and padded to for group definitions) encoded as a big-endian integer and padded to
the left with zeros to the size of p in bytes. the left with zeros to the size of p in bytes.
Note: For a given Diffie-Hellman group, the padding results in all Note: For a given Diffie-Hellman group, the padding results in all
public keys having the same length. public keys having the same length.
Peers MUST validate each other's public key Y by ensuring that 1 < Y Peers MUST validate each other's public key Y by ensuring that 1 < Y
< p-1. This check ensures that the remote peer is properly behaved < p-1. This check ensures that the remote peer is properly behaved
and isn't forcing the local system into a small subgroup. and isn't forcing the local system into a small subgroup.
4.2.8.2. ECDHE Parameters 4.2.8.2. ECDHE Parameters
ECDHE parameters for both clients and servers are encoded in the ECDHE parameters for both clients and servers are encoded in the
opaque key_exchange field of a KeyShareEntry in a KeyShare structure. opaque key_exchange field of a KeyShareEntry in a KeyShare structure.
For secp256r1, secp384r1 and secp521r1, the contents are the For secp256r1, secp384r1, and secp521r1, the contents are the
serialized value of the following struct: serialized value of the following struct:
struct { struct {
uint8 legacy_form = 4; uint8 legacy_form = 4;
opaque X[coordinate_length]; opaque X[coordinate_length];
opaque Y[coordinate_length]; opaque Y[coordinate_length];
} UncompressedPointRepresentation; } UncompressedPointRepresentation;
X and Y respectively are the binary representations of the x and y X and Y, respectively, are the binary representations of the x and y
values in network byte order. There are no internal length markers, values in network byte order. There are no internal length markers,
so each number representation occupies as many octets as implied by so each number representation occupies as many octets as implied by
the curve parameters. For P-256 this means that each of X and Y use the curve parameters. For P-256, this means that each of X and Y use
32 octets, padded on the left by zeros if necessary. For P-384 they 32 octets, padded on the left by zeros if necessary. For P-384, they
take 48 octets each, and for P-521 they take 66 octets each. take 48 octets each. For P-521, they take 66 octets each.
For the curves secp256r1, secp384r1 and secp521r1, peers MUST For the curves secp256r1, secp384r1, and secp521r1, peers MUST
validate each other's public value Q by ensuring that the point is a validate each other's public value Q by ensuring that the point is a
valid point on the elliptic curve. The appropriate validation valid point on the elliptic curve. The appropriate validation
procedures are defined in Section 4.3.7 of [X962] and alternatively procedures are defined in Section 4.3.7 of [ECDSA] and alternatively
in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three in Section 5.6.2.3 of [KEYAGREEMENT]. This process consists of three
steps: (1) verify that Q is not the point at infinity (O), (2) verify steps: (1) verify that Q is not the point at infinity (O), (2) verify
that for Q = (x, y) both integers x and y are in the correct that for Q = (x, y) both integers x and y are in the correct
interval, (3) ensure that (x, y) is a correct solution to the interval, and (3) ensure that (x, y) is a correct solution to the
elliptic curve equation. For these curves, implementers do not need elliptic curve equation. For these curves, implementors do not need
to verify membership in the correct subgroup. to verify membership in the correct subgroup.
For X25519 and X448, the contents of the public value are the byte For X25519 and X448, the contents of the public value are the byte
string inputs and outputs of the corresponding functions defined in string inputs and outputs of the corresponding functions defined in
[RFC7748], 32 bytes for X25519 and 56 bytes for X448. [RFC7748]: 32 bytes for X25519 and 56 bytes for X448.
Note: Versions of TLS prior to 1.3 permitted point format Note: Versions of TLS prior to 1.3 permitted point format
negotiation; TLS 1.3 removes this feature in favor of a single point negotiation; TLS 1.3 removes this feature in favor of a single point
format for each curve. format for each curve.
4.2.9. Pre-Shared Key Exchange Modes 4.2.9. Pre-Shared Key Exchange Modes
In order to use PSKs, clients MUST also send a In order to use PSKs, clients MUST also send a
"psk_key_exchange_modes" extension. The semantics of this extension "psk_key_exchange_modes" extension. The semantics of this extension
are that the client only supports the use of PSKs with these modes, are that the client only supports the use of PSKs with these modes,
which restricts both the use of PSKs offered in this ClientHello and which restricts both the use of PSKs offered in this ClientHello and
those which the server might supply via NewSessionTicket. those which the server might supply via NewSessionTicket.
A client MUST provide a "psk_key_exchange_modes" extension if it A client MUST provide a "psk_key_exchange_modes" extension if it
offers a "pre_shared_key" extension. If clients offer offers a "pre_shared_key" extension. If clients offer
"pre_shared_key" without a "psk_key_exchange_modes" extension, "pre_shared_key" without a "psk_key_exchange_modes" extension,
servers MUST abort the handshake. Servers MUST NOT select a key servers MUST abort the handshake. Servers MUST NOT select a key
exchange mode that is not listed by the client. This extension also exchange mode that is not listed by the client. This extension also
restricts the modes for use with PSK resumption; servers SHOULD NOT restricts the modes for use with PSK resumption. Servers SHOULD NOT
send NewSessionTicket with tickets that are not compatible with the send NewSessionTicket with tickets that are not compatible with the
advertised modes; however, if a server does so, the impact will just advertised modes; however, if a server does so, the impact will just
be that the client's attempts at resumption fail. be that the client's attempts at resumption fail.
The server MUST NOT send a "psk_key_exchange_modes" extension. The server MUST NOT send a "psk_key_exchange_modes" extension.
enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode; enum { psk_ke(0), psk_dhe_ke(1), (255) } PskKeyExchangeMode;
struct { struct {
PskKeyExchangeMode ke_modes<1..255>; PskKeyExchangeMode ke_modes<1..255>;
} PskKeyExchangeModes; } PskKeyExchangeModes;
psk_ke PSK-only key establishment. In this mode, the server MUST psk_ke: PSK-only key establishment. In this mode, the server
NOT supply a "key_share" value. MUST NOT supply a "key_share" value.
psk_dhe_ke PSK with (EC)DHE key establishment. In this mode, the psk_dhe_ke: PSK with (EC)DHE key establishment. In this mode, the
client and server MUST supply "key_share" values as described in client and server MUST supply "key_share" values as described in
Section 4.2.8. Section 4.2.8.
Any future values that are allocated must ensure that the transmitted Any future values that are allocated must ensure that the transmitted
protocol messages unambiguously identify which mode was selected by protocol messages unambiguously identify which mode was selected by
the server; at present, this is indicated by the presence of the the server; at present, this is indicated by the presence of the
"key_share" in the ServerHello. "key_share" in the ServerHello.
4.2.10. Early Data Indication 4.2.10. Early Data Indication
When a PSK is used and early data is allowed for that PSK, the client When a PSK is used and early data is allowed for that PSK, the client
can send application data in its first flight of messages. If the can send Application Data in its first flight of messages. If the
client opts to do so, it MUST supply both the "early_data" extension client opts to do so, it MUST supply both the "pre_shared_key" and
as well as the "pre_shared_key" extension. "early_data" extensions.
The "extension_data" field of this extension contains an The "extension_data" field of this extension contains an
"EarlyDataIndication" value. "EarlyDataIndication" value.
struct {} Empty; struct {} Empty;
struct { struct {
select (Handshake.msg_type) { select (Handshake.msg_type) {
case new_session_ticket: uint32 max_early_data_size; case new_session_ticket: uint32 max_early_data_size;
case client_hello: Empty; case client_hello: Empty;
case encrypted_extensions: Empty; case encrypted_extensions: Empty;
}; };
} EarlyDataIndication; } EarlyDataIndication;
See Section 4.6.1 for the use of the max_early_data_size field. See Section 4.6.1 for details regarding the use of the
max_early_data_size field.
The parameters for the 0-RTT data (version, symmetric cipher suite, The parameters for the 0-RTT data (version, symmetric cipher suite,
ALPN protocol, etc.) are those associated with the PSK in use. For Application-Layer Protocol Negotiation (ALPN) [RFC7301] protocol,
externally provisioned PSKs, the associated values are those etc.) are those associated with the PSK in use. For externally
provisioned along with the key. For PSKs established via a provisioned PSKs, the associated values are those provisioned along
NewSessionTicket message, the associated values are those which were with the key. For PSKs established via a NewSessionTicket message,
negotiated in the connection which established the PSK. The PSK used the associated values are those which were negotiated in the
to encrypt the early data MUST be the first PSK listed in the connection which established the PSK. The PSK used to encrypt the
client's "pre_shared_key" extension. early data MUST be the first PSK listed in the client's
"pre_shared_key" extension.
For PSKs provisioned via NewSessionTicket, a server MUST validate For PSKs provisioned via NewSessionTicket, a server MUST validate
that the ticket age for the selected PSK identity (computed by that the ticket age for the selected PSK identity (computed by
subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age subtracting ticket_age_add from PskIdentity.obfuscated_ticket_age
modulo 2^32) is within a small tolerance of the time since the ticket modulo 2^32) is within a small tolerance of the time since the ticket
was issued (see Section 8). If it is not, the server SHOULD proceed was issued (see Section 8). If it is not, the server SHOULD proceed
with the handshake but reject 0-RTT, and SHOULD NOT take any other with the handshake but reject 0-RTT, and SHOULD NOT take any other
action that assumes that this ClientHello is fresh. action that assumes that this ClientHello is fresh.
0-RTT messages sent in the first flight have the same (encrypted) 0-RTT messages sent in the first flight have the same (encrypted)
skipping to change at page 58, line 30 skipping to change at page 54, line 14
A server which receives an "early_data" extension MUST behave in one A server which receives an "early_data" extension MUST behave in one
of three ways: of three ways:
- Ignore the extension and return a regular 1-RTT response. The - Ignore the extension and return a regular 1-RTT response. The
server then skips past early data by attempting to deprotect server then skips past early data by attempting to deprotect
received records using the handshake traffic key, discarding received records using the handshake traffic key, discarding
records which fail deprotection (up to the configured records which fail deprotection (up to the configured
max_early_data_size). Once a record is deprotected successfully, max_early_data_size). Once a record is deprotected successfully,
it is treated as the start of the client's second flight and the it is treated as the start of the client's second flight and the
the server proceeds as with an ordinary 1-RTT handshake. server proceeds as with an ordinary 1-RTT handshake.
- Request that the client send another ClientHello by responding - Request that the client send another ClientHello by responding
with a HelloRetryRequest. A client MUST NOT include the with a HelloRetryRequest. A client MUST NOT include the
"early_data" extension in its followup ClientHello. The server "early_data" extension in its followup ClientHello. The server
then ignores early data by skipping all records with external then ignores early data by skipping all records with an external
content type of "application_data" (indicating that they are content type of "application_data" (indicating that they are
encrypted), up to the configured max_early_data_size. encrypted), up to the configured max_early_data_size.
- Return its own "early_data" extension in EncryptedExtensions, - Return its own "early_data" extension in EncryptedExtensions,
indicating that it intends to process the early data. It is not indicating that it intends to process the early data. It is not
possible for the server to accept only a subset of the early data possible for the server to accept only a subset of the early data
messages. Even though the server sends a message accepting early messages. Even though the server sends a message accepting early
data, the actual early data itself may already be in flight by the data, the actual early data itself may already be in flight by the
time the server generates this message. time the server generates this message.
In order to accept early data, the server MUST have accepted a PSK In order to accept early data, the server MUST have accepted a PSK
cipher suite and selected the first key offered in the client's cipher suite and selected the first key offered in the client's
"pre_shared_key" extension. In addition, it MUST verify that the "pre_shared_key" extension. In addition, it MUST verify that the
following values are the same as those associated with the selected following values are the same as those associated with the
PSK: selected PSK:
- The TLS version number - The TLS version number
- The selected cipher suite - The selected cipher suite
- The selected ALPN [RFC7301] protocol, if any - The selected ALPN [RFC7301] protocol, if any
These requirements are a superset of those needed to perform a 1-RTT These requirements are a superset of those needed to perform a 1-RTT
handshake using the PSK in question. For externally established handshake using the PSK in question. For externally established
PSKs, the associated values are those provisioned along with the key. PSKs, the associated values are those provisioned along with the key.
For PSKs established via a NewSessionTicket message, the associated For PSKs established via a NewSessionTicket message, the associated
values are those negotiated in the connection during which the ticket values are those negotiated in the connection during which the ticket
was established. was established.
skipping to change at page 59, line 18 skipping to change at page 55, line 6
These requirements are a superset of those needed to perform a 1-RTT These requirements are a superset of those needed to perform a 1-RTT
handshake using the PSK in question. For externally established handshake using the PSK in question. For externally established
PSKs, the associated values are those provisioned along with the key. PSKs, the associated values are those provisioned along with the key.
For PSKs established via a NewSessionTicket message, the associated For PSKs established via a NewSessionTicket message, the associated
values are those negotiated in the connection during which the ticket values are those negotiated in the connection during which the ticket
was established. was established.
Future extensions MUST define their interaction with 0-RTT. Future extensions MUST define their interaction with 0-RTT.
If any of these checks fail, the server MUST NOT respond with the If any of these checks fail, the server MUST NOT respond with the
extension and must discard all the first flight data using one of the extension and must discard all the first-flight data using one of the
first two mechanisms listed above (thus falling back to 1-RTT or first two mechanisms listed above (thus falling back to 1-RTT or
2-RTT). If the client attempts a 0-RTT handshake but the server 2-RTT). If the client attempts a 0-RTT handshake but the server
rejects it, the server will generally not have the 0-RTT record rejects it, the server will generally not have the 0-RTT record
protection keys and must instead use trial decryption (either with protection keys and must instead use trial decryption (either with
the 1-RTT handshake keys or by looking for a cleartext ClientHello in the 1-RTT handshake keys or by looking for a cleartext ClientHello in
the case of HelloRetryRequest) to find the first non-0-RTT message. the case of a HelloRetryRequest) to find the first non-0-RTT message.
If the server chooses to accept the "early_data" extension, then it If the server chooses to accept the "early_data" extension, then it
MUST comply with the same error handling requirements specified for MUST comply with the same error-handling requirements specified for
all records when processing early data records. Specifically, if the all records when processing early data records. Specifically, if the
server fails to decrypt a 0-RTT record following an accepted server fails to decrypt a 0-RTT record following an accepted
"early_data" extension it MUST terminate the connection with a "early_data" extension, it MUST terminate the connection with a
"bad_record_mac" alert as per Section 5.2. "bad_record_mac" alert as per Section 5.2.
If the server rejects the "early_data" extension, the client If the server rejects the "early_data" extension, the client
application MAY opt to retransmit the application data previously application MAY opt to retransmit the Application Data previously
sent in early data once the handshake has been completed. Note that sent in early data once the handshake has been completed. Note that
automatic re-transmission of early data could result in assumptions automatic retransmission of early data could result in incorrect
about the status of the connection being incorrect. For instance, assumptions regarding the status of the connection. For instance,
when the negotiated connection selects a different ALPN protocol from when the negotiated connection selects a different ALPN protocol from
what was used for the early data, an application might need to what was used for the early data, an application might need to
construct different messages. Similarly, if early data assumes construct different messages. Similarly, if early data assumes
anything about the connection state, it might be sent in error after anything about the connection state, it might be sent in error after
the handshake completes. the handshake completes.
A TLS implementation SHOULD NOT automatically re-send early data; A TLS implementation SHOULD NOT automatically resend early data;
applications are in a better position to decide when re-transmission applications are in a better position to decide when retransmission
is appropriate. A TLS implementation MUST NOT automatically re-send is appropriate. A TLS implementation MUST NOT automatically resend
early data unless the negotiated connection selects the same ALPN early data unless the negotiated connection selects the same ALPN
protocol. protocol.
4.2.11. Pre-Shared Key Extension 4.2.11. Pre-Shared Key Extension
The "pre_shared_key" extension is used to negotiate the identity of The "pre_shared_key" extension is used to negotiate the identity of
the pre-shared key to be used with a given handshake in association the pre-shared key to be used with a given handshake in association
with PSK key establishment. with PSK key establishment.
The "extension_data" field of this extension contains a The "extension_data" field of this extension contains a
skipping to change at page 60, line 33 skipping to change at page 56, line 27
PskBinderEntry binders<33..2^16-1>; PskBinderEntry binders<33..2^16-1>;
} OfferedPsks; } OfferedPsks;
struct { struct {
select (Handshake.msg_type) { select (Handshake.msg_type) {
case client_hello: OfferedPsks; case client_hello: OfferedPsks;
case server_hello: uint16 selected_identity; case server_hello: uint16 selected_identity;
}; };
} PreSharedKeyExtension; } PreSharedKeyExtension;
identity A label for a key. For instance, a ticket defined in identity: A label for a key. For instance, a ticket (as defined in
Appendix B.3.4 or a label for a pre-shared key established Appendix B.3.4) or a label for a pre-shared key established
externally. externally.
obfuscated_ticket_age An obfuscated version of the age of the key. obfuscated_ticket_age: An obfuscated version of the age of the key.
Section 4.2.11.1 describes how to form this value for identities Section 4.2.11.1 describes how to form this value for identities
established via the NewSessionTicket message. For identities established via the NewSessionTicket message. For identities
established externally an obfuscated_ticket_age of 0 SHOULD be established externally, an obfuscated_ticket_age of 0 SHOULD be
used, and servers MUST ignore the value. used, and servers MUST ignore the value.
identities A list of the identities that the client is willing to identities: A list of the identities that the client is willing to
negotiate with the server. If sent alongside the "early_data" negotiate with the server. If sent alongside the "early_data"
extension (see Section 4.2.10), the first identity is the one used extension (see Section 4.2.10), the first identity is the one used
for 0-RTT data. for 0-RTT data.
binders A series of HMAC values, one for each PSK offered in the binders: A series of HMAC values, one for each value in the
"pre_shared_keys" extension and in the same order, computed as identities list and in the same order, computed as described
described below. below.
selected_identity The server's chosen identity expressed as a selected_identity: The server's chosen identity expressed as a
(0-based) index into the identities in the client's list. (0-based) index into the identities in the client's list.
Each PSK is associated with a single Hash algorithm. For PSKs Each PSK is associated with a single Hash algorithm. For PSKs
established via the ticket mechanism (Section 4.6.1), this is the KDF established via the ticket mechanism (Section 4.6.1), this is the KDF
Hash algorithm on the connection where the ticket was established. Hash algorithm on the connection where the ticket was established.
For externally established PSKs, the Hash algorithm MUST be set when For externally established PSKs, the Hash algorithm MUST be set when
the PSK is established, or default to SHA-256 if no such algorithm is the PSK is established or default to SHA-256 if no such algorithm is
defined. The server MUST ensure that it selects a compatible PSK (if defined. The server MUST ensure that it selects a compatible PSK
any) and cipher suite. (if any) and cipher suite.
In TLS versions prior to TLS 1.3, the Server Name Identification In TLS versions prior to TLS 1.3, the Server Name Identification
(SNI) value was intended to be associated with the session (Section 3 (SNI) value was intended to be associated with the session (Section 3
of [RFC6066]), with the server being required to enforce that the SNI of [RFC6066]), with the server being required to enforce that the SNI
value associated with the session matches the one specified in the value associated with the session matches the one specified in the
resumption handshake. However, in reality the implementations were resumption handshake. However, in reality the implementations were
not consistent on which of two supplied SNI values they would use, not consistent on which of two supplied SNI values they would use,
leading to the consistency requirement being de-facto enforced by the leading to the consistency requirement being de facto enforced by the
clients. In TLS 1.3, the SNI value is always explicitly specified in clients. In TLS 1.3, the SNI value is always explicitly specified in
the resumption handshake, and there is no need for the server to the resumption handshake, and there is no need for the server to
associate an SNI value with the ticket. Clients, however, SHOULD associate an SNI value with the ticket. Clients, however, SHOULD
store the SNI with the PSK to fulfill the requirements of store the SNI with the PSK to fulfill the requirements of
Section 4.6.1. Section 4.6.1.
Implementor's note: when session resumption is the primary use case Implementor's note: When session resumption is the primary use case
of PSKs the most straightforward way to implement the PSK/cipher of PSKs, the most straightforward way to implement the PSK/cipher
suite matching requirements is to negotiate the cipher suite first suite matching requirements is to negotiate the cipher suite first
and then exclude any incompatible PSKs. Any unknown PSKs (e.g., they and then exclude any incompatible PSKs. Any unknown PSKs (e.g., ones
are not in the PSK database or are encrypted with an unknown key) not in the PSK database or encrypted with an unknown key) SHOULD
SHOULD simply be ignored. If no acceptable PSKs are found, the simply be ignored. If no acceptable PSKs are found, the server
server SHOULD perform a non-PSK handshake if possible. If backwards SHOULD perform a non-PSK handshake if possible. If backward
compatibility is important, client provided, externally established compatibility is important, client-provided, externally established
PSKs SHOULD influence cipher suite selection. PSKs SHOULD influence cipher suite selection.
Prior to accepting PSK key establishment, the server MUST validate Prior to accepting PSK key establishment, the server MUST validate
the corresponding binder value (see Section 4.2.11.2 below). If this the corresponding binder value (see Section 4.2.11.2 below). If this
value is not present or does not validate, the server MUST abort the value is not present or does not validate, the server MUST abort the
handshake. Servers SHOULD NOT attempt to validate multiple binders; handshake. Servers SHOULD NOT attempt to validate multiple binders;
rather they SHOULD select a single PSK and validate solely the binder rather, they SHOULD select a single PSK and validate solely the
that corresponds to that PSK. See [Section 8.2] and [Appendix E.6] binder that corresponds to that PSK. See Section 8.2 and
for the security rationale for this requirement. In order to accept Appendix E.6 for the security rationale for this requirement. In
PSK key establishment, the server sends a "pre_shared_key" extension order to accept PSK key establishment, the server sends a
indicating the selected identity. "pre_shared_key" extension indicating the selected identity.
Clients MUST verify that the server's selected_identity is within the Clients MUST verify that the server's selected_identity is within the
range supplied by the client, that the server selected a cipher suite range supplied by the client, that the server selected a cipher suite
indicating a Hash associated with the PSK and that a server indicating a Hash associated with the PSK, and that a server
"key_share" extension is present if required by the ClientHello "key_share" extension is present if required by the ClientHello
"psk_key_exchange_modes". If these values are not consistent the "psk_key_exchange_modes" extension. If these values are not
client MUST abort the handshake with an "illegal_parameter" alert. consistent, the client MUST abort the handshake with an
"illegal_parameter" alert.
If the server supplies an "early_data" extension, the client MUST If the server supplies an "early_data" extension, the client MUST
verify that the server's selected_identity is 0. If any other value verify that the server's selected_identity is 0. If any other value
is returned, the client MUST abort the handshake with an is returned, the client MUST abort the handshake with an
"illegal_parameter" alert. "illegal_parameter" alert.
The "pre_shared_key" extension MUST be the last extension in the The "pre_shared_key" extension MUST be the last extension in the
ClientHello (this facilitates implementation as described below). ClientHello (this facilitates implementation as described below).
Servers MUST check that it is the last extension and otherwise fail Servers MUST check that it is the last extension and otherwise fail
the handshake with an "illegal_parameter" alert. the handshake with an "illegal_parameter" alert.
skipping to change at page 63, line 14 skipping to change at page 59, line 14
If the handshake includes a HelloRetryRequest, the initial If the handshake includes a HelloRetryRequest, the initial
ClientHello and HelloRetryRequest are included in the transcript ClientHello and HelloRetryRequest are included in the transcript
along with the new ClientHello. For instance, if the client sends along with the new ClientHello. For instance, if the client sends
ClientHello1, its binder will be computed over: ClientHello1, its binder will be computed over:
Transcript-Hash(Truncate(ClientHello1)) Transcript-Hash(Truncate(ClientHello1))
Where Truncate() removes the binders list from the ClientHello. Where Truncate() removes the binders list from the ClientHello.
If the server responds with HelloRetryRequest, and the client then If the server responds with a HelloRetryRequest and the client then
sends ClientHello2, its binder will be computed over: sends ClientHello2, its binder will be computed over:
Transcript-Hash(ClientHello1, Transcript-Hash(ClientHello1,
HelloRetryRequest, HelloRetryRequest,
Truncate(ClientHello2)) Truncate(ClientHello2))
The full ClientHello1/ClientHello2 is included in all other handshake The full ClientHello1/ClientHello2 is included in all other handshake
hash computations. Note that in the first flight, hash computations. Note that in the first flight,
Truncate(ClientHello1) is hashed directly, but in the second flight, Truncate(ClientHello1) is hashed directly, but in the second flight,
ClientHello1 is hashed and then reinjected as a "message_hash" ClientHello1 is hashed and then reinjected as a "message_hash"
skipping to change at page 64, line 4 skipping to change at page 60, line 14
4.3.1. Encrypted Extensions 4.3.1. Encrypted Extensions
In all handshakes, the server MUST send the EncryptedExtensions In all handshakes, the server MUST send the EncryptedExtensions
message immediately after the ServerHello message. This is the first message immediately after the ServerHello message. This is the first
message that is encrypted under keys derived from the message that is encrypted under keys derived from the
server_handshake_traffic_secret. server_handshake_traffic_secret.
The EncryptedExtensions message contains extensions that can be The EncryptedExtensions message contains extensions that can be
protected, i.e., any which are not needed to establish the protected, i.e., any which are not needed to establish the
cryptographic context, but which are not associated with individual cryptographic context but which are not associated with individual
certificates. The client MUST check EncryptedExtensions for the certificates. The client MUST check EncryptedExtensions for the
presence of any forbidden extensions and if any are found MUST abort presence of any forbidden extensions and if any are found MUST abort
the handshake with an "illegal_parameter" alert. the handshake with an "illegal_parameter" alert.
Structure of this message: Structure of this message:
struct { struct {
Extension extensions<0..2^16-1>; Extension extensions<0..2^16-1>;
} EncryptedExtensions; } EncryptedExtensions;
extensions A list of extensions. For more information, see the extensions: A list of extensions. For more information, see the
table in Section 4.2. table in Section 4.2.
4.3.2. Certificate Request 4.3.2. Certificate Request
A server which is authenticating with a certificate MAY optionally A server which is authenticating with a certificate MAY optionally
request a certificate from the client. This message, if sent, MUST request a certificate from the client. This message, if sent, MUST
follow EncryptedExtensions. follow EncryptedExtensions.
Structure of this message: Structure of this message:
struct { struct {
opaque certificate_request_context<0..2^8-1>; opaque certificate_request_context<0..2^8-1>;
Extension extensions<2..2^16-1>; Extension extensions<2..2^16-1>;
} CertificateRequest; } CertificateRequest;
certificate_request_context An opaque string which identifies the certificate_request_context: An opaque string which identifies the
certificate request and which will be echoed in the client's certificate request and which will be echoed in the client's
Certificate message. The certificate_request_context MUST be Certificate message. The certificate_request_context MUST be
unique within the scope of this connection (thus preventing replay unique within the scope of this connection (thus preventing replay
of client CertificateVerify messages). This field SHALL be zero of client CertificateVerify messages). This field SHALL be zero
length unless used for the post-handshake authentication exchanges length unless used for the post-handshake authentication exchanges
described in Section 4.6.2. When requesting post-handshake described in Section 4.6.2. When requesting post-handshake
authentication, the server SHOULD make the context unpredictable authentication, the server SHOULD make the context unpredictable
to the client (e.g., by randomly generating it) in order to to the client (e.g., by randomly generating it) in order to
prevent an attacker who has temporary access to the client's prevent an attacker who has temporary access to the client's
private key from pre-computing valid CertificateVerify messages. private key from pre-computing valid CertificateVerify messages.
extensions A set of extensions describing the parameters of the extensions: A set of extensions describing the parameters of the
certificate being requested. The "signature_algorithms" extension certificate being requested. The "signature_algorithms" extension
MUST be specified, and other extensions may optionally be included MUST be specified, and other extensions may optionally be included
if defined for this message. Clients MUST ignore unrecognized if defined for this message. Clients MUST ignore unrecognized
extensions. extensions.
In prior versions of TLS, the CertificateRequest message carried a In prior versions of TLS, the CertificateRequest message carried a
list of signature algorithms and certificate authorities which the list of signature algorithms and certificate authorities which the
server would accept. In TLS 1.3 the former is expressed by sending server would accept. In TLS 1.3, the former is expressed by sending
the "signature_algorithms" and optionally "signature_algorithms_cert" the "signature_algorithms" and optionally "signature_algorithms_cert"
extensions. The latter is expressed by sending the extensions. The latter is expressed by sending the
"certificate_authorities" extension (see Section 4.2.4). "certificate_authorities" extension (see Section 4.2.4).
Servers which are authenticating with a PSK MUST NOT send the Servers which are authenticating with a PSK MUST NOT send the
CertificateRequest message in the main handshake, though they MAY CertificateRequest message in the main handshake, though they MAY
send it in post-handshake authentication (see Section 4.6.2) provided send it in post-handshake authentication (see Section 4.6.2) provided
that the client has sent the "post_handshake_auth" extension (see that the client has sent the "post_handshake_auth" extension (see
Section 4.2.6). Section 4.2.6).
4.4. Authentication Messages 4.4. Authentication Messages
As discussed in Section 2, TLS generally uses a common set of As discussed in Section 2, TLS generally uses a common set of
messages for authentication, key confirmation, and handshake messages for authentication, key confirmation, and handshake
integrity: Certificate, CertificateVerify, and Finished. (The integrity: Certificate, CertificateVerify, and Finished. (The PSK
PreSharedKey binders also perform key confirmation, in a similar binders also perform key confirmation, in a similar fashion.) These
fashion.) These three messages are always sent as the last messages three messages are always sent as the last messages in their
in their handshake flight. The Certificate and CertificateVerify handshake flight. The Certificate and CertificateVerify messages are
messages are only sent under certain circumstances, as defined below. only sent under certain circumstances, as defined below. The
The Finished message is always sent as part of the Authentication Finished message is always sent as part of the Authentication Block.
block. These messages are encrypted under keys derived from These messages are encrypted under keys derived from the
[sender]_handshake_traffic_secret. [sender]_handshake_traffic_secret.
The computations for the Authentication messages all uniformly take The computations for the Authentication messages all uniformly take
the following inputs: the following inputs:
- The certificate and signing key to be used. - The certificate and signing key to be used.
- A Handshake Context consisting of the set of messages to be - A Handshake Context consisting of the set of messages to be
included in the transcript hash. included in the transcript hash.
- A base key to be used to compute a MAC key. - A Base Key to be used to compute a MAC key.
Based on these inputs, the messages then contain: Based on these inputs, the messages then contain:
Certificate The certificate to be used for authentication, and any Certificate: The certificate to be used for authentication, and any
supporting certificates in the chain. Note that certificate-based supporting certificates in the chain. Note that certificate-based
client authentication is not available in PSK (including 0-RTT) client authentication is not available in PSK handshake flows
flows. (including 0-RTT).
CertificateVerify A signature over the value Transcript- CertificateVerify: A signature over the value
Hash(Handshake Context, Certificate) Transcript-Hash(Handshake Context, Certificate).
Finished A MAC over the value Transcript-Hash(Handshake Context, Finished: A MAC over the value Transcript-Hash(Handshake Context,
Certificate, CertificateVerify) using a MAC key derived from the Certificate, CertificateVerify) using a MAC key derived from the
base key. Base Key.
The following table defines the Handshake Context and MAC Base Key The following table defines the Handshake Context and MAC Base Key
for each scenario: for each scenario:
+-----------+----------------------------+--------------------------+ +-----------+-------------------------+-----------------------------+
| Mode | Handshake Context | Base Key | | Mode | Handshake Context | Base Key |
+-----------+----------------------------+--------------------------+ +-----------+-------------------------+-----------------------------+
| Server | ClientHello ... later of E | server_handshake_traffic | | Server | ClientHello ... later | server_handshake_traffic_ |
| | ncryptedExtensions/Certifi | _secret | | | of EncryptedExtensions/ | secret |
| | cateRequest | | | | CertificateRequest | |
| | | | | | | |
| Client | ClientHello ... later of | client_handshake_traffic | | Client | ClientHello ... later | client_handshake_traffic_ |
| | server | _secret | | | of server | secret |
| | Finished/EndOfEarlyData | | | | Finished/EndOfEarlyData | |
| | | | | | | |
| Post- | ClientHello ... client | client_application_traff | | Post- | ClientHello ... client | client_application_traffic_ |
| Handshake | Finished + | ic_secret_N | | Handshake | Finished + | secret_N |
| | CertificateRequest | | | | CertificateRequest | |
+-----------+----------------------------+--------------------------+ +-----------+-------------------------+-----------------------------+
4.4.1. The Transcript Hash 4.4.1. The Transcript Hash
Many of the cryptographic computations in TLS make use of a Many of the cryptographic computations in TLS make use of a
transcript hash. This value is computed by hashing the concatenation transcript hash. This value is computed by hashing the concatenation
of each included handshake message, including the handshake message of each included handshake message, including the handshake message
header carrying the handshake message type and length fields, but not header carrying the handshake message type and length fields, but not
including record layer headers. I.e., including record layer headers. I.e.,
Transcript-Hash(M1, M2, ... Mn) = Hash(M1 || M2 || ... || Mn) Transcript-Hash(M1, M2, ... Mn) = Hash(M1 || M2 || ... || Mn)
As an exception to this general rule, when the server responds to a As an exception to this general rule, when the server responds to a
ClientHello with a HelloRetryRequest, the value of ClientHello1 is ClientHello with a HelloRetryRequest, the value of ClientHello1 is
replaced with a special synthetic handshake message of handshake type replaced with a special synthetic handshake message of handshake type
"message_hash" containing Hash(ClientHello1). I.e., "message_hash" containing Hash(ClientHello1). I.e.,
Transcript-Hash(ClientHello1, HelloRetryRequest, ... Mn) = Transcript-Hash(ClientHello1, HelloRetryRequest, ... Mn) =
Hash(message_hash || /* Handshake type */ Hash(message_hash || /* Handshake type */
00 00 Hash.length || /* Handshake message length (bytes) */ 00 00 Hash.length || /* Handshake message length (bytes) */
Hash(ClientHello1) || /* Hash of ClientHello1 */ Hash(ClientHello1) || /* Hash of ClientHello1 */
HelloRetryRequest || ... || Mn) HelloRetryRequest || ... || Mn)
The reason for this construction is to allow the server to do a The reason for this construction is to allow the server to do a
stateless HelloRetryRequest by storing just the hash of ClientHello1 stateless HelloRetryRequest by storing just the hash of ClientHello1
in the cookie, rather than requiring it to export the entire in the cookie, rather than requiring it to export the entire
intermediate hash state (see Section 4.2.2). intermediate hash state (see Section 4.2.2).
For concreteness, the transcript hash is always taken from the For concreteness, the transcript hash is always taken from the
following sequence of handshake messages, starting at the first following sequence of handshake messages, starting at the first
ClientHello and including only those messages that were sent: ClientHello and including only those messages that were sent:
ClientHello, HelloRetryRequest, ClientHello, ServerHello, ClientHello, HelloRetryRequest, ClientHello, ServerHello,
EncryptedExtensions, server CertificateRequest, server Certificate, EncryptedExtensions, server CertificateRequest, server Certificate,
server CertificateVerify, server Finished, EndOfEarlyData, client server CertificateVerify, server Finished, EndOfEarlyData, client
Certificate, client CertificateVerify, client Finished. Certificate, client CertificateVerify, client Finished.
In general, implementations can implement the transcript by keeping a In general, implementations can implement the transcript by keeping a
running transcript hash value based on the negotiated hash. Note, running transcript hash value based on the negotiated hash. Note,
however, that subsequent post-handshake authentications do not however, that subsequent post-handshake authentications do not
include each other, just the messages through the end of the main include each other, just the messages through the end of the main
handshake. handshake.
skipping to change at page 67, line 22 skipping to change at page 64, line 11
however, that subsequent post-handshake authentications do not however, that subsequent post-handshake authentications do not
include each other, just the messages through the end of the main include each other, just the messages through the end of the main
handshake. handshake.
4.4.2. Certificate 4.4.2. Certificate
This message conveys the endpoint's certificate chain to the peer. This message conveys the endpoint's certificate chain to the peer.
The server MUST send a Certificate message whenever the agreed-upon The server MUST send a Certificate message whenever the agreed-upon
key exchange method uses certificates for authentication (this key exchange method uses certificates for authentication (this
includes all key exchange methods defined in this document except includes all key exchange methods defined in this document
PSK). except PSK).
The client MUST send a Certificate message if and only if the server The client MUST send a Certificate message if and only if the server
has requested client authentication via a CertificateRequest message has requested client authentication via a CertificateRequest message
(Section 4.3.2). If the server requests client authentication but no (Section 4.3.2). If the server requests client authentication but no
suitable certificate is available, the client MUST send a Certificate suitable certificate is available, the client MUST send a Certificate
message containing no certificates (i.e., with the "certificate_list" message containing no certificates (i.e., with the "certificate_list"
field having length 0). A Finished message MUST be sent regardless field having length 0). A Finished message MUST be sent regardless
of whether the Certificate message is empty. of whether the Certificate message is empty.
Structure of this message: Structure of this message:
/* Managed by IANA */
enum { enum {
X509(0), X509(0),
RawPublicKey(2), RawPublicKey(2),
(255) (255)
} CertificateType; } CertificateType;
struct { struct {
select (certificate_type) { select (certificate_type) {
case RawPublicKey: case RawPublicKey:
/* From RFC 7250 ASN.1_subjectPublicKeyInfo */ /* From RFC 7250 ASN.1_subjectPublicKeyInfo */
skipping to change at page 68, line 29 skipping to change at page 65, line 5
opaque cert_data<1..2^24-1>; opaque cert_data<1..2^24-1>;
}; };
Extension extensions<0..2^16-1>; Extension extensions<0..2^16-1>;
} CertificateEntry; } CertificateEntry;
struct { struct {
opaque certificate_request_context<0..2^8-1>; opaque certificate_request_context<0..2^8-1>;
CertificateEntry certificate_list<0..2^24-1>; CertificateEntry certificate_list<0..2^24-1>;
} Certificate; } Certificate;
certificate_request_context If this message is in response to a certificate_request_context: If this message is in response to a
CertificateRequest, the value of certificate_request_context in CertificateRequest, the value of certificate_request_context in
that message. Otherwise (in the case of server authentication), that message. Otherwise (in the case of server authentication),
this field SHALL be zero length. this field SHALL be zero length.
certificate_list This is a sequence (chain) of CertificateEntry certificate_list: A sequence (chain) of CertificateEntry structures,
structures, each containing a single certificate and set of each containing a single certificate and set of extensions.
extensions.
extensions: A set of extension values for the CertificateEntry. The extensions: A set of extension values for the CertificateEntry. The
"Extension" format is defined in Section 4.2. Valid extensions "Extension" format is defined in Section 4.2. Valid extensions
for server certificates at present include OCSP Status extension for server certificates at present include the OCSP Status
([RFC6066]) and SignedCertificateTimestamps ([RFC6962]); future extension [RFC6066] and the SignedCertificateTimestamp extension
extensions may be defined for this message as well. Extensions in [RFC6962]; future extensions may be defined for this message as
the Certificate message from the server MUST correspond to ones well. Extensions in the Certificate message from the server MUST
from the ClientHello message. Extensions in the Certificate from correspond to ones from the ClientHello message. Extensions in
the client MUST correspond with extensions in the the Certificate message from the client MUST correspond to
CertificateRequest message from the server. If an extension extensions in the CertificateRequest message from the server. If
applies to the entire chain, it SHOULD be included in the first an extension applies to the entire chain, it SHOULD be included in
CertificateEntry. the first CertificateEntry.
If the corresponding certificate type extension If the corresponding certificate type extension
("server_certificate_type" or "client_certificate_type") was not ("server_certificate_type" or "client_certificate_type") was not
negotiated in Encrypted Extensions, or the X.509 certificate type was negotiated in EncryptedExtensions, or the X.509 certificate type was
negotiated, then each CertificateEntry contains a DER-encoded X.509 negotiated, then each CertificateEntry contains a DER-encoded X.509
certificate. The sender's certificate MUST come in the first certificate. The sender's certificate MUST come in the first
CertificateEntry in the list. Each following certificate SHOULD CertificateEntry in the list. Each following certificate SHOULD
directly certify the one immediately preceding it. Because directly certify the one immediately preceding it. Because
certificate validation requires that trust anchors be distributed certificate validation requires that trust anchors be distributed
independently, a certificate that specifies a trust anchor MAY be independently, a certificate that specifies a trust anchor MAY be
omitted from the chain, provided that supported peers are known to omitted from the chain, provided that supported peers are known to
possess any omitted certificates. possess any omitted certificates.
Note: Prior to TLS 1.3, "certificate_list" ordering required each Note: Prior to TLS 1.3, "certificate_list" ordering required each
skipping to change at page 69, line 44 skipping to change at page 66, line 20
authentication request. authentication request.
4.4.2.1. OCSP Status and SCT Extensions 4.4.2.1. OCSP Status and SCT Extensions
[RFC6066] and [RFC6961] provide extensions to negotiate the server [RFC6066] and [RFC6961] provide extensions to negotiate the server
sending OCSP responses to the client. In TLS 1.2 and below, the sending OCSP responses to the client. In TLS 1.2 and below, the
server replies with an empty extension to indicate negotiation of server replies with an empty extension to indicate negotiation of
this extension and the OCSP information is carried in a this extension and the OCSP information is carried in a
CertificateStatus message. In TLS 1.3, the server's OCSP information CertificateStatus message. In TLS 1.3, the server's OCSP information
is carried in an extension in the CertificateEntry containing the is carried in an extension in the CertificateEntry containing the
associated certificate. Specifically: The body of the associated certificate. Specifically, the body of the
"status_request" extension from the server MUST be a "status_request" extension from the server MUST be a
CertificateStatus structure as defined in [RFC6066], which is CertificateStatus structure as defined in [RFC6066], which is
interpreted as defined in [RFC6960]. interpreted as defined in [RFC6960].
Note: status_request_v2 extension ([RFC6961]) is deprecated. TLS 1.3 Note: The status_request_v2 extension [RFC6961] is deprecated.
servers MUST NOT act upon its presence or information in it when TLS 1.3 servers MUST NOT act upon its presence or information in it
processing Client Hello, in particular they MUST NOT send the when processing ClientHello messages; in particular, they MUST NOT
status_request_v2 extension in the Encrypted Extensions, Certificate send the status_request_v2 extension in the EncryptedExtensions,
Request or the Certificate messages. TLS 1.3 servers MUST be able to CertificateRequest, or Certificate messages. TLS 1.3 servers MUST be
process Client Hello messages that include it, as it MAY be sent by able to process ClientHello messages that include it, as it MAY be
clients that wish to use it in earlier protocol versions. sent by clients that wish to use it in earlier protocol versions.
A server MAY request that a client present an OCSP response with its A server MAY request that a client present an OCSP response with its
certificate by sending an empty "status_request" extension in its certificate by sending an empty "status_request" extension in its
CertificateRequest message. If the client opts to send an OCSP CertificateRequest message. If the client opts to send an OCSP
response, the body of its "status_request" extension MUST be a response, the body of its "status_request" extension MUST be a
CertificateStatus structure as defined in [RFC6066]. CertificateStatus structure as defined in [RFC6066].
Similarly, [RFC6962] provides a mechanism for a server to send a Similarly, [RFC6962] provides a mechanism for a server to send a
Signed Certificate Timestamp (SCT) as an extension in the ServerHello Signed Certificate Timestamp (SCT) as an extension in the ServerHello
in TLS 1.2 and below. In TLS 1.3, the server's SCT information is in TLS 1.2 and below. In TLS 1.3, the server's SCT information is
carried in an extension in CertificateEntry. carried in an extension in the CertificateEntry.
4.4.2.2. Server Certificate Selection 4.4.2.2. Server Certificate Selection
The following rules apply to the certificates sent by the server: The following rules apply to the certificates sent by the server:
- The certificate type MUST be X.509v3 [RFC5280], unless explicitly - The certificate type MUST be X.509v3 [RFC5280], unless explicitly
negotiated otherwise (e.g., [RFC7250]). negotiated otherwise (e.g., [RFC7250]).
- The server's end-entity certificate's public key (and associated - The server's end-entity certificate's public key (and associated
restrictions) MUST be compatible with the selected authentication restrictions) MUST be compatible with the selected authentication
skipping to change at page 70, line 44 skipping to change at page 67, line 29
present) with a signature scheme indicated in the client's present) with a signature scheme indicated in the client's
"signature_algorithms"/"signature_algorithms_cert" extensions (see "signature_algorithms"/"signature_algorithms_cert" extensions (see
Section 4.2.3). Section 4.2.3).
- The "server_name" [RFC6066] and "certificate_authorities" - The "server_name" [RFC6066] and "certificate_authorities"
extensions are used to guide certificate selection. As servers extensions are used to guide certificate selection. As servers
MAY require the presence of the "server_name" extension, clients MAY require the presence of the "server_name" extension, clients
SHOULD send this extension, when applicable. SHOULD send this extension, when applicable.
All certificates provided by the server MUST be signed by a signature All certificates provided by the server MUST be signed by a signature
algorithm advertised by the client, if it is able to provide such a algorithm advertised by the client if it is able to provide such a
chain (see Section 4.2.3). Certificates that are self-signed or chain (see Section 4.2.3). Certificates that are self-signed or
certificates that are expected to be trust anchors are not validated certificates that are expected to be trust anchors are not validated
as part of the chain and therefore MAY be signed with any algorithm. as part of the chain and therefore MAY be signed with any algorithm.
If the server cannot produce a certificate chain that is signed only If the server cannot produce a certificate chain that is signed only
via the indicated supported algorithms, then it SHOULD continue the via the indicated supported algorithms, then it SHOULD continue the
handshake by sending the client a certificate chain of its choice handshake by sending the client a certificate chain of its choice
that may include algorithms that are not known to be supported by the that may include algorithms that are not known to be supported by the
client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash client. This fallback chain SHOULD NOT use the deprecated SHA-1 hash
algorithm in general, but MAY do so if the client's advertisement algorithm in general, but MAY do so if the client's advertisement
permits it, and MUST NOT do so otherwise. permits it, and MUST NOT do so otherwise.
If the client cannot construct an acceptable chain using the provided If the client cannot construct an acceptable chain using the provided
certificates and decides to abort the handshake, then it MUST abort certificates and decides to abort the handshake, then it MUST abort
the handshake with an appropriate certificate-related alert (by the handshake with an appropriate certificate-related alert (by
default, "unsupported_certificate"; see Section 6.2 for more). default, "unsupported_certificate"; see Section 6.2 for more
information).
If the server has multiple certificates, it chooses one of them based If the server has multiple certificates, it chooses one of them based
on the above-mentioned criteria (in addition to other criteria, such on the above-mentioned criteria (in addition to other criteria, such
as transport layer endpoint, local configuration and preferences). as transport-layer endpoint, local configuration, and preferences).
4.4.2.3. Client Certificate Selection 4.4.2.3. Client Certificate Selection
The following rules apply to certificates sent by the client: The following rules apply to certificates sent by the client:
- The certificate type MUST be X.509v3 [RFC5280], unless explicitly - The certificate type MUST be X.509v3 [RFC5280], unless explicitly
negotiated otherwise (e.g., [RFC7250]). negotiated otherwise (e.g., [RFC7250]).
- If the "certificate_authorities" extension in the - If the "certificate_authorities" extension in the
CertificateRequest message was present, at least one of the CertificateRequest message was present, at least one of the
skipping to change at page 71, line 40 skipping to change at page 68, line 27
- The certificates MUST be signed using an acceptable signature - The certificates MUST be signed using an acceptable signature
algorithm, as described in Section 4.3.2. Note that this relaxes algorithm, as described in Section 4.3.2. Note that this relaxes
the constraints on certificate-signing algorithms found in prior the constraints on certificate-signing algorithms found in prior
versions of TLS. versions of TLS.
- If the CertificateRequest message contained a non-empty - If the CertificateRequest message contained a non-empty
"oid_filters" extension, the end-entity certificate MUST match the "oid_filters" extension, the end-entity certificate MUST match the
extension OIDs that are recognized by the client, as described in extension OIDs that are recognized by the client, as described in
Section 4.2.5. Section 4.2.5.
Note that, as with the server certificate, there are certificates
that use algorithm combinations that cannot be currently used with
TLS.
4.4.2.4. Receiving a Certificate Message 4.4.2.4. Receiving a Certificate Message
In general, detailed certificate validation procedures are out of In general, detailed certificate validation procedures are out of
scope for TLS (see [RFC5280]). This section provides TLS-specific scope for TLS (see [RFC5280]). This section provides TLS-specific
requirements. requirements.
If the server supplies an empty Certificate message, the client MUST If the server supplies an empty Certificate message, the client MUST
abort the handshake with a "decode_error" alert. abort the handshake with a "decode_error" alert.
If the client does not send any certificates (i.e., it sends an empty If the client does not send any certificates (i.e., it sends an empty
Certificate message), the server MAY at its discretion either Certificate message), the server MAY at its discretion either
continue the handshake without client authentication, or abort the continue the handshake without client authentication or abort the
handshake with a "certificate_required" alert. Also, if some aspect handshake with a "certificate_required" alert. Also, if some aspect
of the certificate chain was unacceptable (e.g., it was not signed by of the certificate chain was unacceptable (e.g., it was not signed by
a known, trusted CA), the server MAY at its discretion either a known, trusted CA), the server MAY at its discretion either
continue the handshake (considering the client unauthenticated) or continue the handshake (considering the client unauthenticated) or
abort the handshake. abort the handshake.
Any endpoint receiving any certificate which it would need to Any endpoint receiving any certificate which it would need to
validate using any signature algorithm using an MD5 hash MUST abort validate using any signature algorithm using an MD5 hash MUST abort
the handshake with a "bad_certificate" alert. SHA-1 is deprecated the handshake with a "bad_certificate" alert. SHA-1 is deprecated,
and it is RECOMMENDED that any endpoint receiving any certificate and it is RECOMMENDED that any endpoint receiving any certificate
which it would need to validate using any signature algorithm using a which it would need to validate using any signature algorithm using a
SHA-1 hash abort the handshake with a "bad_certificate" alert. For SHA-1 hash abort the handshake with a "bad_certificate" alert. For
clarity, this means that endpoints MAY accept these algorithms for clarity, this means that endpoints can accept these algorithms for
certificates that are self-signed or are trust anchors. certificates that are self-signed or are trust anchors.
All endpoints are RECOMMENDED to transition to SHA-256 or better as All endpoints are RECOMMENDED to transition to SHA-256 or better as
soon as possible to maintain interoperability with implementations soon as possible to maintain interoperability with implementations
currently in the process of phasing out SHA-1 support. currently in the process of phasing out SHA-1 support.
Note that a certificate containing a key for one signature algorithm Note that a certificate containing a key for one signature algorithm
MAY be signed using a different signature algorithm (for instance, an MAY be signed using a different signature algorithm (for instance, an
RSA key signed with an ECDSA key). RSA key signed with an ECDSA key).
skipping to change at page 72, line 51 skipping to change at page 69, line 33
message. message.
Structure of this message: Structure of this message:
struct { struct {
SignatureScheme algorithm; SignatureScheme algorithm;
opaque signature<0..2^16-1>; opaque signature<0..2^16-1>;
} CertificateVerify; } CertificateVerify;
The algorithm field specifies the signature algorithm used (see The algorithm field specifies the signature algorithm used (see
Section 4.2.3 for the definition of this field). The signature is a Section 4.2.3 for the definition of this type). The signature is a
digital signature using that algorithm. The content that is covered digital signature using that algorithm. The content that is covered
under the signature is the hash output as described in Section 4.4.1, under the signature is the hash output as described in Section 4.4.1,
namely: namely:
Transcript-Hash(Handshake Context, Certificate) Transcript-Hash(Handshake Context, Certificate)
The digital signature is then computed over the concatenation of: The digital signature is then computed over the concatenation of:
- A string that consists of octet 32 (0x20) repeated 64 times - A string that consists of octet 32 (0x20) repeated 64 times
skipping to change at page 73, line 18 skipping to change at page 70, line 4
The digital signature is then computed over the concatenation of: The digital signature is then computed over the concatenation of:
- A string that consists of octet 32 (0x20) repeated 64 times - A string that consists of octet 32 (0x20) repeated 64 times
- The context string - The context string
- A single 0 byte which serves as the separator - A single 0 byte which serves as the separator
- The content to be signed - The content to be signed
This structure is intended to prevent an attack on previous versions This structure is intended to prevent an attack on previous versions
of TLS in which the ServerKeyExchange format meant that attackers of TLS in which the ServerKeyExchange format meant that attackers
could obtain a signature of a message with a chosen 32-byte prefix could obtain a signature of a message with a chosen 32-byte prefix
(ClientHello.random). The initial 64-byte pad clears that prefix (ClientHello.random). The initial 64-byte pad clears that prefix
along with the server-controlled ServerHello.random. along with the server-controlled ServerHello.random.
The context string for a server signature is: "TLS 1.3, server The context string for a server signature is
CertificateVerify" The context string for a client signature is: "TLS "TLS 1.3, server CertificateVerify". The context string for a
1.3, client CertificateVerify" It is used to provide separation client signature is "TLS 1.3, client CertificateVerify". It is
between signatures made in different contexts, helping against used to provide separation between signatures made in different
potential cross-protocol attacks. contexts, helping against potential cross-protocol attacks.
For example, if the transcript hash was 32 bytes of 01 (this length For example, if the transcript hash was 32 bytes of 01 (this length
would make sense for SHA-256), the content covered by the digital would make sense for SHA-256), the content covered by the digital
signature for a server CertificateVerify would be: signature for a server CertificateVerify would be:
2020202020202020202020202020202020202020202020202020202020202020 2020202020202020202020202020202020202020202020202020202020202020
2020202020202020202020202020202020202020202020202020202020202020 2020202020202020202020202020202020202020202020202020202020202020
544c5320312e332c207365727665722043657274696669636174655665726966 544c5320312e332c207365727665722043657274696669636174655665726966
79 79
00 00
0101010101010101010101010101010101010101010101010101010101010101 0101010101010101010101010101010101010101010101010101010101010101
On the sender side the process for computing the signature field of On the sender side, the process for computing the signature field of
the CertificateVerify message takes as input: the CertificateVerify message takes as input:
- The content covered by the digital signature - The content covered by the digital signature
- The private signing key corresponding to the certificate sent in - The private signing key corresponding to the certificate sent in
the previous message the previous message
If the CertificateVerify message is sent by a server, the signature If the CertificateVerify message is sent by a server, the signature
algorithm MUST be one offered in the client's "signature_algorithms" algorithm MUST be one offered in the client's "signature_algorithms"
extension unless no valid certificate chain can be produced without extension unless no valid certificate chain can be produced without
skipping to change at page 74, line 27 skipping to change at page 71, line 15
All SHA-1 signature algorithms in this specification are defined All SHA-1 signature algorithms in this specification are defined
solely for use in legacy certificates and are not valid for solely for use in legacy certificates and are not valid for
CertificateVerify signatures. CertificateVerify signatures.
The receiver of a CertificateVerify message MUST verify the signature The receiver of a CertificateVerify message MUST verify the signature
field. The verification process takes as input: field. The verification process takes as input:
- The content covered by the digital signature - The content covered by the digital signature
- The public key contained in the end-entity certificate found in - The public key contained in the end-entity certificate found in
the associated Certificate message. the associated Certificate message
- The digital signature received in the signature field of the - The digital signature received in the signature field of the
CertificateVerify message CertificateVerify message
If the verification fails, the receiver MUST terminate the handshake If the verification fails, the receiver MUST terminate the handshake
with a "decrypt_error" alert. with a "decrypt_error" alert.
4.4.4. Finished 4.4.4. Finished
The Finished message is the final message in the authentication The Finished message is the final message in the Authentication
block. It is essential for providing authentication of the handshake Block. It is essential for providing authentication of the handshake
and of the computed keys. and of the computed keys.
Recipients of Finished messages MUST verify that the contents are Recipients of Finished messages MUST verify that the contents are
correct and if incorrect MUST terminate the connection with a correct and if incorrect MUST terminate the connection with a
"decrypt_error" alert. "decrypt_error" alert.
Once a side has sent its Finished message and received and validated Once a side has sent its Finished message and has received and
the Finished message from its peer, it may begin to send and receive validated the Finished message from its peer, it may begin to send
application data over the connection. There are two settings in and receive Application Data over the connection. There are two
which it is permitted to send data prior to receiving the peer's settings in which it is permitted to send data prior to receiving the
Finished: peer's Finished:
1. Clients sending 0-RTT data as described in Section 4.2.10. 1. Clients sending 0-RTT data as described in Section 4.2.10.
2. Servers MAY send data after sending their first flight, but 2. Servers MAY send data after sending their first flight, but
because the handshake is not yet complete, they have no assurance because the handshake is not yet complete, they have no assurance
of either the peer's identity or of its liveness (i.e., the of either the peer's identity or its liveness (i.e., the
ClientHello might have been replayed). ClientHello might have been replayed).
The key used to compute the Finished message is computed from the The key used to compute the Finished message is computed from the
Base key defined in Section 4.4 using HKDF (see Section 7.1). Base Key defined in Section 4.4 using HKDF (see Section 7.1).
Specifically: Specifically:
finished_key = finished_key =
HKDF-Expand-Label(BaseKey, "finished", "", Hash.length) HKDF-Expand-Label(BaseKey, "finished", "", Hash.length)
Structure of this message: Structure of this message:
struct { struct {
opaque verify_data[Hash.length]; opaque verify_data[Hash.length];
} Finished; } Finished;
skipping to change at page 75, line 40 skipping to change at page 72, line 35
* Only included if present. * Only included if present.
HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted HMAC [RFC2104] uses the Hash algorithm for the handshake. As noted
above, the HMAC input can generally be implemented by a running hash, above, the HMAC input can generally be implemented by a running hash,
i.e., just the handshake hash at this point. i.e., just the handshake hash at this point.
In previous versions of TLS, the verify_data was always 12 octets In previous versions of TLS, the verify_data was always 12 octets
long. In TLS 1.3, it is the size of the HMAC output for the Hash long. In TLS 1.3, it is the size of the HMAC output for the Hash
used for the handshake. used for the handshake.
Note: Alerts and any other record types are not handshake messages Note: Alerts and any other non-handshake record types are not
and are not included in the hash computations. handshake messages and are not included in the hash computations.
Any records following a Finished message MUST be encrypted under the Any records following a Finished message MUST be encrypted under the
appropriate application traffic key as described in Section 7.2. In appropriate application traffic key as described in Section 7.2. In
particular, this includes any alerts sent by the server in response particular, this includes any alerts sent by the server in response
to client Certificate and CertificateVerify messages. to client Certificate and CertificateVerify messages.
4.5. End of Early Data 4.5. End of Early Data
struct {} EndOfEarlyData; struct {} EndOfEarlyData;
If the server sent an "early_data" extension, the client MUST send an If the server sent an "early_data" extension in EncryptedExtensions,
EndOfEarlyData message after receiving the server Finished. If the the client MUST send an EndOfEarlyData message after receiving the
server does not send an "early_data" extension, then the client MUST server Finished. If the server does not send an "early_data"
NOT send an EndOfEarlyData message. This message indicates that all extension in EncryptedExtensions, then the client MUST NOT send an
0-RTT application_data messages, if any, have been transmitted and EndOfEarlyData message. This message indicates that all 0-RTT
that the following records are protected under handshake traffic application_data messages, if any, have been transmitted and that the
keys. Servers MUST NOT send this message and clients receiving it following records are protected under handshake traffic keys.
MUST terminate the connection with an "unexpected_message" alert. Servers MUST NOT send this message, and clients receiving it MUST
This message is encrypted under keys derived from the terminate the connection with an "unexpected_message" alert. This
message is encrypted under keys derived from the
client_early_traffic_secret. client_early_traffic_secret.
4.6. Post-Handshake Messages 4.6. Post-Handshake Messages
TLS also allows other messages to be sent after the main handshake. TLS also allows other messages to be sent after the main handshake.
These messages use a handshake content type and are encrypted under These messages use a handshake content type and are encrypted under
the appropriate application traffic key. the appropriate application traffic key.
4.6.1. New Session Ticket Message 4.6.1. New Session Ticket Message
At any time after the server has received the client Finished At any time after the server has received the client Finished
message, it MAY send a NewSessionTicket message. This message message, it MAY send a NewSessionTicket message. This message
creates a unique association between the ticket value and a secret creates a unique association between the ticket value and a secret
PSK derived from the resumption master secret (see Section 7. PSK derived from the resumption master secret (see Section 7).
The client MAY use this PSK for future handshakes by including the The client MAY use this PSK for future handshakes by including the
ticket value in the "pre_shared_key" extension in its ClientHello ticket value in the "pre_shared_key" extension in its ClientHello
(Section 4.2.11). Servers MAY send multiple tickets on a single (Section 4.2.11). Servers MAY send multiple tickets on a single
connection, either immediately after each other or after specific connection, either immediately after each other or after specific
events (see Appendix C.4). For instance, the server might send a new events (see Appendix C.4). For instance, the server might send a new
ticket after post-handshake authentication in order to encapsulate ticket after post-handshake authentication in order to encapsulate
the additional client authentication state. Multiple tickets are the additional client authentication state. Multiple tickets are
useful for clients for a variety of purposes, including: useful for clients for a variety of purposes, including:
- Opening multiple parallel HTTP connections. - Opening multiple parallel HTTP connections.
- Performing connection racing across interfaces and address - Performing connection racing across interfaces and address
families via, e.g., Happy Eyeballs [RFC8305] or related families via (for example) Happy Eyeballs [RFC8305] or related
techniques. techniques.
Any ticket MUST only be resumed with a cipher suite that has the same Any ticket MUST only be resumed with a cipher suite that has the same
KDF hash algorithm as that used to establish the original connection. KDF hash algorithm as that used to establish the original connection.
Clients MUST only resume if the new SNI value is valid for the server Clients MUST only resume if the new SNI value is valid for the server
certificate presented in the original session, and SHOULD only resume certificate presented in the original session and SHOULD only resume
if the SNI value matches the one used in the original session. The if the SNI value matches the one used in the original session. The
latter is a performance optimization: normally, there is no reason to latter is a performance optimization: normally, there is no reason to
expect that different servers covered by a single certificate would expect that different servers covered by a single certificate would
be able to accept each other's tickets, hence attempting resumption be able to accept each other's tickets; hence, attempting resumption
in that case would waste a single-use ticket. If such an indication in that case would waste a single-use ticket. If such an indication
is provided (externally or by any other means), clients MAY resume is provided (externally or by any other means), clients MAY resume
with a different SNI value. with a different SNI value.
On resumption, if reporting an SNI value to the calling application, On resumption, if reporting an SNI value to the calling application,
implementations MUST use the value sent in the resumption ClientHello implementations MUST use the value sent in the resumption ClientHello
rather than the value sent in the previous session. Note that if a rather than the value sent in the previous session. Note that if a
server implementation declines all PSK identities with different SNI server implementation declines all PSK identities with different SNI
values, these two values are always the same. values, these two values are always the same.
Note: Although the resumption master secret depends on the client's Note: Although the resumption master secret depends on the client's
second flight, servers which do not request client authentication MAY second flight, a server which does not request client authentication
compute the remainder of the transcript independently and then send a MAY compute the remainder of the transcript independently and then
NewSessionTicket immediately upon sending its Finished rather than send a NewSessionTicket immediately upon sending its Finished rather
waiting for the client Finished. This might be appropriate in cases than waiting for the client Finished. This might be appropriate in
where the client is expected to open multiple TLS connections in cases where the client is expected to open multiple TLS connections
parallel and would benefit from the reduced overhead of a resumption in parallel and would benefit from the reduced overhead of a
handshake, for example. resumption handshake, for example.
struct { struct {
uint32 ticket_lifetime; uint32 ticket_lifetime;
uint32 ticket_age_add; uint32 ticket_age_add;
opaque ticket_nonce<0..255>; opaque ticket_nonce<0..255>;
opaque ticket<1..2^16-1>; opaque ticket<1..2^16-1>;
Extension extensions<0..2^16-2>; Extension extensions<0..2^16-2>;
} NewSessionTicket; } NewSessionTicket;
ticket_lifetime Indicates the lifetime in seconds as a 32-bit ticket_lifetime: Indicates the lifetime in seconds as a 32-bit
unsigned integer in network byte order from the time of ticket unsigned integer in network byte order from the time of ticket
issuance. Servers MUST NOT use any value greater than 604800 issuance. Servers MUST NOT use any value greater than
seconds (7 days). The value of zero indicates that the ticket 604800 seconds (7 days). The value of zero indicates that the
should be discarded immediately. Clients MUST NOT cache tickets ticket should be discarded immediately. Clients MUST NOT cache
for longer than 7 days, regardless of the ticket_lifetime, and MAY tickets for longer than 7 days, regardless of the ticket_lifetime,
delete tickets earlier based on local policy. A server MAY treat and MAY delete tickets earlier based on local policy. A server
a ticket as valid for a shorter period of time than what is stated MAY treat a ticket as valid for a shorter period of time than what
in the ticket_lifetime. is stated in the ticket_lifetime.
ticket_age_add A securely generated, random 32-bit value that is ticket_age_add: A securely generated, random 32-bit value that is
used to obscure the age of the ticket that the client includes in used to obscure the age of the ticket that the client includes in
the "pre_shared_key" extension. The client-side ticket age is the "pre_shared_key" extension. The client-side ticket age is
added to this value modulo 2^32 to obtain the value that is added to this value modulo 2^32 to obtain the value that is
transmitted by the client. The server MUST generate a fresh value transmitted by the client. The server MUST generate a fresh value
for each ticket it sends. for each ticket it sends.
ticket_nonce A per-ticket value that is unique across all tickets ticket_nonce: A per-ticket value that is unique across all tickets
issued on this connection. issued on this connection.
ticket The value of the ticket to be used as the PSK identity. The ticket: The value of the ticket to be used as the PSK identity. The
ticket itself is an opaque label. It MAY either be a database ticket itself is an opaque label. It MAY be either a database
lookup key or a self-encrypted and self-authenticated value. lookup key or a self-encrypted and self-authenticated value.
Section 4 of [RFC5077] describes a recommended ticket construction
mechanism.
extensions A set of extension values for the ticket. The extensions: A set of extension values for the ticket. The
"Extension" format is defined in Section 4.2. Clients MUST ignore "Extension" format is defined in Section 4.2. Clients MUST ignore
unrecognized extensions. unrecognized extensions.
The sole extension currently defined for NewSessionTicket is The sole extension currently defined for NewSessionTicket is
"early_data", indicating that the ticket may be used to send 0-RTT "early_data", indicating that the ticket may be used to send 0-RTT
data (Section 4.2.10)). It contains the following value: data (Section 4.2.10). It contains the following value:
max_early_data_size The maximum amount of 0-RTT data that the client max_early_data_size: The maximum amount of 0-RTT data that the
is allowed to send when using this ticket, in bytes. Only client is allowed to send when using this ticket, in bytes. Only
Application Data payload (i.e., plaintext but not padding or the Application Data payload (i.e., plaintext but not padding or the
inner content type byte) is counted. A server receiving more than inner content type byte) is counted. A server receiving more than
max_early_data_size bytes of 0-RTT data SHOULD terminate the max_early_data_size bytes of 0-RTT data SHOULD terminate the
connection with an "unexpected_message" alert. Note that servers connection with an "unexpected_message" alert. Note that servers
that reject early data due to lack of cryptographic material will that reject early data due to lack of cryptographic material will
be unable to differentiate padding from content, so clients SHOULD be unable to differentiate padding from content, so clients
NOT depend on being able to send large quantities of padding in SHOULD NOT depend on being able to send large quantities of
early data records. padding in early data records.
The PSK associated with the ticket is computed as: The PSK associated with the ticket is computed as:
HKDF-Expand-Label(resumption_master_secret, HKDF-Expand-Label(resumption_master_secret,
"resumption", ticket_nonce, Hash.length) "resumption", ticket_nonce, Hash.length)
Because the ticket_nonce value is distinct for each NewSessionTicket Because the ticket_nonce value is distinct for each NewSessionTicket
message, a different PSK will be derived for each ticket. message, a different PSK will be derived for each ticket.
Note that in principle it is possible to continue issuing new tickets Note that in principle it is possible to continue issuing new tickets
skipping to change at page 79, line 24 skipping to change at page 76, line 22
Note: Because client authentication could involve prompting the user, Note: Because client authentication could involve prompting the user,
servers MUST be prepared for some delay, including receiving an servers MUST be prepared for some delay, including receiving an
arbitrary number of other messages between sending the arbitrary number of other messages between sending the
CertificateRequest and receiving a response. In addition, clients CertificateRequest and receiving a response. In addition, clients
which receive multiple CertificateRequests in close succession MAY which receive multiple CertificateRequests in close succession MAY
respond to them in a different order than they were received (the respond to them in a different order than they were received (the
certificate_request_context value allows the server to disambiguate certificate_request_context value allows the server to disambiguate
the responses). the responses).
4.6.3. Key and IV Update 4.6.3. Key and Initialization Vector Update
The KeyUpdate handshake message is used to indicate that the sender
is updating its sending cryptographic keys. This message can be sent
by either peer after it has sent a Finished message. Implementations
that receive a KeyUpdate message prior to receiving a Finished
message MUST terminate the connection with an "unexpected_message"
alert. After sending a KeyUpdate message, the sender SHALL send all
its traffic using the next generation of keys, computed as described
in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update
its receiving keys.
enum { enum {
update_not_requested(0), update_requested(1), (255) update_not_requested(0), update_requested(1), (255)
} KeyUpdateRequest; } KeyUpdateRequest;
struct { struct {
KeyUpdateRequest request_update; KeyUpdateRequest request_update;
} KeyUpdate; } KeyUpdate;
request_update Indicates whether the recipient of the KeyUpdate request_update: Indicates whether the recipient of the KeyUpdate
should respond with its own KeyUpdate. If an implementation should respond with its own KeyUpdate. If an implementation
receives any other value, it MUST terminate the connection with an receives any other value, it MUST terminate the connection with an
"illegal_parameter" alert. "illegal_parameter" alert.
The KeyUpdate handshake message is used to indicate that the sender If the request_update field is set to "update_requested", then the
is updating its sending cryptographic keys. This message can be sent
by either peer after it has sent a Finished message. Implementations
that receive a KeyUpdate message prior to receiving a Finished
message MUST terminate the connection with an "unexpected_message"
alert. After sending a KeyUpdate message, the sender SHALL send all
its traffic using the next generation of keys, computed as described
in Section 7.2. Upon receiving a KeyUpdate, the receiver MUST update
its receiving keys.
If the request_update field is set to "update_requested" then the
receiver MUST send a KeyUpdate of its own with request_update set to receiver MUST send a KeyUpdate of its own with request_update set to
"update_not_requested" prior to sending its next application data "update_not_requested" prior to sending its next Application Data
record. This mechanism allows either side to force an update to the record. This mechanism allows either side to force an update to the
entire connection, but causes an implementation which receives entire connection, but causes an implementation which receives
multiple KeyUpdates while it is silent to respond with a single multiple KeyUpdates while it is silent to respond with a single
update. Note that implementations may receive an arbitrary number of update. Note that implementations may receive an arbitrary number of
messages between sending a KeyUpdate with request_update set to messages between sending a KeyUpdate with request_update set to
update_requested and receiving the peer's KeyUpdate, because those "update_requested" and receiving the peer's KeyUpdate, because those
messages may already be in flight. However, because send and receive messages may already be in flight. However, because send and receive
keys are derived from independent traffic secrets, retaining the keys are derived from independent traffic secrets, retaining the
receive traffic secret does not threaten the forward secrecy of data receive traffic secret does not threaten the forward secrecy of data
sent before the sender changed keys. sent before the sender changed keys.
If implementations independently send their own KeyUpdates with If implementations independently send their own KeyUpdates with
request_update set to "update_requested", and they cross in flight, request_update set to "update_requested" and they cross in flight,
then each side will also send a response, with the result that each then each side will also send a response, with the result that each
side increments by two generations. side increments by two generations.
Both sender and receiver MUST encrypt their KeyUpdate messages with Both sender and receiver MUST encrypt their KeyUpdate messages with
the old keys. Additionally, both sides MUST enforce that a KeyUpdate the old keys. Additionally, both sides MUST enforce that a KeyUpdate
with the old key is received before accepting any messages encrypted with the old key is received before accepting any messages encrypted
with the new key. Failure to do so may allow message truncation with the new key. Failure to do so may allow message truncation
attacks. attacks.
5. Record Protocol 5. Record Protocol
The TLS record protocol takes messages to be transmitted, fragments The TLS record protocol takes messages to be transmitted, fragments
the data into manageable blocks, protects the records, and transmits the data into manageable blocks, protects the records, and transmits
the result. Received data is verified, decrypted, reassembled, and the result. Received data is verified, decrypted, reassembled, and
then delivered to higher-level clients. then delivered to higher-level clients.
TLS records are typed, which allows multiple higher-level protocols TLS records are typed, which allows multiple higher-level protocols
to be multiplexed over the same record layer. This document to be multiplexed over the same record layer. This document
specifies four content types: handshake, application data, alert, and specifies four content types: handshake, application_data, alert, and
change_cipher_spec. The change_cipher_spec record is used only for change_cipher_spec. The change_cipher_spec record is used only for
compatibility purposes (see Appendix D.4). compatibility purposes (see Appendix D.4).
An implementation may receive an unencrypted record of type An implementation may receive an unencrypted record of type
change_cipher_spec consisting of the single byte value 0x01 at any change_cipher_spec consisting of the single byte value 0x01 at any
time after the first ClientHello message has been sent or received time after the first ClientHello message has been sent or received
and before the peer's Finished message has been received and MUST and before the peer's Finished message has been received and MUST
simply drop it without further processing. Note that this record may simply drop it without further processing. Note that this record may
appear at a point at the handshake where the implementation is appear at a point at the handshake where the implementation is
expecting protected records and so it is necessary to detect this expecting protected records, and so it is necessary to detect this
condition prior to attempting to deprotect the record. An condition prior to attempting to deprotect the record. An
implementation which receives any other change_cipher_spec value or implementation which receives any other change_cipher_spec value or
which receives a protected change_cipher_spec record MUST abort the which receives a protected change_cipher_spec record MUST abort the
handshake with an "unexpected_message" alert. A change_cipher_spec handshake with an "unexpected_message" alert. If an implementation
record received before the first ClientHello message or after the detects a change_cipher_spec record received before the first
peer's Finished message MUST be treated as an unexpected record type ClientHello message or after the peer's Finished message, it MUST be
(though stateless servers may not be able to distinguish these cases treated as an unexpected record type (though stateless servers may
from allowed cases). not be able to distinguish these cases from allowed cases).
Implementations MUST NOT send record types not defined in this Implementations MUST NOT send record types not defined in this
document unless negotiated by some extension. If a TLS document unless negotiated by some extension. If a TLS
implementation receives an unexpected record type, it MUST terminate implementation receives an unexpected record type, it MUST terminate
the connection with an "unexpected_message" alert. New record the connection with an "unexpected_message" alert. New record
content type values are assigned by IANA in the TLS Content Type content type values are assigned by IANA in the TLS ContentType
Registry as described in Section 11. registry as described in Section 11.
5.1. Record Layer 5.1. Record Layer
The record layer fragments information blocks into TLSPlaintext The record layer fragments information blocks into TLSPlaintext
records carrying data in chunks of 2^14 bytes or less. Message records carrying data in chunks of 2^14 bytes or less. Message
boundaries are handled differently depending on the underlying boundaries are handled differently depending on the underlying
ContentType. Any future content types MUST specify appropriate ContentType. Any future content types MUST specify appropriate
rules. Note that these rules are stricter than what was enforced in rules. Note that these rules are stricter than what was enforced in
TLS 1.2. TLS 1.2.
skipping to change at page 81, line 41 skipping to change at page 78, line 39
MUST verify that all messages immediately preceding a key change MUST verify that all messages immediately preceding a key change
align with a record boundary; if not, then they MUST terminate the align with a record boundary; if not, then they MUST terminate the
connection with an "unexpected_message" alert. Because the connection with an "unexpected_message" alert. Because the
ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate
messages can immediately precede a key change, implementations messages can immediately precede a key change, implementations
MUST send these messages in alignment with a record boundary. MUST send these messages in alignment with a record boundary.
Implementations MUST NOT send zero-length fragments of Handshake Implementations MUST NOT send zero-length fragments of Handshake
types, even if those fragments contain padding. types, even if those fragments contain padding.
Alert messages (Section 6) MUST NOT be fragmented across records and Alert messages (Section 6) MUST NOT be fragmented across records, and
multiple Alert messages MUST NOT be coalesced into a single multiple alert messages MUST NOT be coalesced into a single
TLSPlaintext record. In other words, a record with an Alert type TLSPlaintext record. In other words, a record with an Alert type
MUST contain exactly one message. MUST contain exactly one message.
Application Data messages contain data that is opaque to TLS. Application Data messages contain data that is opaque to TLS.
Application Data messages are always protected. Zero-length Application Data messages are always protected. Zero-length
fragments of Application Data MAY be sent as they are potentially fragments of Application Data MAY be sent, as they are potentially
useful as a traffic analysis countermeasure. Application Data useful as a traffic analysis countermeasure. Application Data
fragments MAY be split across multiple records or coalesced into a fragments MAY be split across multiple records or coalesced into a
single record. single record.
enum { enum {
invalid(0), invalid(0),
change_cipher_spec(20), change_cipher_spec(20),
alert(21), alert(21),
handshake(22), handshake(22),
application_data(23), application_data(23),
(255) (255)
} ContentType; } ContentType;
struct { struct {
ContentType type; ContentType type;
ProtocolVersion legacy_record_version; ProtocolVersion legacy_record_version;
uint16 length; uint16 length;
opaque fragment[TLSPlaintext.length]; opaque fragment[TLSPlaintext.length];
} TLSPlaintext; } TLSPlaintext;
type The higher-level protocol used to process the enclosed type: The higher-level protocol used to process the enclosed
fragment. fragment.
legacy_record_version This value MUST be set to 0x0303 for all legacy_record_version: MUST be set to 0x0303 for all records
records generated by a TLS 1.3 implementation other than an generated by a TLS 1.3 implementation other than an initial
initial ClientHello (i.e., one not generated after a ClientHello (i.e., one not generated after a HelloRetryRequest),
HelloRetryRequest), where it MAY also be 0x0301 for compatibility where it MAY also be 0x0301 for compatibility purposes. This
purposes. This field is deprecated and MUST be ignored for all field is deprecated and MUST be ignored for all purposes.
purposes. Previous versions of TLS would use other values in this Previous versions of TLS would use other values in this field
field under some circumstances. under some circumstances.
length The length (in bytes) of the following TLSPlaintext.fragment. length: The length (in bytes) of the following
The length MUST NOT exceed 2^14 bytes. An endpoint that receives TLSPlaintext.fragment. The length MUST NOT exceed 2^14 bytes. An
a record that exceeds this length MUST terminate the connection endpoint that receives a record that exceeds this length MUST
with a "record_overflow" alert. terminate the connection with a "record_overflow" alert.
fragment The data being transmitted. This value is transparent and fragment: The data being transmitted. This value is transparent and
is treated as an independent block to be dealt with by the higher- is treated as an independent block to be dealt with by the higher-
level protocol specified by the type field. level protocol specified by the type field.
This document describes TLS 1.3, which uses the version 0x0304. This This document describes TLS 1.3, which uses the version 0x0304. This
version value is historical, deriving from the use of 0x0301 for TLS version value is historical, deriving from the use of 0x0301 for
1.0 and 0x0300 for SSL 3.0. In order to maximize backwards TLS 1.0 and 0x0300 for SSL 3.0. In order to maximize backward
compatibility, records containing an initial ClientHello SHOULD have compatibility, a record containing an initial ClientHello SHOULD have
version 0x0301 and a record containing a second ClientHello or a version 0x0301 (reflecting TLS 1.0) and a record containing a second
ServerHello MUST have version 0x0303, reflecting TLS 1.0 and TLS 1.2 ClientHello or a ServerHello MUST have version 0x0303 (reflecting
respectively. When negotiating prior versions of TLS, endpoints TLS 1.2). When negotiating prior versions of TLS, endpoints follow
follow the procedure and requirements in Appendix D. the procedure and requirements provided in Appendix D.
When record protection has not yet been engaged, TLSPlaintext When record protection has not yet been engaged, TLSPlaintext
structures are written directly onto the wire. Once record structures are written directly onto the wire. Once record
protection has started, TLSPlaintext records are protected and sent protection has started, TLSPlaintext records are protected and sent
as described in the following section. Note that application data as described in the following section. Note that Application Data
records MUST NOT be written to the wire unprotected (see Section 2 records MUST NOT be written to the wire unprotected (see Section 2
for details). for details).
5.2. Record Payload Protection 5.2. Record Payload Protection
The record protection functions translate a TLSPlaintext structure The record protection functions translate a TLSPlaintext structure
into a TLSCiphertext. The deprotection functions reverse the into a TLSCiphertext structure. The deprotection functions reverse
process. In TLS 1.3, as opposed to previous versions of TLS, all the process. In TLS 1.3, as opposed to previous versions of TLS, all
ciphers are modeled as "Authenticated Encryption with Additional ciphers are modeled as "Authenticated Encryption with Associated
Data" (AEAD) [RFC5116]. AEAD functions provide an unified encryption Data" (AEAD) [RFC5116]. AEAD functions provide a unified encryption
and authentication operation which turns plaintext into authenticated and authentication operation which turns plaintext into authenticated
ciphertext and back again. Each encrypted record consists of a ciphertext and back again. Each encrypted record consists of a
plaintext header followed by an encrypted body, which itself contains plaintext header followed by an encrypted body, which itself contains
a type and optional padding. a type and optional padding.
struct { struct {
opaque content[TLSPlaintext.length]; opaque content[TLSPlaintext.length];
ContentType type; ContentType type;
uint8 zeros[length_of_padding]; uint8 zeros[length_of_padding];
} TLSInnerPlaintext; } TLSInnerPlaintext;
struct { struct {
ContentType opaque_type = application_data; /* 23 */ ContentType opaque_type = application_data; /* 23 */
ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */ ProtocolVersion legacy_record_version = 0x0303; /* TLS v1.2 */
uint16 length; uint16 length;
opaque encrypted_record[TLSCiphertext.length]; opaque encrypted_record[TLSCiphertext.length];
} TLSCiphertext; } TLSCiphertext;
content The TLSPLaintext.fragment value, containing the byte content: The TLSPlaintext.fragment value, containing the byte
encoding of a handshake or an alert message, or the raw bytes of encoding of a handshake or an alert message, or the raw bytes of
the application's data to send. the application's data to send.
type The TLSPlaintext.type value containing the content type of the type: The TLSPlaintext.type value containing the content type of the
record. record.
zeros An arbitrary-length run of zero-valued bytes may appear in the zeros: An arbitrary-length run of zero-valued bytes may appear in
cleartext after the type field. This provides an opportunity for the cleartext after the type field. This provides an opportunity
senders to pad any TLS record by a chosen amount as long as the for senders to pad any TLS record by a chosen amount as long as
total stays within record size limits. See Section 5.4 for more the total stays within record size limits. See Section 5.4 for
details. more details.
opaque_type The outer opaque_type field of a TLSCiphertext record is opaque_type: The outer opaque_type field of a TLSCiphertext record
always set to the value 23 (application_data) for outward is always set to the value 23 (application_data) for outward
compatibility with middleboxes accustomed to parsing previous compatibility with middleboxes accustomed to parsing previous
versions of TLS. The actual content type of the record is found versions of TLS. The actual content type of the record is found
in TLSInnerPlaintext.type after decryption. in TLSInnerPlaintext.type after decryption.
legacy_record_version The legacy_record_version field is always legacy_record_version: The legacy_record_version field is always
0x0303. TLS 1.3 TLSCiphertexts are not generated until after TLS 0x0303. TLS 1.3 TLSCiphertexts are not generated until after
1.3 has been negotiated, so there are no historical compatibility TLS 1.3 has been negotiated, so there are no historical
concerns where other values might be received. Note that the compatibility concerns where other values might be received. Note
handshake protocol including the ClientHello and ServerHello that the handshake protocol, including the ClientHello and
messages authenticates the protocol version, so this value is ServerHello messages, authenticates the protocol version, so this
redundant. value is redundant.
length The length (in bytes) of the following length: The length (in bytes) of the following
TLSCiphertext.encrypted_record, which is the sum of the lengths of TLSCiphertext.encrypted_record, which is the sum of the lengths of
the content and the padding, plus one for the inner content type, the content and the padding, plus one for the inner content type,
plus any expansion added by the AEAD algorithm. The length MUST plus any expansion added by the AEAD algorithm. The length
NOT exceed 2^14 + 256 bytes. An endpoint that receives a record MUST NOT exceed 2^14 + 256 bytes. An endpoint that receives a
that exceeds this length MUST terminate the connection with a record that exceeds this length MUST terminate the connection with
"record_overflow" alert. a "record_overflow" alert.
encrypted_record The AEAD-encrypted form of the serialized encrypted_record: The AEAD-encrypted form of the serialized
TLSInnerPlaintext structure. TLSInnerPlaintext structure.
AEAD algorithms take as input a single key, a nonce, a plaintext, and AEAD algorithms take as input a single key, a nonce, a plaintext, and
"additional data" to be included in the authentication check, as "additional data" to be included in the authentication check, as
described in Section 2.1 of [RFC5116]. The key is either the described in Section 2.1 of [RFC5116]. The key is either the
client_write_key or the server_write_key, the nonce is derived from client_write_key or the server_write_key, the nonce is derived from
the sequence number and the client_write_iv or server_write_iv (see the sequence number and the client_write_iv or server_write_iv (see
Section 5.3), and the additional data input is the record header. Section 5.3), and the additional data input is the record header.
I.e., I.e.,
additional_data = TLSCiphertext.opaque_type || additional_data = TLSCiphertext.opaque_type ||
TLSCiphertext.legacy_record_version || TLSCiphertext.legacy_record_version ||
TLSCiphertext.length TLSCiphertext.length
The plaintext input to the AEAD algorithm is the encoded The plaintext input to the AEAD algorithm is the encoded
TLSInnerPlaintext structure. Derivation of traffic keys is defined TLSInnerPlaintext structure. Derivation of traffic keys is defined
in Section 7.3. in Section 7.3.
skipping to change at page 84, line 46 skipping to change at page 82, line 4
The plaintext input to the AEAD algorithm is the encoded The plaintext input to the AEAD algorithm is the encoded
TLSInnerPlaintext structure. Derivation of traffic keys is defined TLSInnerPlaintext structure. Derivation of traffic keys is defined
in Section 7.3. in Section 7.3.
The AEAD output consists of the ciphertext output from the AEAD The AEAD output consists of the ciphertext output from the AEAD
encryption operation. The length of the plaintext is greater than encryption operation. The length of the plaintext is greater than
the corresponding TLSPlaintext.length due to the inclusion of the corresponding TLSPlaintext.length due to the inclusion of
TLSInnerPlaintext.type and any padding supplied by the sender. The TLSInnerPlaintext.type and any padding supplied by the sender. The
length of the AEAD output will generally be larger than the length of the AEAD output will generally be larger than the
plaintext, but by an amount that varies with the AEAD algorithm. plaintext, but by an amount that varies with the AEAD algorithm.
Since the ciphers might incorporate padding, the amount of overhead Since the ciphers might incorporate padding, the amount of overhead
could vary with different lengths of plaintext. Symbolically, could vary with different lengths of plaintext. Symbolically,
AEADEncrypted = AEADEncrypted =
AEAD-Encrypt(write_key, nonce, additional_data, plaintext) AEAD-Encrypt(write_key, nonce, additional_data, plaintext)
Then the encrypted_record field of TLSCiphertext is set to The encrypted_record field of TLSCiphertext is set to AEADEncrypted.
AEADEncrypted.
In order to decrypt and verify, the cipher takes as input the key, In order to decrypt and verify, the cipher takes as input the key,
nonce, additional data, and the AEADEncrypted value. The output is nonce, additional data, and the AEADEncrypted value. The output is
either the plaintext or an error indicating that the decryption either the plaintext or an error indicating that the decryption
failed. There is no separate integrity check. That is: failed. There is no separate integrity check. Symbolically,
plaintext of encrypted_record = plaintext of encrypted_record =
AEAD-Decrypt(peer_write_key, nonce, additional_data, AEADEncrypted) AEAD-Decrypt(peer_write_key, nonce,
additional_data, AEADEncrypted)
If the decryption fails, the receiver MUST terminate the connection If the decryption fails, the receiver MUST terminate the connection
with a "bad_record_mac" alert. with a "bad_record_mac" alert.
An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion An AEAD algorithm used in TLS 1.3 MUST NOT produce an expansion
greater than 255 octets. An endpoint that receives a record from its greater than 255 octets. An endpoint that receives a record from its
peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST peer with TLSCiphertext.length larger than 2^14 + 256 octets MUST
terminate the connection with a "record_overflow" alert. This limit terminate the connection with a "record_overflow" alert. This limit
is derived from the maximum TLSInnerPlaintext length of 2^14 octets + is derived from the maximum TLSInnerPlaintext length of 2^14 octets +
1 octet for ContentType + the maximum AEAD expansion of 255 octets. 1 octet for ContentType + the maximum AEAD expansion of 255 octets.
skipping to change at page 85, line 37 skipping to change at page 82, line 43
A 64-bit sequence number is maintained separately for reading and A 64-bit sequence number is maintained separately for reading and
writing records. The appropriate sequence number is incremented by writing records. The appropriate sequence number is incremented by
one after reading or writing each record. Each sequence number is one after reading or writing each record. Each sequence number is
set to zero at the beginning of a connection and whenever the key is set to zero at the beginning of a connection and whenever the key is
changed; the first record transmitted under a particular traffic key changed; the first record transmitted under a particular traffic key
MUST use sequence number 0. MUST use sequence number 0.
Because the size of sequence numbers is 64-bit, they should not wrap. Because the size of sequence numbers is 64-bit, they should not wrap.
If a TLS implementation would need to wrap a sequence number, it MUST If a TLS implementation would need to wrap a sequence number, it MUST
either re-key (Section 4.6.3) or terminate the connection. either rekey (Section 4.6.3) or terminate the connection.
Each AEAD algorithm will specify a range of possible lengths for the Each AEAD algorithm will specify a range of possible lengths for the
per-record nonce, from N_MIN bytes to N_MAX bytes of input per-record nonce, from N_MIN bytes to N_MAX bytes of input [RFC5116].
([RFC5116]). The length of the TLS per-record nonce (iv_length) is The length of the TLS per-record nonce (iv_length) is set to the
set to the larger of 8 bytes and N_MIN for the AEAD algorithm (see larger of 8 bytes and N_MIN for the AEAD algorithm (see [RFC5116],
[RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 Section 4). An AEAD algorithm where N_MAX is less than 8 bytes
bytes MUST NOT be used with TLS. The per-record nonce for the AEAD MUST NOT be used with TLS. The per-record nonce for the AEAD
construction is formed as follows: construction is formed as follows:
1. The 64-bit record sequence number is encoded in network byte 1. The 64-bit record sequence number is encoded in network byte
order and padded to the left with zeros to iv_length. order and padded to the left with zeros to iv_length.
2. The padded sequence number is XORed with the static 2. The padded sequence number is XORed with either the static
client_write_iv or server_write_iv, depending on the role. client_write_iv or server_write_iv (depending on the role).
The resulting quantity (of length iv_length) is used as the per- The resulting quantity (of length iv_length) is used as the
record nonce. per-record nonce.
Note: This is a different construction from that in TLS 1.2, which Note: This is a different construction from that in TLS 1.2, which
specified a partially explicit nonce. specified a partially explicit nonce.
5.4. Record Padding 5.4. Record Padding
All encrypted TLS records can be padded to inflate the size of the All encrypted TLS records can be padded to inflate the size of the
TLSCiphertext. This allows the sender to hide the size of the TLSCiphertext. This allows the sender to hide the size of the
traffic from an observer. traffic from an observer.
When generating a TLSCiphertext record, implementations MAY choose to When generating a TLSCiphertext record, implementations MAY choose to
pad. An unpadded record is just a record with a padding length of pad. An unpadded record is just a record with a padding length of
zero. Padding is a string of zero-valued bytes appended to the zero. Padding is a string of zero-valued bytes appended to the
ContentType field before encryption. Implementations MUST set the ContentType field before encryption. Implementations MUST set the
padding octets to all zeros before encrypting. padding octets to all zeros before encrypting.
Application Data records may contain a zero-length Application Data records may contain a zero-length
TLSInnerPlaintext.content if the sender desires. This permits TLSInnerPlaintext.content if the sender desires. This permits
generation of plausibly-sized cover traffic in contexts where the generation of plausibly sized cover traffic in contexts where the
presence or absence of activity may be sensitive. Implementations presence or absence of activity may be sensitive. Implementations
MUST NOT send Handshake or Alert records that have a zero-length MUST NOT send Handshake and Alert records that have a zero-length
TLSInnerPlaintext.content; if such a message is received, the TLSInnerPlaintext.content; if such a message is received, the
receiving implementation MUST terminate the connection with an receiving implementation MUST terminate the connection with an
"unexpected_message" alert. "unexpected_message" alert.
The padding sent is automatically verified by the record protection The padding sent is automatically verified by the record protection
mechanism; upon successful decryption of a mechanism; upon successful decryption of a
TLSCiphertext.encrypted_record, the receiving implementation scans TLSCiphertext.encrypted_record, the receiving implementation scans
the field from the end toward the beginning until it finds a non-zero the field from the end toward the beginning until it finds a non-zero
octet. This non-zero octet is the content type of the message. This octet. This non-zero octet is the content type of the message. This
padding scheme was selected because it allows padding of any padding scheme was selected because it allows padding of any
skipping to change at page 86, line 49 skipping to change at page 84, line 22
size limits) without introducing new content types. The design also size limits) without introducing new content types. The design also
enforces all-zero padding octets, which allows for quick detection of enforces all-zero padding octets, which allows for quick detection of
padding errors. padding errors.
Implementations MUST limit their scanning to the cleartext returned Implementations MUST limit their scanning to the cleartext returned
from the AEAD decryption. If a receiving implementation does not from the AEAD decryption. If a receiving implementation does not
find a non-zero octet in the cleartext, it MUST terminate the find a non-zero octet in the cleartext, it MUST terminate the
connection with an "unexpected_message" alert. connection with an "unexpected_message" alert.
The presence of padding does not change the overall record size The presence of padding does not change the overall record size
limitations - the full encoded TLSInnerPlaintext MUST NOT exceed 2^14 limitations: the full encoded TLSInnerPlaintext MUST NOT exceed 2^14
+ 1 octets. If the maximum fragment length is reduced, as for + 1 octets. If the maximum fragment length is reduced -- as, for
example by the max_fragment_length extension from [RFC6066], then the example, by the record_size_limit extension from [RFC8449] -- then
reduced limit applies to the full plaintext, including the content the reduced limit applies to the full plaintext, including the
type and padding. content type and padding.
Selecting a padding policy that suggests when and how much to pad is 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 a complex topic and is beyond the scope of this specification. If
the application layer protocol on top of TLS has its own padding, it the application-layer protocol on top of TLS has its own padding, it
may be preferable to pad application_data TLS records within the may be preferable to pad Application Data TLS records within the
application layer. Padding for encrypted handshake and alert TLS application layer. Padding for encrypted Handshake or Alert records
records must still be handled at the TLS layer, though. Later must still be handled at the TLS layer, though. Later documents may
documents may define padding selection algorithms or define a padding define padding selection algorithms or define a padding policy
policy request mechanism through TLS extensions or some other means. request mechanism through TLS extensions or some other means.
5.5. Limits on Key Usage 5.5. Limits on Key Usage
There are cryptographic limits on the amount of plaintext which can There are cryptographic limits on the amount of plaintext which can
be safely encrypted under a given set of keys. [AEAD-LIMITS] be safely encrypted under a given set of keys. [AEAD-LIMITS]
provides an analysis of these limits under the assumption that the provides an analysis of these limits under the assumption that the
underlying primitive (AES or ChaCha20) has no weaknesses. underlying primitive (AES or ChaCha20) has no weaknesses.
Implementations SHOULD do a key update as described in Section 4.6.3 Implementations SHOULD do a key update as described in Section 4.6.3
prior to reaching these limits. prior to reaching these limits.
For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be For AES-GCM, up to 2^24.5 full-size records (about 24 million) may be
encrypted on a given connection while keeping a safety margin of encrypted on a given connection while keeping a safety margin of
approximately 2^-57 for Authenticated Encryption (AE) security. For approximately 2^-57 for Authenticated Encryption (AE) security. For
ChaCha20/Poly1305, the record sequence number would wrap before the ChaCha20/Poly1305, the record sequence number would wrap before the
safety limit is reached. safety limit is reached.
6. Alert Protocol 6. Alert Protocol
One of the content types supported by the TLS record layer is the TLS provides an Alert content type to indicate closure information
alert type. Like other messages, alert messages are encrypted as and errors. Like other messages, alert messages are encrypted as
specified by the current connection state. specified by the current connection state.
Alert messages convey a description of the alert and a legacy field Alert messages convey a description of the alert and a legacy field
that conveyed the severity of the message in previous versions of that conveyed the severity level of the message in previous versions
TLS. Alerts are divided into two classes: closure alerts and error of TLS. Alerts are divided into two classes: closure alerts and
alerts. In TLS 1.3, the severity is implicit in the type of alert error alerts. In TLS 1.3, the severity is implicit in the type of
being sent, and the 'level' field can safely be ignored. The alert being sent, and the "level" field can safely be ignored. The
"close_notify" alert is used to indicate orderly closure of one "close_notify" alert is used to indicate orderly closure of one
direction of the connection. Upon receiving such an alert, the TLS direction of the connection. Upon receiving such an alert, the TLS
implementation SHOULD indicate end-of-data to the application. implementation SHOULD indicate end-of-data to the application.
Error alerts indicate abortive closure of the connection (see Error alerts indicate abortive closure of the connection (see
Section 6.2). Upon receiving an error alert, the TLS implementation Section 6.2). Upon receiving an error alert, the TLS implementation
SHOULD indicate an error to the application and MUST NOT allow any SHOULD indicate an error to the application and MUST NOT allow any
further data to be sent or received on the connection. Servers and further data to be sent or received on the connection. Servers and
clients MUST forget the secret values and keys established in failed clients MUST forget the secret values and keys established in failed
connections, with the exception of the PSKs associated with session connections, with the exception of the PSKs associated with session
tickets, which SHOULD be discarded if possible. tickets, which SHOULD be discarded if possible.
All the alerts listed in Section 6.2 MUST be sent with All the alerts listed in Section 6.2 MUST be sent with
AlertLevel=fatal and MUST be treated as error alerts regardless of AlertLevel=fatal and MUST be treated as error alerts when received
the AlertLevel in the message. Unknown alert types MUST be treated regardless of the AlertLevel in the message. Unknown Alert types
as error alerts. MUST be treated as error alerts.
Note: TLS defines two generic alerts (see Section 6) to use upon Note: TLS defines two generic alerts (see Section 6) to use upon
failure to parse a message. Peers which receive a message which failure to parse a message. Peers which receive a message which
cannot be parsed according to the syntax (e.g., have a length cannot be parsed according to the syntax (e.g., have a length
extending beyond the message boundary or contain an out-of-range extending beyond the message boundary or contain an out-of-range
length) MUST terminate the connection with a "decode_error" alert. length) MUST terminate the connection with a "decode_error" alert.
Peers which receive a message which is syntactically correct but Peers which receive a message which is syntactically correct but
semantically invalid (e.g., a DHE share of p - 1, or an invalid enum) semantically invalid (e.g., a DHE share of p - 1, or an invalid enum)
MUST terminate the connection with an "illegal_parameter" alert. MUST terminate the connection with an "illegal_parameter" alert.
skipping to change at page 89, line 48 skipping to change at page 87, line 10
struct { struct {
AlertLevel level; AlertLevel level;
AlertDescription description; AlertDescription description;
} Alert; } Alert;
6.1. Closure Alerts 6.1. Closure Alerts
The client and the server must share knowledge that the connection is The client and the server must share knowledge that the connection is
ending in order to avoid a truncation attack. ending in order to avoid a truncation attack.
close_notify This alert notifies the recipient that the sender will close_notify: This alert notifies the recipient that the sender will
not send any more messages on this connection. Any data received not send any more messages on this connection. Any data received
after a closure alert has been received MUST be ignored. after a closure alert has been received MUST be ignored.
user_canceled This alert notifies the recipient that the sender is user_canceled: This alert notifies the recipient that the sender is
canceling the handshake for some reason unrelated to a protocol canceling the handshake for some reason unrelated to a protocol
failure. If a user cancels an operation after the handshake is failure. If a user cancels an operation after the handshake is
complete, just closing the connection by sending a "close_notify" complete, just closing the connection by sending a "close_notify"
is more appropriate. This alert SHOULD be followed by a is more appropriate. This alert SHOULD be followed by a
"close_notify". This alert generally has AlertLevel=warning. "close_notify". This alert generally has AlertLevel=warning.
Either party MAY initiate a close of its write side of the connection Either party MAY initiate a close of its write side of the connection
by sending a "close_notify" alert. Any data received after a closure by sending a "close_notify" alert. Any data received after a closure
alert has been received MUST be ignored. If a transport-level close alert has been received MUST be ignored. If a transport-level close
is received prior to a "close_notify", the receiver cannot know that is received prior to a "close_notify", the receiver cannot know that
skipping to change at page 90, line 33 skipping to change at page 87, line 42
discarding pending writes and sending an immediate "close_notify" discarding pending writes and sending an immediate "close_notify"
alert of their own. That previous requirement could cause truncation alert of their own. That previous requirement could cause truncation
in the read side. Both parties need not wait to receive a in the read side. Both parties need not wait to receive a
"close_notify" alert before closing their read side of the "close_notify" alert before closing their read side of the
connection, though doing so would introduce the possibility of connection, though doing so would introduce the possibility of
truncation. truncation.
If the application protocol using TLS provides that any data may be If the application protocol using TLS provides that any data may be
carried over the underlying transport after the TLS connection is carried over the underlying transport after the TLS connection is
closed, the TLS implementation MUST receive a "close_notify" alert closed, the TLS implementation MUST receive a "close_notify" alert
before indicating end-of-data to the application-layer. No part of before indicating end-of-data to the application layer. No part of
this standard should be taken to dictate the manner in which a usage this standard should be taken to dictate the manner in which a usage
profile for TLS manages its data transport, including when profile for TLS manages its data transport, including when
connections are opened or closed. connections are opened or closed.
Note: It is assumed that closing the write side of a connection Note: It is assumed that closing the write side of a connection
reliably delivers pending data before destroying the transport. reliably delivers pending data before destroying the transport.
6.2. Error Alerts 6.2. Error Alerts
Error handling in the TLS Handshake Protocol is very simple. When an Error handling in TLS is very simple. When an error is detected, the
error is detected, the detecting party sends a message to its peer. detecting party sends a message to its peer. Upon transmission or
Upon transmission or receipt of a fatal alert message, both parties receipt of a fatal alert message, both parties MUST immediately close
MUST immediately close the connection. the connection.
Whenever an implementation encounters a fatal error condition, it Whenever an implementation encounters a fatal error condition, it
SHOULD send an appropriate fatal alert and MUST close the connection SHOULD send an appropriate fatal alert and MUST close the connection
without sending or receiving any additional data. In the rest of without sending or receiving any additional data. In the rest of
this specification, when the phrases "terminate the connection" and this specification, when the phrases "terminate the connection" and
"abort the handshake" are used without a specific alert it means that "abort the handshake" are used without a specific alert it means that
the implementation SHOULD send the alert indicated by the the implementation SHOULD send the alert indicated by the
descriptions below. The phrases "terminate the connection with a X descriptions below. The phrases "terminate the connection with an X
alert" and "abort the handshake with a X alert" mean that the alert" and "abort the handshake with an X alert" mean that the
implementation MUST send alert X if it sends any alert. All alerts implementation MUST send alert X if it sends any alert. All alerts
defined in this section below, as well as all unknown alerts, are defined below in this section, as well as all unknown alerts, are
universally considered fatal as of TLS 1.3 (see Section 6). The universally considered fatal as of TLS 1.3 (see Section 6). The
implementation SHOULD provide a way to facilitate logging the sending implementation SHOULD provide a way to facilitate logging the sending
and receiving of alerts. and receiving of alerts.
The following error alerts are defined: The following error alerts are defined:
unexpected_message An inappropriate message (e.g., the wrong unexpected_message: An inappropriate message (e.g., the wrong
handshake message, premature application data, etc.) was received. handshake message, premature Application Data, etc.) was received.
This alert should never be observed in communication between This alert should never be observed in communication between
proper implementations. proper implementations.
bad_record_mac This alert is returned if a record is received which bad_record_mac: This alert is returned if a record is received which
cannot be deprotected. Because AEAD algorithms combine decryption cannot be deprotected. Because AEAD algorithms combine decryption
and verification, and also to avoid side channel attacks, this and verification, and also to avoid side-channel attacks, this
alert is used for all deprotection failures. This alert should alert is used for all deprotection failures. This alert should
never be observed in communication between proper implementations, never be observed in communication between proper implementations,
except when messages were corrupted in the network. except when messages were corrupted in the network.
record_overflow A TLSCiphertext record was received that had a record_overflow: A TLSCiphertext record was received that had a
length more than 2^14 + 256 bytes, or a record decrypted to a length more than 2^14 + 256 bytes, or a record decrypted to a
TLSPlaintext record with more than 2^14 bytes (or some other TLSPlaintext record with more than 2^14 bytes (or some other
negotiated limit). This alert should never be observed in negotiated limit). This alert should never be observed in
communication between proper implementations, except when messages communication between proper implementations, except when messages
were corrupted in the network. were corrupted in the network.
handshake_failure Receipt of a "handshake_failure" alert message handshake_failure: Receipt of a "handshake_failure" alert message
indicates that the sender was unable to negotiate an acceptable indicates that the sender was unable to negotiate an acceptable
set of security parameters given the options available. set of security parameters given the options available.
bad_certificate A certificate was corrupt, contained signatures that bad_certificate: A certificate was corrupt, contained signatures
did not verify correctly, etc. that did not verify correctly, etc.
unsupported_certificate A certificate was of an unsupported type. unsupported_certificate: A certificate was of an unsupported type.
certificate_revoked A certificate was revoked by its signer. certificate_revoked: A certificate was revoked by its signer.
certificate_expired A certificate has expired or is not currently certificate_expired: A certificate has expired or is not currently
valid. valid.
certificate_unknown Some other (unspecified) issue arose in certificate_unknown: Some other (unspecified) issue arose in
processing the certificate, rendering it unacceptable. processing the certificate, rendering it unacceptable.
illegal_parameter A field in the handshake was incorrect or illegal_parameter: A field in the handshake was incorrect or
inconsistent with other fields. This alert is used for errors inconsistent with other fields. This alert is used for errors
which conform to the formal protocol syntax but are otherwise which conform to the formal protocol syntax but are otherwise
incorrect. incorrect.
unknown_ca A valid certificate chain or partial chain was received, unknown_ca: A valid certificate chain or partial chain was received,
but the certificate was not accepted because the CA certificate but the certificate was not accepted because the CA certificate
could not be located or could not be matched with a known trust could not be located or could not be matched with a known trust
anchor. anchor.
access_denied A valid certificate or PSK was received, but when access_denied: A valid certificate or PSK was received, but when
access control was applied, the sender decided not to proceed with access control was applied, the sender decided not to proceed with
negotiation. negotiation.
decode_error A message could not be decoded because some field was decode_error: A message could not be decoded because some field was
out of the specified range or the length of the message was out of the specified range or the length of the message was
incorrect. This alert is used for errors where the message does incorrect. This alert is used for errors where the message does
not conform to the formal protocol syntax. This alert should not conform to the formal protocol syntax. This alert should
never be observed in communication between proper implementations, never be observed in communication between proper implementations,
except when messages were corrupted in the network. except when messages were corrupted in the network.
decrypt_error A handshake (not record-layer) cryptographic operation decrypt_error: A handshake (not record layer) cryptographic
failed, including being unable to correctly verify a signature or operation failed, including being unable to correctly verify a
validate a Finished message or a PSK binder. signature or validate a Finished message or a PSK binder.
protocol_version The protocol version the peer has attempted to protocol_version: The protocol version the peer has attempted to
negotiate is recognized but not supported. (see Appendix D) negotiate is recognized but not supported (see Appendix D).
insufficient_security Returned instead of "handshake_failure" when a insufficient_security: Returned instead of "handshake_failure" when
negotiation has failed specifically because the server requires a negotiation has failed specifically because the server requires
parameters more secure than those supported by the client. parameters more secure than those supported by the client.
internal_error An internal error unrelated to the peer or the internal_error: An internal error unrelated to the peer or the
correctness of the protocol (such as a memory allocation failure) correctness of the protocol (such as a memory allocation failure)
makes it impossible to continue. makes it impossible to continue.
inappropriate_fallback Sent by a server in response to an invalid inappropriate_fallback: Sent by a server in response to an invalid
connection retry attempt from a client (see [RFC7507]). connection retry attempt from a client (see [RFC7507]).
missing_extension Sent by endpoints that receive a handshake message missing_extension: Sent by endpoints that receive a handshake
not containing an extension that is mandatory to send for the message not containing an extension that is mandatory to send for
offered TLS version or other negotiated parameters. the offered TLS version or other negotiated parameters.
unsupported_extension Sent by endpoints receiving any handshake unsupported_extension: Sent by endpoints receiving any handshake
message containing an extension known to be prohibited for message containing an extension known to be prohibited for
inclusion in the given handshake message, or including any inclusion in the given handshake message, or including any
extensions in a ServerHello or Certificate not first offered in extensions in a ServerHello or Certificate not first offered in
the corresponding ClientHello. the corresponding ClientHello or CertificateRequest.
unrecognized_name Sent by servers when no server exists identified unrecognized_name: Sent by servers when no server exists identified
by the name provided by the client via the "server_name" extension by the name provided by the client via the "server_name" extension
(see [RFC6066]). (see [RFC6066]).
bad_certificate_status_response Sent by clients when an invalid or bad_certificate_status_response: Sent by clients when an invalid or
unacceptable OCSP response is provided by the server via the unacceptable OCSP response is provided by the server via the
"status_request" extension (see [RFC6066]). "status_request" extension (see [RFC6066]).
unknown_psk_identity Sent by servers when PSK key establishment is unknown_psk_identity: Sent by servers when PSK key establishment is
desired but no acceptable PSK identity is provided by the client. desired but no acceptable PSK identity is provided by the client.
Sending this alert is OPTIONAL; servers MAY instead choose to send Sending this alert is OPTIONAL; servers MAY instead choose to send
a "decrypt_error" alert to merely indicate an invalid PSK a "decrypt_error" alert to merely indicate an invalid PSK
identity. identity.
certificate_required Sent by servers when a client certificate is certificate_required: Sent by servers when a client certificate is
desired but none was provided by the client. desired but none was provided by the client.
no_application_protocol Sent by servers when a client no_application_protocol: Sent by servers when a client
"application_layer_protocol_negotiation" extension advertises only "application_layer_protocol_negotiation" extension advertises only
protocols that the server does not support (see [RFC7301]). protocols that the server does not support (see [RFC7301]).
New Alert values are assigned by IANA as described in Section 11. New Alert values are assigned by IANA as described in Section 11.
7. Cryptographic Computations 7. Cryptographic Computations
The TLS handshake establishes one or more input secrets which are The TLS handshake establishes one or more input secrets which are
combined to create the actual working keying material, as detailed combined to create the actual working keying material, as detailed
below. The key derivation process incorporates both the input below. The key derivation process incorporates both the input
secrets and the handshake transcript. Note that because the secrets and the handshake transcript. Note that because the
handshake transcript includes the random values from the Hello handshake transcript includes the random values from the Hello
messages, any given handshake will have different traffic secrets, messages, any given handshake will have different traffic secrets,
even if the same input secrets are used, as is the case when the same even if the same input secrets are used, as is the case when the same
PSK is used for multiple connections. PSK is used for multiple connections.
7.1. Key Schedule 7.1. Key Schedule
The key derivation process makes use of the HKDF-Extract and HKDF- The key derivation process makes use of the HKDF-Extract and
Expand functions as defined for HKDF [RFC5869], as well as the HKDF-Expand functions as defined for HKDF [RFC5869], as well as the
functions defined below: functions defined below:
HKDF-Expand-Label(Secret, Label, Context, Length) = HKDF-Expand-Label(Secret, Label, Context, Length) =
HKDF-Expand(Secret, HkdfLabel, Length) HKDF-Expand(Secret, HkdfLabel, Length)
Where HkdfLabel is specified as: Where HkdfLabel is specified as:
struct { struct {
uint16 length = Length; uint16 length = Length;
opaque label<7..255> = "tls13 " + Label; opaque label<7..255> = "tls13 " + Label;
skipping to change at page 94, line 26 skipping to change at page 91, line 32
Derive-Secret(Secret, Label, Messages) = Derive-Secret(Secret, Label, Messages) =
HKDF-Expand-Label(Secret, Label, HKDF-Expand-Label(Secret, Label,
Transcript-Hash(Messages), Hash.length) Transcript-Hash(Messages), Hash.length)
The Hash function used by Transcript-Hash and HKDF is the cipher The Hash function used by Transcript-Hash and HKDF is the cipher
suite hash algorithm. Hash.length is its output length in bytes. suite hash algorithm. Hash.length is its output length in bytes.
Messages is the concatenation of the indicated handshake messages, Messages is the concatenation of the indicated handshake messages,
including the handshake message type and length fields, but not including the handshake message type and length fields, but not
including record layer headers. Note that in some cases a zero- including record layer headers. Note that in some cases a zero-
length Context (indicated by "") is passed to HKDF-Expand-Label. The length Context (indicated by "") is passed to HKDF-Expand-Label. The
Labels specified in this document are all ASCII strings, and do not labels specified in this document are all ASCII strings and do not
include a trailing NUL byte. include a trailing NUL byte.
Note: with common hash functions, any label longer than 12 characters Note: With common hash functions, any label longer than 12 characters
requires an additional iteration of the hash function to compute. requires an additional iteration of the hash function to compute.
The labels in this specification have all been chosen to fit within The labels in this specification have all been chosen to fit within
this limit. this limit.
Keys are derived from two input secrets using the HKDF-Extract and Keys are derived from two input secrets using the HKDF-Extract and
Derive-Secret functions. The general pattern for adding a new secret Derive-Secret functions. The general pattern for adding a new secret
is to use HKDF-Extract with the salt being the current secret state is to use HKDF-Extract with the Salt being the current secret state
and the IKM being the new secret to be added. In this version of TLS and the Input Keying Material (IKM) being the new secret to be added.
1.3, the two input secrets are: In this version of TLS 1.3, the two input secrets are:
- PSK (a pre-shared key established externally or derived from the - PSK (a pre-shared key established externally or derived from the
resumption_master_secret value from a previous connection) resumption_master_secret value from a previous connection)
- (EC)DHE shared secret (Section 7.4) - (EC)DHE shared secret (Section 7.4)
This produces a full key derivation schedule shown in the diagram This produces a full key derivation schedule shown in the diagram
below. In this diagram, the following formatting conventions apply: below. In this diagram, the following formatting conventions apply:
- HKDF-Extract is drawn as taking the Salt argument from the top and - HKDF-Extract is drawn as taking the Salt argument from the top and
the IKM argument from the left, with its output to the bottom and the IKM argument from the left, with its output to the bottom and
the name of the output on the right. the name of the output on the right.
- Derive-Secret's Secret argument is indicated by the incoming - Derive-Secret's Secret argument is indicated by the incoming
arrow. For instance, the Early Secret is the Secret for arrow. For instance, the Early Secret is the Secret for
generating the client_early_traffic_secret. generating the client_early_traffic_secret.
- "0" indicates a string of Hash-lengths bytes set to 0. - "0" indicates a string of Hash.length bytes set to zero.
0 0
| |
v v
PSK -> HKDF-Extract = Early Secret PSK -> HKDF-Extract = Early Secret
| |
+-----> Derive-Secret(., +-----> Derive-Secret(., "ext binder" | "res binder", "")
| "ext binder" | | = binder_key
| "res binder", |
| "") +-----> Derive-Secret(., "c e traffic", ClientHello)
| = binder_key | = client_early_traffic_secret
| |
+-----> Derive-Secret(., "c e traffic", +-----> Derive-Secret(., "e exp master", ClientHello)
| ClientHello) | = early_exporter_master_secret
| = client_early_traffic_secret v
| Derive-Secret(., "derived", "")
+-----> Derive-Secret(., "e exp master", |
| ClientHello) v
| = early_exporter_master_secret (EC)DHE -> HKDF-Extract = Handshake Secret
v |
Derive-Secret(., "derived", "") +-----> Derive-Secret(., "c hs traffic",
| | ClientHello...ServerHello)
v | = client_handshake_traffic_secret
(EC)DHE -> HKDF-Extract = Handshake Secret |
| +-----> Derive-Secret(., "s hs traffic",
+-----> Derive-Secret(., "c hs traffic", | ClientHello...ServerHello)
| ClientHello...ServerHello) | = server_handshake_traffic_secret
| = client_handshake_traffic_secret v
| Derive-Secret(., "derived", "")
+-----> Derive-Secret(., "s hs traffic", |
| ClientHello...ServerHello) v
| = server_handshake_traffic_secret 0 -> HKDF-Extract = Master Secret
v |
Derive-Secret(., "derived", "") +-----> Derive-Secret(., "c ap traffic",
| | ClientHello...server Finished)
v | = client_application_traffic_secret_0
0 -> HKDF-Extract = Master Secret |
| +-----> Derive-Secret(., "s ap traffic",
+-----> Derive-Secret(., "c ap traffic", | ClientHello...server Finished)
| ClientHello...server Finished) | = server_application_traffic_secret_0
| = client_application_traffic_secret_0 |
| +-----> Derive-Secret(., "exp master",
+-----> Derive-Secret(., "s ap traffic", | ClientHello...server Finished)
| ClientHello...server Finished) | = exporter_master_secret
| = server_application_traffic_secret_0 |
| +-----> Derive-Secret(., "res master",
+-----> Derive-Secret(., "exp master", ClientHello...client Finished)
| ClientHello...server Finished) = resumption_master_secret
| = exporter_master_secret
|
+-----> Derive-Secret(., "res master",
ClientHello...client Finished)
= resumption_master_secret
The general pattern here is that the secrets shown down the left side The general pattern here is that the secrets shown down the left side
of the diagram are just raw entropy without context, whereas the of the diagram are just raw entropy without context, whereas the
secrets down the right side include handshake context and therefore secrets down the right side include Handshake Context and therefore
can be used to derive working keys without additional context. Note can be used to derive working keys without additional context. Note
that the different calls to Derive-Secret may take different Messages that the different calls to Derive-Secret may take different Messages
arguments, even with the same secret. In a 0-RTT exchange, Derive- arguments, even with the same secret. In a 0-RTT exchange,
Secret is called with four distinct transcripts; in a 1-RTT-only Derive-Secret is called with four distinct transcripts; in a
exchange with three distinct transcripts. 1-RTT-only exchange, it is called with three distinct transcripts.
If a given secret is not available, then the 0-value consisting of a If a given secret is not available, then the 0-value consisting of a
string of Hash.length bytes set to zeros is used. Note that this string of Hash.length bytes set to zeros is used. Note that this
does not mean skipping rounds, so if PSK is not in use Early Secret does not mean skipping rounds, so if PSK is not in use, Early Secret
will still be HKDF-Extract(0, 0). For the computation of the will still be HKDF-Extract(0, 0). For the computation of the
binder_secret, the label is "ext binder" for external PSKs (those binder_key, the label is "ext binder" for external PSKs (those
provisioned outside of TLS) and "res binder" for resumption PSKs provisioned outside of TLS) and "res binder" for resumption PSKs
(those provisioned as the resumption master secret of a previous (those provisioned as the resumption master secret of a previous
handshake). The different labels prevent the substitution of one handshake). The different labels prevent the substitution of one
type of PSK for the other. type of PSK for the other.
There are multiple potential Early Secret values depending on which There are multiple potential Early Secret values, depending on which
PSK the server ultimately selects. The client will need to compute PSK the server ultimately selects. The client will need to compute
one for each potential PSK; if no PSK is selected, it will then need one for each potential PSK; if no PSK is selected, it will then need
to compute the early secret corresponding to the zero PSK. to compute the Early Secret corresponding to the zero PSK.
Once all the values which are to be derived from a given secret have Once all the values which are to be derived from a given secret have
been computed, that secret SHOULD be erased. been computed, that secret SHOULD be erased.
7.2. Updating Traffic Secrets 7.2. Updating Traffic Secrets
Once the handshake is complete, it is possible for either side to Once the handshake is complete, it is possible for either side to
update its sending traffic keys using the KeyUpdate handshake message update its sending traffic keys using the KeyUpdate handshake message
defined in Section 4.6.3. The next generation of traffic keys is defined in Section 4.6.3. The next generation of traffic keys is
computed by generating client_/server_application_traffic_secret_N+1 computed by generating client_/server_application_traffic_secret_N+1
from client_/server_application_traffic_secret_N as described in this from client_/server_application_traffic_secret_N as described in this
section then re-deriving the traffic keys as described in section and then re-deriving the traffic keys as described in
Section 7.3. Section 7.3.
The next-generation application_traffic_secret is computed as: The next-generation application_traffic_secret is computed as:
application_traffic_secret_N+1 = application_traffic_secret_N+1 =
HKDF-Expand-Label(application_traffic_secret_N, HKDF-Expand-Label(application_traffic_secret_N,
"traffic upd", "", Hash.length) "traffic upd", "", Hash.length)
Once client/server_application_traffic_secret_N+1 and its associated Once client_/server_application_traffic_secret_N+1 and its associated
traffic keys have been computed, implementations SHOULD delete traffic keys have been computed, implementations SHOULD delete
client_/server_application_traffic_secret_N and its associated client_/server_application_traffic_secret_N and its associated
traffic keys. traffic keys.
7.3. Traffic Key Calculation 7.3. Traffic Key Calculation
The traffic keying material is generated from the following input The traffic keying material is generated from the following input
values: values:
- A secret value - A secret value
- A purpose value indicating the specific value being generated - A purpose value indicating the specific value being generated
- The length of the key being generated - The length of the key being generated
The traffic keying material is generated from an input traffic secret The traffic keying material is generated from an input traffic secret
value using: value using:
[sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length)
[sender]_write_iv = HKDF-Expand-Label(Secret, "iv" , "", iv_length) [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)
[sender] denotes the sending side. The Secret value for each record [sender] denotes the sending side. The value of Secret for each
type is shown in the table below. record type is shown in the table below.
+-------------------+---------------------------------------+ +-------------------+---------------------------------------+
| Record Type | Secret | | Record Type | Secret |
+-------------------+---------------------------------------+ +-------------------+---------------------------------------+
| 0-RTT Application | client_early_traffic_secret | | 0-RTT Application | client_early_traffic_secret |
| | | | | |
| Handshake | [sender]_handshake_traffic_secret | | Handshake | [sender]_handshake_traffic_secret |
| | | | | |
| Application Data | [sender]_application_traffic_secret_N | | Application Data | [sender]_application_traffic_secret_N |
+-------------------+---------------------------------------+ +-------------------+---------------------------------------+
All the traffic keying material is recomputed whenever the underlying All the traffic keying material is recomputed whenever the underlying
Secret changes (e.g., when changing from the handshake to application Secret changes (e.g., when changing from the handshake to Application
data keys or upon a key update). Data keys or upon a key update).
7.4. (EC)DHE Shared Secret Calculation 7.4. (EC)DHE Shared Secret Calculation
7.4.1. Finite Field Diffie-Hellman 7.4.1. Finite Field Diffie-Hellman
For finite field groups, a conventional Diffie-Hellman [DH76] For finite field groups, a conventional Diffie-Hellman [DH76]
computation is performed. The negotiated key (Z) is converted to a computation is performed. The negotiated key (Z) is converted to a
byte string by encoding in big-endian and left padded with zeros up byte string by encoding in big-endian form and left-padded with zeros
to the size of the prime. This byte string is used as the shared up to the size of the prime. This byte string is used as the shared
secret in the key schedule as specified above. secret in the key schedule as specified above.
Note that this construction differs from previous versions of TLS Note that this construction differs from previous versions of TLS
which remove leading zeros. which removed leading zeros.
7.4.2. Elliptic Curve Diffie-Hellman 7.4.2. Elliptic Curve Diffie-Hellman
For secp256r1, secp384r1 and secp521r1, ECDH calculations (including For secp256r1, secp384r1, and secp521r1, ECDH calculations (including
parameter and key generation as well as the shared secret parameter and key generation as well as the shared secret
calculation) are performed according to [IEEE1363] using the ECKAS- calculation) are performed according to [IEEE1363] using the
DH1 scheme with the identity map as key derivation function (KDF), so ECKAS-DH1 scheme with the identity map as the key derivation function
that the shared secret is the x-coordinate of the ECDH shared secret (KDF), so that the shared secret is the x-coordinate of the ECDH
elliptic curve point represented as an octet string. Note that this shared secret elliptic curve point represented as an octet string.
octet string (Z in IEEE 1363 terminology) as output by FE2OSP, the Note that this octet string ("Z" in IEEE 1363 terminology) as output
Field Element to Octet String Conversion Primitive, has constant by FE2OSP (the Field Element to Octet String Conversion Primitive)
length for any given field; leading zeros found in this octet string has constant length for any given field; leading zeros found in this
MUST NOT be truncated. octet string MUST NOT be truncated.
(Note that this use of the identity KDF is a technicality. The (Note that this use of the identity KDF is a technicality. The
complete picture is that ECDH is employed with a non-trivial KDF complete picture is that ECDH is employed with a non-trivial KDF
because TLS does not directly use this secret for anything other than because TLS does not directly use this secret for anything other than
for computing other secrets.) for computing other secrets.)
ECDH functions are used as follows: For X25519 and X448, the ECDH calculations are as follows:
- The public key to put into the KeyShareEntry.key_exchange - The public key to put into the KeyShareEntry.key_exchange
structure is the result of applying the ECDH scalar multiplication structure is the result of applying the ECDH scalar multiplication
function to the secret key of appropriate length (into scalar function to the secret key of appropriate length (into scalar
input) and the standard public basepoint (into u-coordinate point input) and the standard public basepoint (into u-coordinate point
input). input).
- The ECDH shared secret is the result of applying the ECDH scalar - The ECDH shared secret is the result of applying the ECDH scalar
multiplication function to the secret key (into scalar input) and multiplication function to the secret key (into scalar input) and
the peer's public key (into u-coordinate point input). The output the peer's public key (into u-coordinate point input). The output
is used raw, with no processing. is used raw, with no processing.
For X25519 and X448, implementations SHOULD use the approach For these curves, implementations SHOULD use the approach specified
specified in [RFC7748] to calculate the Diffie-Hellman shared secret. in [RFC7748] to calculate the Diffie-Hellman shared secret.
Implementations MUST check whether the computed Diffie-Hellman shared Implementations MUST check whether the computed Diffie-Hellman shared
secret is the all-zero value and abort if so, as described in secret is the all-zero value and abort if so, as described in
Section 6 of [RFC7748]. If implementors use an alternative Section 6 of [RFC7748]. If implementors use an alternative
implementation of these elliptic curves, they SHOULD perform the implementation of these elliptic curves, they SHOULD perform the
additional checks specified in Section 7 of [RFC7748]. additional checks specified in Section 7 of [RFC7748].
7.5. Exporters 7.5. Exporters
[RFC5705] defines keying material exporters for TLS in terms of the [RFC5705] defines keying material exporters for TLS in terms of the
TLS pseudorandom function (PRF). This document replaces the PRF with TLS pseudorandom function (PRF). This document replaces the PRF with
skipping to change at page 99, line 30 skipping to change at page 97, line 27
Where Secret is either the early_exporter_master_secret or the Where Secret is either the early_exporter_master_secret or the
exporter_master_secret. Implementations MUST use the exporter_master_secret. Implementations MUST use the
exporter_master_secret unless explicitly specified by the exporter_master_secret unless explicitly specified by the
application. The early_exporter_master_secret is defined for use in application. The early_exporter_master_secret is defined for use in
settings where an exporter is needed for 0-RTT data. A separate settings where an exporter is needed for 0-RTT data. A separate
interface for the early exporter is RECOMMENDED; this avoids the interface for the early exporter is RECOMMENDED; this avoids the
exporter user accidentally using an early exporter when a regular one exporter user accidentally using an early exporter when a regular one
is desired or vice versa. is desired or vice versa.
If no context is provided, the context_value is zero-length. If no context is provided, the context_value is zero length.
Consequently, providing no context computes the same value as Consequently, providing no context computes the same value as
providing an empty context. This is a change from previous versions providing an empty context. This is a change from previous versions
of TLS where an empty context produced a different output to an of TLS where an empty context produced a different output than an
absent context. As of this document's publication, no allocated absent context. As of this document's publication, no allocated
exporter label is used both with and without a context. Future exporter label is used both with and without a context. Future
specifications MUST NOT define a use of exporters that permit both an specifications MUST NOT define a use of exporters that permit both an
empty context and no context with the same label. New uses of empty context and no context with the same label. New uses of
exporters SHOULD provide a context in all exporter computations, exporters SHOULD provide a context in all exporter computations,
though the value could be empty. though the value could be empty.
Requirements for the format of exporter labels are defined in section Requirements for the format of exporter labels are defined in
4 of [RFC5705]. Section 4 of [RFC5705].
8. 0-RTT and Anti-Replay 8. 0-RTT and Anti-Replay
As noted in Section 2.3 and Appendix E.5, TLS does not provide As noted in Section 2.3 and Appendix E.5, TLS does not provide
inherent replay protections for 0-RTT data. There are two potential inherent replay protections for 0-RTT data. There are two potential
threats to be concerned with: threats to be concerned with:
- Network attackers who mount a replay attack by simply duplicating - Network attackers who mount a replay attack by simply duplicating
a flight of 0-RTT data. a flight of 0-RTT data.
skipping to change at page 100, line 23 skipping to change at page 98, line 32
zone B, then an attacker can duplicate a ClientHello and early zone B, then an attacker can duplicate a ClientHello and early
data intended for A to both A and B. At A, the data will be data intended for A to both A and B. At A, the data will be
accepted in 0-RTT, but at B the server will reject 0-RTT data and accepted in 0-RTT, but at B the server will reject 0-RTT data and
instead force a full handshake. If the attacker blocks the instead force a full handshake. If the attacker blocks the
ServerHello from A, then the client will complete the handshake ServerHello from A, then the client will complete the handshake
with B and probably retry the request, leading to duplication on with B and probably retry the request, leading to duplication on
the server system as a whole. the server system as a whole.
The first class of attack can be prevented by sharing state to The first class of attack can be prevented by sharing state to
guarantee that the 0-RTT data is accepted at most once. Servers guarantee that the 0-RTT data is accepted at most once. Servers
SHOULD provide that level of replay safety, by implementing one of SHOULD provide that level of replay safety by implementing one of the
the methods described in this section or by equivalent means. It is methods described in this section or by equivalent means. It is
understood, however, that due to operational concerns not all understood, however, that due to operational concerns not all
deployments will maintain state at that level. Therefore, in normal deployments will maintain state at that level. Therefore, in normal
operation, clients will not know which, if any, of these mechanisms operation, clients will not know which, if any, of these mechanisms
servers actually implement and hence MUST only send early data which servers actually implement and hence MUST only send early data which
they deem safe to be replayed. they deem safe to be replayed.
In addition to the direct effects of replays, there is a class of In addition to the direct effects of replays, there is a class of
attacks where even operations normally considered idempotent could be attacks where even operations normally considered idempotent could be
exploited by a large number of replays (timing attacks, resource exploited by a large number of replays (timing attacks, resource
limit exhaustion and others described in Appendix E.5). Those can be limit exhaustion and others, as described in Appendix E.5). Those
mitigated by ensuring that every 0-RTT payload can be replayed only a can be mitigated by ensuring that every 0-RTT payload can be replayed
limited number of times. The server MUST ensure that any instance of only a limited number of times. The server MUST ensure that any
it (be it a machine, a thread or any other entity within the relevant instance of it (be it a machine, a thread, or any other entity within
serving infrastructure) would accept 0-RTT for the same 0-RTT the relevant serving infrastructure) would accept 0-RTT for the same
handshake at most once; this limits the number of replays to the 0-RTT handshake at most once; this limits the number of replays to
number of server instances in the deployment. Such a guarantee can the number of server instances in the deployment. Such a guarantee
be accomplished by locally recording data from recently-received can be accomplished by locally recording data from recently received
ClientHellos and rejecting repeats, or by any other method that ClientHellos and rejecting repeats, or by any other method that
provides the same or a stronger guarantee. The "at most once per provides the same or a stronger guarantee. The "at most once per
server instance" guarantee is a minimum requirement; servers SHOULD server instance" guarantee is a minimum requirement; servers SHOULD
limit 0-RTT replays further when feasible. limit 0-RTT replays further when feasible.
The second class of attack cannot be prevented at the TLS layer and The second class of attack cannot be prevented at the TLS layer and
MUST be dealt with by any application. Note that any application MUST be dealt with by any application. Note that any application
whose clients implement any kind of retry behavior already needs to whose clients implement any kind of retry behavior already needs to
implement some sort of anti-replay defense. implement some sort of anti-replay defense.
8.1. Single-Use Tickets 8.1. Single-Use Tickets
The simplest form of anti-replay defense is for the server to only The simplest form of anti-replay defense is for the server to only
allow each session ticket to be used once. For instance, the server allow each session ticket to be used once. For instance, the server
can maintain a database of all outstanding valid tickets; deleting can maintain a database of all outstanding valid tickets, deleting
each ticket from the database as it is used. If an unknown ticket is each ticket from the database as it is used. If an unknown ticket is
provided, the server would then fall back to a full handshake. provided, the server would then fall back to a full handshake.
If the tickets are not self-contained but rather are database keys, If the tickets are not self-contained but rather are database keys,
and the corresponding PSKs are deleted upon use, then connections and the corresponding PSKs are deleted upon use, then connections
established using PSKs enjoy forward secrecy. This improves security established using PSKs enjoy forward secrecy. This improves security
for all 0-RTT data and PSK usage when PSK is used without (EC)DHE. for all 0-RTT data and PSK usage when PSK is used without (EC)DHE.
Because this mechanism requires sharing the session database between Because this mechanism requires sharing the session database between
server nodes in environments with multiple distributed servers, it server nodes in environments with multiple distributed servers, it
skipping to change at page 101, line 38 skipping to change at page 99, line 46
An alternative form of anti-replay is to record a unique value An alternative form of anti-replay is to record a unique value
derived from the ClientHello (generally either the random value or derived from the ClientHello (generally either the random value or
the PSK binder) and reject duplicates. Recording all ClientHellos the PSK binder) and reject duplicates. Recording all ClientHellos
causes state to grow without bound, but a server can instead record causes state to grow without bound, but a server can instead record
ClientHellos within a given time window and use the ClientHellos within a given time window and use the
"obfuscated_ticket_age" to ensure that tickets aren't reused outside "obfuscated_ticket_age" to ensure that tickets aren't reused outside
that window. that window.
In order to implement this, when a ClientHello is received, the In order to implement this, when a ClientHello is received, the
server first verifies the PSK binder as described Section 4.2.11. It server first verifies the PSK binder as described in Section 4.2.11.
then computes the expected_arrival_time as described in the next It then computes the expected_arrival_time as described in the next
section and rejects 0-RTT if it is outside the recording window, section and rejects 0-RTT if it is outside the recording window,
falling back to the 1-RTT handshake. falling back to the 1-RTT handshake.
If the expected arrival time is in the window, then the server checks If the expected_arrival_time is in the window, then the server checks
to see if it has recorded a matching ClientHello. If one is found, to see if it has recorded a matching ClientHello. If one is found,
it either aborts the handshake with an "illegal_parameter" alert or it either aborts the handshake with an "illegal_parameter" alert or
accepts the PSK but reject 0-RTT. If no matching ClientHello is accepts the PSK but rejects 0-RTT. If no matching ClientHello is
found, then it accepts 0-RTT and then stores the ClientHello for as found, then it accepts 0-RTT and then stores the ClientHello for as
long as the expected_arrival_time is inside the window. Servers MAY long as the expected_arrival_time is inside the window. Servers MAY
also implement data stores with false positives, such as Bloom also implement data stores with false positives, such as Bloom
filters, in which case they MUST respond to apparent replay by filters, in which case they MUST respond to apparent replay by
rejecting 0-RTT but MUST NOT abort the handshake. rejecting 0-RTT but MUST NOT abort the handshake.
The server MUST derive the storage key only from validated sections The server MUST derive the storage key only from validated sections
of the ClientHello. If the ClientHello contains multiple PSK of the ClientHello. If the ClientHello contains multiple PSK
identities, then an attacker can create multiple ClientHellos with identities, then an attacker can create multiple ClientHellos with
different binder values for the less-preferred identity on the different binder values for the less-preferred identity on the
assumption that the server will not verify it, as recommended by assumption that the server will not verify it (as recommended by
Section 4.2.11. I.e., if the client sends PSKs A and B but the Section 4.2.11). I.e., if the client sends PSKs A and B but the
server prefers A, then the attacker can change the binder for B server prefers A, then the attacker can change the binder for B
without affecting the binder for A. If the binder for B is part of without affecting the binder for A. If the binder for B is part of
the storage key, then this ClientHello will not appear as a the storage key, then this ClientHello will not appear as a
duplicate, which will cause the ClientHello to be accepted, and may duplicate, which will cause the ClientHello to be accepted, and may
cause side effects such as replay cache pollution, although any 0-RTT cause side effects such as replay cache pollution, although any 0-RTT
data will not be decryptable because it will use different keys. If data will not be decryptable because it will use different keys. If
the validated binder or the ClientHello.random are used as the the validated binder or the ClientHello.random is used as the storage
storage key, then this attack is not possible. key, then this attack is not possible.
Because this mechanism does not require storing all outstanding Because this mechanism does not require storing all outstanding
tickets, it may be easier to implement in distributed systems with tickets, it may be easier to implement in distributed systems with
high rates of resumption and 0-RTT, at the cost of potentially weaker high rates of resumption and 0-RTT, at the cost of potentially weaker
anti-replay defense because of the difficulty of reliably storing and anti-replay defense because of the difficulty of reliably storing and
retrieving the received ClientHello messages. In many such systems, retrieving the received ClientHello messages. In many such systems,
it is impractical to have globally consistent storage of all the it is impractical to have globally consistent storage of all the
received ClientHellos. In this case, the best anti-replay protection received ClientHellos. In this case, the best anti-replay protection
is provided by having a single storage zone be authoritative for a is provided by having a single storage zone be authoritative for a
given ticket and refusing 0-RTT for that ticket in any other zone. given ticket and refusing 0-RTT for that ticket in any other zone.
skipping to change at page 102, line 40 skipping to change at page 101, line 5
zone will accept 0-RTT data. A weaker design is to implement zone will accept 0-RTT data. A weaker design is to implement
separate storage for each zone but allow 0-RTT in any zone. This separate storage for each zone but allow 0-RTT in any zone. This
approach limits the number of replays to once per zone. Application approach limits the number of replays to once per zone. Application
message duplication of course remains possible with either design. message duplication of course remains possible with either design.
When implementations are freshly started, they SHOULD reject 0-RTT as When implementations are freshly started, they SHOULD reject 0-RTT as
long as any portion of their recording window overlaps the startup long as any portion of their recording window overlaps the startup
time. Otherwise, they run the risk of accepting replays which were time. Otherwise, they run the risk of accepting replays which were
originally sent during that period. originally sent during that period.
Note: If the client's clock is running much faster than the server's Note: If the client's clock is running much faster than the server's,
then a ClientHello may be received that is outside the window in the then a ClientHello may be received that is outside the window in the
future, in which case it might be accepted for 1-RTT, causing a future, in which case it might be accepted for 1-RTT, causing a
client retry, and then acceptable later for 0-RTT. This is another client retry, and then acceptable later for 0-RTT. This is another
variant of the second form of attack described above. variant of the second form of attack described in Section 8.
8.3. Freshness Checks 8.3. Freshness Checks
Because the ClientHello indicates the time at which the client sent Because the ClientHello indicates the time at which the client sent
it, it is possible to efficiently determine whether a ClientHello was it, it is possible to efficiently determine whether a ClientHello was
likely sent reasonably recently and only accept 0-RTT for such a likely sent reasonably recently and only accept 0-RTT for such a
ClientHello, otherwise falling back to a 1-RTT handshake. This is ClientHello, otherwise falling back to a 1-RTT handshake. This is
necessary for the ClientHello storage mechanism described in necessary for the ClientHello storage mechanism described in
Section 8.2 because otherwise the server needs to store an unlimited Section 8.2 because otherwise the server needs to store an unlimited
number of ClientHellos and is a useful optimization for self- number of ClientHellos, and is a useful optimization for self-
contained single-use tickets because it allows efficient rejection of contained single-use tickets because it allows efficient rejection of
ClientHellos which cannot be used for 0-RTT. ClientHellos which cannot be used for 0-RTT.
In order to implement this mechanism, a server needs to store the In order to implement this mechanism, a server needs to store the
time that the server generated the session ticket, offset by an time that the server generated the session ticket, offset by an
estimate of the round trip time between client and server. I.e., estimate of the round-trip time between client and server. I.e.,
adjusted_creation_time = creation_time + estimated_RTT adjusted_creation_time = creation_time + estimated_RTT
This value can be encoded in the ticket, thus avoiding the need to This value can be encoded in the ticket, thus avoiding the need to
keep state for each outstanding ticket. The server can determine the keep state for each outstanding ticket. The server can determine the
client's view of the age of the ticket by subtracting the ticket's client's view of the age of the ticket by subtracting the ticket's
"ticket_age_add value" from the "obfuscated_ticket_age" parameter in "ticket_age_add" value from the "obfuscated_ticket_age" parameter in
the client's "pre_shared_key" extension. The server can determine the client's "pre_shared_key" extension. The server can determine
the "expected arrival time" of the ClientHello as: the expected_arrival_time of the ClientHello as:
expected_arrival_time = adjusted_creation_time + clients_ticket_age expected_arrival_time = adjusted_creation_time + clients_ticket_age
When a new ClientHello is received, the expected_arrival_time is then When a new ClientHello is received, the expected_arrival_time is then
compared against the current server wall clock time and if they compared against the current server wall clock time and if they
differ by more than a certain amount, 0-RTT is rejected, though the differ by more than a certain amount, 0-RTT is rejected, though the
1-RTT handshake can be allowed to complete. 1-RTT handshake can be allowed to complete.
There are several potential sources of error that might cause There are several potential sources of error that might cause
mismatches between the expected arrival time and the measured time. mismatches between the expected_arrival_time and the measured time.
Variations in client and server clock rates are likely to be minimal, Variations in client and server clock rates are likely to be minimal,
though potentially the absolute times may be off by large values. though potentially the absolute times may be off by large values.
Network propagation delays are the most likely causes of a mismatch Network propagation delays are the most likely causes of a mismatch
in legitimate values for elapsed time. Both the NewSessionTicket and in legitimate values for elapsed time. Both the NewSessionTicket and
ClientHello messages might be retransmitted and therefore delayed, ClientHello messages might be retransmitted and therefore delayed,
which might be hidden by TCP. For clients on the Internet, this which might be hidden by TCP. For clients on the Internet, this
implies windows on the order of ten seconds to account for errors in implies windows on the order of ten seconds to account for errors in
clocks and variations in measurements; other deployment scenarios may clocks and variations in measurements; other deployment scenarios may
have different needs. Clock skew distributions are not symmetric, so have different needs. Clock skew distributions are not symmetric, so
the optimal tradeoff may involve an asymmetric range of permissible the optimal tradeoff may involve an asymmetric range of permissible
mismatch values. mismatch values.
Note that freshness checking alone is not sufficient to prevent Note that freshness checking alone is not sufficient to prevent
replays because it does not detect them during the error window, replays because it does not detect them during the error window,
which, depending on bandwidth and system capacity could include which -- depending on bandwidth and system capacity -- could include
billions of replays in real-world settings. In addition, this billions of replays in real-world settings. In addition, this
freshness checking is only done at the time the ClientHello is freshness checking is only done at the time the ClientHello is
received, and not when later early application data records are received and not when subsequent early Application Data records are
received. After early data is accepted, records may continue to be received. After early data is accepted, records may continue to be
streamed to the server over a longer time period. streamed to the server over a longer time period.
9. Compliance Requirements 9. Compliance Requirements
9.1. Mandatory-to-Implement Cipher Suites 9.1. Mandatory-to-Implement Cipher Suites
In the absence of an application profile standard specifying In the absence of an application profile standard specifying
otherwise, a TLS-compliant application MUST implement the otherwise:
TLS_AES_128_GCM_SHA256 [GCM] cipher suite and SHOULD implement the
TLS_AES_256_GCM_SHA384 [GCM] and TLS_CHACHA20_POLY1305_SHA256 A TLS-compliant application MUST implement the TLS_AES_128_GCM_SHA256
[RFC7539] cipher suites. (see Appendix B.4) [GCM] cipher suite and SHOULD implement the TLS_AES_256_GCM_SHA384
[GCM] and TLS_CHACHA20_POLY1305_SHA256 [RFC8439] cipher suites (see
Appendix B.4).
A TLS-compliant application MUST support digital signatures with A TLS-compliant application MUST support digital signatures with
rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for rsa_pkcs1_sha256 (for certificates), rsa_pss_rsae_sha256 (for
CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A CertificateVerify and certificates), and ecdsa_secp256r1_sha256. A
TLS-compliant application MUST support key exchange with secp256r1 TLS-compliant application MUST support key exchange with secp256r1
(NIST P-256) and SHOULD support key exchange with X25519 [RFC7748]. (NIST P-256) and SHOULD support key exchange with X25519 [RFC7748].
9.2. Mandatory-to-Implement Extensions 9.2. Mandatory-to-Implement Extensions
In the absence of an application profile standard specifying In the absence of an application profile standard specifying
skipping to change at page 104, line 45 skipping to change at page 103, line 29
- Negotiated Groups ("supported_groups"; Section 4.2.7) - Negotiated Groups ("supported_groups"; Section 4.2.7)
- Key Share ("key_share"; Section 4.2.8) - Key Share ("key_share"; Section 4.2.8)
- Server Name Indication ("server_name"; Section 3 of [RFC6066]) - Server Name Indication ("server_name"; Section 3 of [RFC6066])
All implementations MUST send and use these extensions when offering All implementations MUST send and use these extensions when offering
applicable features: applicable features:
- "supported_versions" is REQUIRED for all ClientHello, ServerHello - "supported_versions" is REQUIRED for all ClientHello, ServerHello,
and HelloRetryRequest messages. and HelloRetryRequest messages.
- "signature_algorithms" is REQUIRED for certificate authentication. - "signature_algorithms" is REQUIRED for certificate authentication.
- "supported_groups" is REQUIRED for ClientHello messages using DHE - "supported_groups" is REQUIRED for ClientHello messages using DHE
or ECDHE key exchange. or ECDHE key exchange.
- "key_share" is REQUIRED for DHE or ECDHE key exchange. - "key_share" is REQUIRED for DHE or ECDHE key exchange.
- "pre_shared_key" is REQUIRED for PSK key agreement. - "pre_shared_key" is REQUIRED for PSK key agreement.
skipping to change at page 105, line 28 skipping to change at page 104, line 22
extension. extension.
- If containing a "supported_groups" extension, it MUST also contain - If containing a "supported_groups" extension, it MUST also contain
a "key_share" extension, and vice versa. An empty a "key_share" extension, and vice versa. An empty
KeyShare.client_shares vector is permitted. KeyShare.client_shares vector is permitted.
Servers receiving a ClientHello which does not conform to these Servers receiving a ClientHello which does not conform to these
requirements MUST abort the handshake with a "missing_extension" requirements MUST abort the handshake with a "missing_extension"
alert. alert.
Additionally, all implementations MUST support use of the Additionally, all implementations MUST support the use of the
"server_name" extension with applications capable of using it. "server_name" extension with applications capable of using it.
Servers MAY require clients to send a valid "server_name" extension. Servers MAY require clients to send a valid "server_name" extension.
Servers requiring this extension SHOULD respond to a ClientHello Servers requiring this extension SHOULD respond to a ClientHello
lacking a "server_name" extension by terminating the connection with lacking a "server_name" extension by terminating the connection with
a "missing_extension" alert. a "missing_extension" alert.
9.3. Protocol Invariants 9.3. Protocol Invariants
This section describes invariants that TLS endpoints and middleboxes This section describes invariants that TLS endpoints and middleboxes
MUST follow. It also applies to earlier versions of TLS. MUST follow. It also applies to earlier versions of TLS.
skipping to change at page 106, line 11 skipping to change at page 105, line 14
For this to work, implementations MUST correctly handle extensible For this to work, implementations MUST correctly handle extensible
fields: fields:
- A client sending a ClientHello MUST support all parameters - A client sending a ClientHello MUST support all parameters
advertised in it. Otherwise, the server may fail to interoperate advertised in it. Otherwise, the server may fail to interoperate
by selecting one of those parameters. by selecting one of those parameters.
- A server receiving a ClientHello MUST correctly ignore all - A server receiving a ClientHello MUST correctly ignore all
unrecognized cipher suites, extensions, and other parameters. unrecognized cipher suites, extensions, and other parameters.
Otherwise, it may fail to interoperate with newer clients. In TLS Otherwise, it may fail to interoperate with newer clients. In
1.3, a client receiving a CertificateRequest or NewSessionTicket TLS 1.3, a client receiving a CertificateRequest or
MUST also ignore all unrecognized extensions. NewSessionTicket MUST also ignore all unrecognized extensions.
- A middlebox which terminates a TLS connection MUST behave as a - A middlebox which terminates a TLS connection MUST behave as a
compliant TLS server (to the original client), including having a compliant TLS server (to the original client), including having a
certificate which the client is willing to accept, and as a certificate which the client is willing to accept, and also as a
compliant TLS client (to the original server), including verifying compliant TLS client (to the original server), including verifying
the original server's certificate. In particular, it MUST the original server's certificate. In particular, it MUST
generate its own ClientHello containing only parameters it generate its own ClientHello containing only parameters it
understands, and it MUST generate a fresh ServerHello random understands, and it MUST generate a fresh ServerHello random
value, rather than forwarding the endpoint's value. value, rather than forwarding the endpoint's value.
Note that TLS's protocol requirements and security analysis only Note that TLS's protocol requirements and security analysis only
apply to the two connections separately. Safely deploying a TLS apply to the two connections separately. Safely deploying a TLS
terminator requires additional security considerations which are terminator requires additional security considerations which are
beyond the scope of this document. beyond the scope of this document.
- An middlebox which forwards ClientHello parameters it does not - A middlebox which forwards ClientHello parameters it does not
understand MUST NOT process any messages beyond that ClientHello. understand MUST NOT process any messages beyond that ClientHello.
It MUST forward all subsequent traffic unmodified. Otherwise, it It MUST forward all subsequent traffic unmodified. Otherwise, it
may fail to interoperate with newer clients and servers. may fail to interoperate with newer clients and servers.
Forwarded ClientHellos may contain advertisements for features not Forwarded ClientHellos may contain advertisements for features not
supported by the middlebox, so the response may include future TLS supported by the middlebox, so the response may include future TLS
additions the middlebox does not recognize. These additions MAY additions the middlebox does not recognize. These additions MAY
change any message beyond the ClientHello arbitrarily. In change any message beyond the ClientHello arbitrarily. In
particular, the values sent in the ServerHello might change, the particular, the values sent in the ServerHello might change, the
ServerHello format might change, and the TLSCiphertext format ServerHello format might change, and the TLSCiphertext format
might change. might change.
The design of TLS 1.3 was constrained by widely-deployed non- The design of TLS 1.3 was constrained by widely deployed
compliant TLS middleboxes (see Appendix D.4), however it does not non-compliant TLS middleboxes (see Appendix D.4); however, it does
relax the invariants. Those middleboxes continue to be non- not relax the invariants. Those middleboxes continue to be
compliant. non-compliant.
10. Security Considerations 10. Security Considerations
Security issues are discussed throughout this memo, especially in Security issues are discussed throughout this memo, especially in
Appendix C, Appendix D, and Appendix E. Appendices C, D, and E.
11. IANA Considerations 11. IANA Considerations
This document uses several registries that were originally created in This document uses several registries that were originally created in
[RFC4346]. IANA [SHALL update/has updated] these to reference this [RFC4346] and updated in [RFC8447]. IANA has updated these to
document. The registries and their allocation policies are below: reference this document. The registries and their allocation
policies are below:
- TLS Cipher Suite Registry: values with the first byte in the range - TLS Cipher Suites registry: values with the first byte in the
0-254 (decimal) are assigned via Specification Required [RFC8126]. range 0-254 (decimal) are assigned via Specification Required
Values with the first byte 255 (decimal) are reserved for Private [RFC8126]. Values with the first byte 255 (decimal) are reserved
Use [RFC8126]. for Private Use [RFC8126].
IANA [SHALL add/has added] the cipher suites listed in IANA has added the cipher suites listed in Appendix B.4 to the
Appendix B.4 to the registry. The "Value" and "Description" registry. The "Value" and "Description" columns are taken from
columns are taken from the table. The "DTLS-OK" and "Recommended" the table. The "DTLS-OK" and "Recommended" columns are both
columns are both marked as "Yes" for each new cipher suite. marked as "Y" for each new cipher suite.
[[This assumes [I-D.ietf-tls-iana-registry-updates] has been
applied.]]
- TLS ContentType Registry: Future values are allocated via - TLS ContentType registry: Future values are allocated via
Standards Action [RFC8126]. Standards Action [RFC8126].
- TLS Alert Registry: Future values are allocated via Standards - TLS Alerts registry: Future values are allocated via Standards
Action [RFC8126]. IANA [SHALL update/has updated] this registry Action [RFC8126]. IANA has populated this registry with the
to include values for "missing_extension" and values from Appendix B.2. The "DTLS-OK" column is marked as "Y"
"certificate_required". The "DTLS-OK" column is marked as "Yes" for all such values. Values marked as "_RESERVED" have comments
for each new alert. describing their previous usage.
- TLS HandshakeType Registry: Future values are allocated via - TLS HandshakeType registry: Future values are allocated via
Standards Action [RFC8126]. IANA [SHALL update/has updated] this Standards Action [RFC8126]. IANA has updated this registry to
registry to rename item 4 from "NewSessionTicket" to rename item 4 from "NewSessionTicket" to "new_session_ticket" and
"new_session_ticket" and to add the populated this registry with the values from Appendix B.3. The
"hello_retry_request_RESERVED", "encrypted_extensions", "DTLS-OK" column is marked as "Y" for all such values. Values
"end_of_early_data", "key_update", and "message_hash" values. The marked "_RESERVED" have comments describing their previous or
"DTLS-OK" are marked as "Yes" for each of these additions. temporary usage.
This document also uses the TLS ExtensionType Registry originally This document also uses the TLS ExtensionType Values registry
created in [RFC4366]. IANA has updated it to reference this originally created in [RFC4366]. IANA has updated it to reference
document. Changes to the registry follow: this document. Changes to the registry follow:
- IANA [SHALL update/has updated] the registration policy as - IANA has updated the registration policy as follows:
follows:
Values with the first byte in the range 0-254 (decimal) are Values with the first byte in the range 0-254 (decimal) are
assigned via Specification Required [RFC8126]. Values with the assigned via Specification Required [RFC8126]. Values with the
first byte 255 (decimal) are reserved for Private Use [RFC8126]. first byte 255 (decimal) are reserved for Private Use [RFC8126].
- IANA [SHALL update/has updated] this registry to include the - IANA has updated this registry to include the "key_share",
"key_share", "pre_shared_key", "psk_key_exchange_modes", "pre_shared_key", "psk_key_exchange_modes", "early_data",
"early_data", "cookie", "supported_versions", "cookie", "supported_versions", "certificate_authorities",
"certificate_authorities", "oid_filters", "post_handshake_auth", "oid_filters", "post_handshake_auth", and
and "signature_algorithms_cert", extensions with the values "signature_algorithms_cert" extensions with the values defined in
defined in this document and the Recommended value of "Yes". this document and the "Recommended" value of "Y".
- IANA [SHALL update/has updated] this registry to include a "TLS - IANA has updated this registry to include a "TLS 1.3" column which
1.3" column which lists the messages in which the extension may lists the messages in which the extension may appear. This column
appear. This column [SHALL be/has been] initially populated from has been initially populated from the table in Section 4.2, with
the table in Section 4.2 with any extension not listed there any extension not listed there marked as "-" to indicate that it
marked as "-" to indicate that it is not used by TLS 1.3. is not used by TLS 1.3.
In addition, this document defines two new registries to be This document updates an entry in the TLS Certificate Types registry
originally created in [RFC6091] and updated in [RFC8447]. IANA has
updated the entry for value 1 to have the name "OpenPGP_RESERVED",
"Recommended" value "N", and comment "Used in TLS versions prior
to 1.3."
This document updates an entry in the TLS Certificate Status Types
registry originally created in [RFC6961]. IANA has updated the entry
for value 2 to have the name "ocsp_multi_RESERVED" and comment "Used
in TLS versions prior to 1.3".
This document updates two entries in the TLS Supported Groups
registry (created under a different name by [RFC4492]; now maintained
by [RFC8422]) and updated by [RFC7919] and [RFC8447]. The entries
for values 29 and 30 (x25519 and x448) have been updated to also
refer to this document.
In addition, this document defines two new registries that are
maintained by IANA: maintained by IANA:
- TLS SignatureScheme Registry: Values with the first byte in the - TLS SignatureScheme registry: Values with the first byte in the
range 0-253 (decimal) are assigned via Specification Required range 0-253 (decimal) are assigned via Specification Required
[RFC8126]. Values with the first byte 254 or 255 (decimal) are [RFC8126]. Values with the first byte 254 or 255 (decimal) are
reserved for Private Use [RFC8126]. Values with the first byte in reserved for Private Use [RFC8126]. Values with the first byte in
the range 0-6 or with the second byte in the range 0-3 that are the range 0-6 or with the second byte in the range 0-3 that are
not currently allocated are reserved for backwards compatibility. not currently allocated are reserved for backward compatibility.
This registry SHALL have a "Recommended" column. The registry This registry has a "Recommended" column. The registry has been
[shall be/ has been] initially populated with the values described initially populated with the values described in Section 4.2.3.
in Section 4.2.3. The following values SHALL be marked as The following values are marked as "Recommended":
"Recommended": ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384,
rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512, rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512,
rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512, and rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512, and
ed25519. ed25519. The "Recommended" column is assigned a value of "N"
unless explicitly requested, and adding a value with a
"Recommended" value of "Y" requires Standards Action [RFC8126].
IESG Approval is REQUIRED for a Y->N transition.
- TLS PskKeyExchangeMode Registry: Values in the range 0-253 - TLS PskKeyExchangeMode registry: Values in the range 0-253
(decimal) are assigned via Specification Required [RFC8126]. (decimal) are assigned via Specification Required [RFC8126].
Values with the first byte 254 or 255 (decimal) are reserved for The values 254 and 255 (decimal) are reserved for Private Use
Private Use [RFC8126]. This registry SHALL have a "Recommended" [RFC8126]. This registry has a "Recommended" column. The
column. The registry [shall be/ has been] initially populated registry has been initially populated with psk_ke (0) and
psk_ke (0) and psk_dhe_ke (1). Both SHALL be marked as psk_dhe_ke (1). Both are marked as "Recommended". The
"Recommended". "Recommended" column is assigned a value of "N" unless explicitly
requested, and adding a value with a "Recommended" value of "Y"
requires Standards Action [RFC8126]. IESG Approval is REQUIRED
for a Y->N transition.