RFC 2817

Upgrading to TLS Within HTTP/1.1 🦋

Okay bestie, this is RFC 2817 💖 It's a Standards Track doc from May 2000, written by R. Khare (4K Associates / UC Irvine) and S. Lawrence (Agranat Systems, Inc.). It updates RFC 2616 (the older HTTP/1.1 spec) 🌸 There's no Obsoletes line in the header, so it isn't replacing anything.

Status of this Memo ✨

This is an Internet standards track protocol for the Internet community, and the authors are asking for discussion and suggestions for improvements 💅 For the current standardization state and status, check the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌈

Copyright Notice 🎀

Copyright (C) The Internet Society (2000). All Rights Reserved.

Abstract 🧚

Okay so this memo explains how to use the Upgrade mechanism in HTTP/1.1 to start Transport Layer Security (TLS) over a TCP connection that already exists 🔥 The payoff is that unsecured and secured HTTP traffic can share the same well-known port. That's http: on 80 instead of https: on 443. It's giving efficiency 🫶

It also unlocks virtual hosting. One HTTP + TLS server can tell apart traffic meant for several hostnames sitting on a single IP address 👑

Since HTTP/1.1 [1] defines Upgrade as a hop-by-hop mechanism, this memo also documents the HTTP CONNECT method for setting up end-to-end tunnels across HTTP proxies 🦋 Last but not least, it creates new IANA registries for public HTTP status codes, plus public or private Upgrade product tokens 💜

This memo does not change how the https URI scheme is defined. That scheme already has its own namespace, so http://example.org/ and https://example.org/ are not equivalent. 🙈

Table of Contents 📚

1.  Motivation . . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
2.1 Requirements Terminology . . . . . . . . . . . . . . . . . . .  4
3.  Client Requested Upgrade to HTTP over TLS  . . . . . . . . . .  4
3.1 Optional Upgrade . . . . . . . . . . . . . . . . . . . . . . .  4
3.2 Mandatory Upgrade  . . . . . . . . . . . . . . . . . . . . . .  4
3.3 Server Acceptance of Upgrade Request . . . . . . . . . . . . .  4
4.  Server Requested Upgrade to HTTP over TLS  . . . . . . . . . .  5
4.1 Optional Advertisement . . . . . . . . . . . . . . . . . . . .  5
4.2 Mandatory Advertisement  . . . . . . . . . . . . . . . . . . .  5
5.  Upgrade across Proxies . . . . . . . . . . . . . . . . . . . .  6
5.1 Implications of Hop By Hop Upgrade . . . . . . . . . . . . . .  6
5.2 Requesting a Tunnel with CONNECT . . . . . . . . . . . . . . .  6
5.3 Establishing a Tunnel with CONNECT . . . . . . . . . . . . . .  7
6.  Rationale for the use of a 4xx (client error) Status Code  . .  7
7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  8
7.1 HTTP Status Code Registry  . . . . . . . . . . . . . . . . . .  8
7.2 HTTP Upgrade Token Registry  . . . . . . . . . . . . . . . . .  8
8.  Security Considerations  . . . . . . . . . . . . . . . . . . .  9
8.1 Implications for the https: URI Scheme . . . . . . . . . . . . 10
8.2 Security Considerations for CONNECT  . . . . . . . . . . . . . 10
    References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
    Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 11
A.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 12
    Full Copyright Statement . . . . . . . . . . . . . . . . . . . 13

1. Motivation 🌸

Historically, HTTP over SSL3 [3] was deployed in a way that set the combo apart from plain HTTP with its own URI scheme and its own TCP port number. The scheme http meant plain HTTP on port 80, and https meant HTTP over SSL on port 443 🎀 Other application protocols wanted the same split too, such as snews and ftps, and parallel well-known ports were requested for them (and in some cases granted) 🙃 The catch is that this effectively halves the number of available well-known ports. Yikes 💀

At the Washington DC IETF meeting in December 1997, the Applications Area Directors and the IESG reaffirmed that the practice of issuing parallel "secure" port numbers should be deprecated. The HTTP/1.1 Upgrade mechanism can apply Transport Layer Security [6] to an open HTTP connection ✨

In the nearly two years since, the concept behind this proposal has been broadly accepted, but there's been little interest in implementing alternatives to port 443 for generic Web browsing 🦋 Nothing in this memo changes how https: URIs are interpreted. However, new application protocols built on top of HTTP, like the Internet Printing Protocol [7], need exactly this kind of mechanism so they can move forward in the IETF standards process 💅

The Upgrade mechanism also fixes the "virtual hosting" problem. Instead of giving a single host multiple IP addresses, an HTTP/1.1 server uses the Host: header to work out which web service is meant. As HTTP/1.1 use has grown, more ISPs offer name-based virtual hosting, which delays IP address space exhaustion 👑

TLS (and SSL) have hit the same limitation earlier versions of HTTP had: the initial handshake doesn't say which hostname is intended and relies only on the IP address 😭 The idea here is to send a cleartext HTTP/1.1 Upgrade: preamble before the TLS handshake and choose the certificates based on the initial Host: header. That would let ISPs offer secure name-based virtual hosting too 🫶

2. Introduction 🧚‍♀️

Okay so TLS, a.k.a. SSL (Secure Sockets Layer), sets up a private end-to-end connection. It can optionally include strong mutual authentication and uses a variety of cryptosystems 🔐 First, a handshake phase uses three subprotocols to set up a record layer, authenticate the endpoints, set parameters, and report errors. After that, an ongoing layered record protocol handles encryption, compression, and reassembly for the rest of the connection. That part is meant to be completely transparent ✨ For example, there's no dependency between TLS's record markers and/or certificates and HTTP/1.1's chunked encoding or authentication. Separate lanes, no drama 💖

Either the client or the server can use the HTTP/1.1 [1] Upgrade mechanism (Section 14.42) to say a TLS-secured connection is desired or necessary 🌈 This memo defines the TLS/1.0 Upgrade token and a new HTTP Status Code, 426 Upgrade Required 💜

Sections 3 and 4 describe how a directly connected client and server operate. Intermediate proxies have to set up an end-to-end tunnel before applying those operations, as explained in Section 5 🦋

2.1 Requirements Terminology 💅

Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and "MAY" that appear in this document are to be interpreted as described in RFC 2119 [11] 🎀

3. Client Requested Upgrade to HTTP over TLS 🫶

When the client sends an HTTP/1.1 request with an Upgrade header field containing the token TLS/1.0, it's asking the server to finish the current HTTP/1.1 request after switching to TLS/1.0 🔥

3.1 Optional Upgrade 🌸

A client MAY offer to switch to secured operation during any clear HTTP request when an unsecured response would be acceptable:

    GET http://example.bank.com/acct_stat.html?749394889300 HTTP/1.1
    Host: example.bank.com
    Upgrade: TLS/1.0
    Connection: Upgrade

In this case, the server MAY respond to the clear HTTP operation normally, or switch to secured operation (as detailed in the next section) ✨

Note that HTTP/1.1 [1] specifies "the upgrade keyword MUST be supplied within a Connection header field (section 14.10) whenever Upgrade is present in an HTTP/1.1 message". 🙌

3.2 Mandatory Upgrade 💜

If an unsecured response would be unacceptable, a client MUST send an OPTIONS request first to complete the switch to TLS/1.0 (if possible) 🚨

    OPTIONS * HTTP/1.1
    Host: example.bank.com
    Upgrade: TLS/1.0
    Connection: Upgrade

3.3 Server Acceptance of Upgrade Request 🦋

As specified in HTTP/1.1 [1], if the server is prepared to start the TLS handshake, it MUST send the intermediate "101 Switching Protocol" and MUST include an Upgrade response header specifying the tokens of the protocol stack it's switching to:

    HTTP/1.1 101 Switching Protocols
    Upgrade: TLS/1.0, HTTP/1.1
    Connection: Upgrade

Note that the protocol tokens listed in the Upgrade header of a 101 Switching Protocols response specify an ordered 'bottom-up' stack. Stack goes bottom to top, babe 🥞

As specified in HTTP/1.1 [1], Section 10.1.2: "The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response". 💅

Once the TLS handshake completes successfully, the server MUST continue with the response to the original request. Any TLS handshake failure MUST lead to disconnection, per the TLS error alert specification. Not optional, not negotiable 😤

4. Server Requested Upgrade to HTTP over TLS 👑

The Upgrade response header field advertises the possible protocol upgrades a server MAY accept. Combined with the "426 Upgrade Required" status code, a server can advertise the exact protocol upgrade(s) that a client MUST accept to complete the request 🔥

4.1 Optional Advertisement 🌈

As specified in HTTP/1.1 [1], the server MAY include an Upgrade header in any response other than 101 or 426 to show it's willing to switch to any (combination) of the protocols listed ✨

4.2 Mandatory Advertisement 💖

A server MAY indicate that a client request cannot be completed without TLS by using the "426 Upgrade Required" status code. That response MUST include an Upgrade header field specifying the token of the required TLS version 🚫

    HTTP/1.1 426 Upgrade Required
    Upgrade: TLS/1.0, HTTP/1.1
    Connection: Upgrade

The server SHOULD include a message body in the 426 response that explains in human-readable form the reason for the error and describes any alternative courses that might be available to the user 🫶

Note that even if a client is willing to use TLS, it must use the operations in Section 3 to proceed. The TLS handshake cannot begin immediately after the 426 response. Read the room, bestie 🙈

5. Upgrade across Proxies 🧚

As a hop-by-hop header, Upgrade is negotiated between each pair of HTTP counterparties. If a User Agent sends a request with an Upgrade header to a proxy, it's requesting a change to the protocol between itself and the proxy, not an end-to-end change 🦋

Since TLS in particular needs end-to-end connectivity to provide authentication and prevent man-in-the-middle attacks, this memo specifies the CONNECT method to establish a tunnel across proxies 🔐

Once a tunnel is established, any of the operations in Section 3 can be used to establish a TLS connection 🌸

5.1 Implications of Hop By Hop Upgrade 🧩

okay so if an origin server gets an Upgrade header from a proxy and replies with a 101 Switching Protocols response, it's only switching protocols on the connection between the proxy and itself 🦋. Similarly, a proxy might send a 101 back to its client to change the protocol on that connection, totally separate from whatever it's speaking to the origin server. main character multitasking 💅

these scenarios make diagnosing a 426 response kinda messy 🙈 Upgrade is a hop-by-hop header, so a proxy that doesn't recognize 426 might strip the Upgrade header off, and now the client has no clue which protocol switch it needs. ngl that's so annoying 😭. So if a client gets a 426 without an accompanying Upgrade header, it's gonna need to request an end to end tunnel connection (see Section 5.2) and then repeat the request to get the required upgrade info 🫶.

this hop-by-hop version of Upgrade was a deliberate choice!! it lets things get rolled out incrementally on either side of proxies, and lets cascaded proxies use optimized protocols between each other without the parties who aren't part of the change needing to know. iconic design 👑

5.2 Requesting a Tunnel with CONNECT 🚇

A CONNECT method requests that a proxy establish a tunnel connection on its behalf. The Request-URI portion of the Request-Line is always an 'authority' as defined by URI Generic Syntax [2], which is to say the host name and port number destination of the requested connection separated by a colon:

CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80

Other HTTP mechanisms can be used normally with the CONNECT method -- except end-to-end protocol Upgrade requests, of course, since the tunnel has to be established first 🙃.

For example, proxy authentication might be used to establish the authority to create a tunnel 🔑:

CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80
Proxy-Authorization: basic aGVsbG86d29ybGQ=

Like any other pipelined HTTP/1.1 request, data to be tunneled may be sent immediately after the blank line. The usual caveats also apply: data may be discarded if the eventual response is negative, and the connection may be reset with no response if more than one TCP segment is outstanding 💀.

5.3 Establishing a Tunnel with CONNECT 🔐

Any successful (2xx) response to a CONNECT request means the proxy has established a connection to the requested host and port, and has switched to tunneling the current connection to that server connection ✨.

It may be the case that the proxy itself can only reach the requested origin server through another proxy. In this case, the first proxy SHOULD make a CONNECT request of that next proxy, requesting a tunnel to the authority. A proxy MUST NOT respond with any 2xx status code unless it has either a direct or tunnel connection established to the authority. bestie, that's a hard rule 🚫.

An origin server which receives a CONNECT request for itself MAY respond with a 2xx status code to indicate that a connection is established 💜.

If at any point either one of the peers gets disconnected, any outstanding data that came from that peer will be passed to the other one, and after that the other connection will also be terminated by the proxy. If there is outstanding data to that peer that hasn't been delivered, that data will be discarded 🥀.

6. Rationale for the use of a 4xx (client error) Status Code 🍓

Reliable, interoperable negotiation of Upgrade features needs an unambiguous failure signal, and that's exactly what the 426 Upgrade Required status code gives us. It lets a server definitively state the precise protocol extensions a given resource must be served with 🎯.

It might at first appear that the response should have been some form of redirection (a 3xx code), kind of like the old-style redirect to an https: URI. But user agents that don't understand Upgrade: already rule that out 🙅‍♀️.

Imagine a 3xx code had been assigned for "Upgrade Required." A user agent that didn't recognize it would treat it as 300. It would then properly look for a "Location" header in the response and try to repeat the request at the URL in that header field. Since it didn't know to Upgrade to incorporate the TLS layer, it would at best fail again at the new URL 😩.

7. IANA Considerations 📋

IANA shall create registries for two name spaces, as described in BCP 26 [10]:

• HTTP Status Codes
• HTTP Upgrade Tokens

7.1 HTTP Status Code Registry 🔢

The HTTP Status Code Registry defines the name space for the Status-Code token in the Status line of an HTTP response. The initial values for this name space are those specified by:

1. Draft Standard for HTTP/1.1 [1]
2. Web Distributed Authoring and Versioning [4] [defines 420-424]
3. WebDAV Advanced Collections [5] (Work in Progress) [defines 425]
4. Section 6 [defines 426]

Values added to this name space SHOULD be subject to review in the form of a standards track document within the IETF Applications Area. Any such document SHOULD be traceable through statuses of either 'Obsoletes' or 'Updates' to the Draft Standard for HTTP/1.1 [1] 🧾.

7.2 HTTP Upgrade Token Registry 🏷️

The HTTP Upgrade Token Registry defines the name space for product tokens used to identify protocols in the Upgrade HTTP header field. Each registered token should be associated with one or a set of specifications, and with contact information 📇.

The Draft Standard for HTTP/1.1 [1] says these tokens follow the production for 'product':

product         = token ["/" product-version]
product-version = token

Registrations should be allowed on a First Come First Served basis, as described in BCP 26 [10]. These specifications don't need to be IETF documents or go through IESG review, but they should follow these rules:

1. A token, once registered, stays registered forever ♾️.
2. The registration MUST name a responsible party for the registration.
3. The registration MUST name a point of contact.
4. The registration MAY name the documentation required for the token.
5. The responsible party MAY change the registration at any time. The IANA will keep a record of all such changes, and make them available upon request.
6. The responsible party for the first registration of a "product" token MUST approve later registrations of a "version" token together with that "product" token before they can be registered.
7. If absolutely required, the IESG MAY reassign the responsibility for a token. This will normally only be used when a responsible party cannot be contacted.

This specification defines the protocol token "TLS/1.0" as the identifier for the protocol specified by The TLS Protocol [6] 🔒.

It is NOT required that specifications for upgrade tokens be made publicly available, but the contact information for the registration SHOULD be 🫣.

8. Security Considerations 🚨

The potential for a man-in-the-middle attack (deleting the Upgrade header) is the same as it is with current, mixed http/https practice:

• Removing the Upgrade header is similar to rewriting web pages to change https:// links to http:// links.
• The risk is only present if the server is willing to vend such information over both a secure and an insecure channel in the first place.
• If the client knows for a fact that a server is TLS-compliant, it can insist on it by only sending an Upgrade request with a no-op method like OPTIONS.
• Finally, as the https: specification warns, "users should carefully examine the certificate presented by the server to determine if it meets their expectations" 👀.

Furthermore, for clients that don't explicitly try to invoke TLS, servers can use the Upgrade header in any response other than 101 or 426 to advertise TLS compliance. Since TLS compliance should be considered a feature of the server and not the resource at hand, it should be enough to send it once and let clients cache that fact 🧠.

8.1 Implications for the https: URI Scheme 🌐

While nothing in this memo affects the definition of the 'https' URI scheme, widespread adoption of this mechanism for HyperText content could let 'http' identify both secure and non-secure resources 🤯.

The choice of what security characteristics are required on the connection is left to the client and server. This lets either party use any information available in making that call. For example, user agents may rely on user preference settings or information about the security of the network, such as 'TLS required on all POST operations not on my local net', or servers may apply resource access rules such as 'the FORM on this page must be served and submitted using TLS' 🔐.

8.2 Security Considerations for CONNECT 🛡️

A generic TCP tunnel is fraught with security risks. First, such authorization should be limited to a small number of known ports. The Upgrade: mechanism defined here only requires onward tunneling at port 80. Second, since tunneled data is opaque to the proxy, there are additional risks to tunneling to other well-known or reserved ports. A putative HTTP client CONNECTing to port 25 could relay spam via SMTP, for example. 🚫📧

References

[1]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
     and T. Berners-Lee, "Hypertext Transfer Protocol --
     HTTP/1.1", RFC 2616, June 1999.

[2]  Berners-Lee, T., Fielding, R. and L. Masinter, "URI Generic
     Syntax", RFC 2396, August 1998.

[3]  Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.

[4]  Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen,
     "Web Distributed Authoring and Versioning", RFC 2518, February
     1999.

[5]  Slein, J., Whitehead, E.J., et al., "WebDAV Advanced Collections
     Protocol",  Work In Progress.

[6]  Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246, January
     1999.

[7]  Herriot, R., Butler, S., Moore, P. and R. Turner, "Internet
     Printing Protocol/1.0: Encoding and Transport", RFC 2565, April
     1999.

[8]  Luotonen, A., "Tunneling TCP based protocols through Web proxy
     servers",  Work In Progress.  (Also available in: Luotonen, Ari.
     Web Proxy Servers, Prentice-Hall, 1997 ISBN:0136806120.)

[9]  Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June
     1999.

[10] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
     Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.

[11] Bradner, S., "Key words for use in RFCs to Indicate Requirement
     Levels", BCP 14, RFC 2119, March 1997.

Authors' Addresses ✍️

Rohit Khare
4K Associates / UC Irvine
3207 Palo Verde
Irvine, CA  92612
US

Phone: +1 626 806 7574
EMail: rohit@4K-associates.com
URI:   http://www.4K-associates.com/


Scott Lawrence
Agranat Systems, Inc.
5 Clocktower Place
Suite 400
Maynard, MA  01754
US

Phone: +1 978 461 0888
EMail: lawrence@agranat.com
URI:   http://www.agranat.com/

Appendix A. Acknowledgments 💖

Okay, so the CONNECT method has the most iconic origin story 🎀. It started out in a Work in Progress called "Tunneling TCP based protocols through Web proxy servers" [8], written by Ari Luotonen of Netscape Communications Corporation. HTTP proxies ended up implementing it everywhere, but it never became part of any IETF Standards Track document 💀. The method name CONNECT was reserved in [1], but it wasn't actually defined there 🙈.

This definition is basically a glow-up of that older memo ✨. It has some editorial changes and follows the stylistic conventions that other HTTP specifications have since set 💅.

Big thanks to these bestties 🫶:

• Paul Hoffman for his work on the STARTTLS command extension for ESMTP.
• Roy Fielding for help with the rationale behind Upgrade: and its interaction with OPTIONS.
• Eric Rescorla for his work on standardizing the existing https: practice to compare with.
• Marshall Rose, for the xml2rfc document type description and tools [9].
• Jim Whitehead, for sorting out the current range of available HTTP status codes.
• Henrik Frystyk Nielsen, whose work on the Mandatory extension mechanism pointed out that a hop-by-hop Upgrade still requires tunneling.
• Harald Alvestrand for improvements to the token registration rules.

---

Full Copyright Statement 🌈

Legal time, but make it cute ✨. Here's the copyright text exactly as it's written, since the wording really matters:

Copyright (C) The Internet Society (2000).  All Rights Reserved.

This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works.  However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Quick vibe check: you can share and remix this doc, but the document itself can't be modified, so the copyright notice and Internet Society references have to stay put 🔒.

---

Acknowledgement 🧚

Funding for the RFC Editor function is currently provided by the Internet Society 💜.