RFC 7639

The ALPN HTTP Header Field

📅 published August 2015, from ietf

RFC 7639: The ALPN HTTP Header Field 🎀

Okay bestie, RFC 7639 is The ALPN HTTP Header Field 💖 It's a Standards Track doc from the IETF stream (ISSN 2070-1721), written by A. Hutton of Unify, J. Uberti of Google, and M. Thomson of Mozilla, and it's dated August 2015. The title block doesn't list anything it obsoletes or updates, so it's standing on its own 🦋

Abstract ✨

So this spec lets HTTP CONNECT requests say what protocol is supposed to run inside the tunnel once it's set up, and it does that with the ALPN header field 🌸

Status of This Memo 📜

This is an Internet Standards Track document. 💜

It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 5741 ✨

For info on the current status of this document, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7639 🧚

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 🫶

Table of Contents 📚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
2.  The ALPN HTTP Header Field  . . . . . . . . . . . . . . . . .   3
  2.1.  Header Field Values . . . . . . . . . . . . . . . . . . .   3
  2.2.  Syntax  . . . . . . . . . . . . . . . . . . . . . . . . .   3
  2.3.  Usage . . . . . . . . . . . . . . . . . . . . . . . . . .   4
3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   4
4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
  5.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
  5.2.  Informative References  . . . . . . . . . . . . . . . . .   6
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   7

1. Introduction 💖

So the HTTP CONNECT method (Section 4.3.6 of [RFC7231]) asks the recipient to set up a tunnel to the origin server you named, and then forward packets both ways until the tunnel closes. These tunnels are super common for making end-to-end virtual connections through one or more proxies 🚇

The ALPN HTTP header field tells the proxy which protocol, or protocols, the client plans to run inside a tunnel made with CONNECT. It uses the Application-Layer Protocol Negotiation (ALPN) identifier from [RFC7301] ✨

If the tunnel gets secured with Transport Layer Security (TLS) [RFC5246], the header field carries the same application protocol label that shows up in the TLS handshake [RFC7301]. And if there's more than one possible application protocol, the header lists all of them 🦋

Here's the important bit: the ALPN header field is only client intent. ✨ An ALPN identifier just names the application protocol, or group of protocols, the client wants to use in the tunnel. Nothing gets negotiated through this header field. With TLS, the server makes the final pick from the choices the client offered. Other substrates could negotiate the application protocol in their own way 👑

Proxies don't implement the tunneled protocol, but they might make policy calls based on the header field value. For example, a proxy could use the application protocol to pick the right traffic prioritization 🔥

1.1. Requirements Language 💅

Okay, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document get read the way RFC 2119 [RFC2119] describes. They're the official requirement words, so they stay in caps 🎀

2. The ALPN HTTP Header Field 🌸

Clients put the ALPN header field in an HTTP CONNECT request to say which application-layer protocol they plan to use inside the tunnel. They can also list a set of protocols that might get used in there 🧚

2.1. Header Field Values 📝

The valid values for the protocol field come from the "Application-Layer Protocol Negotiation (ALPN) Protocol ID" registry [ALPN-IDS], which [RFC7301] set up 💜

2.2. Syntax 🔤

This is the ABNF (Augmented Backus-Naur Form) syntax for the ALPN header field value. It reuses the syntax from Section 1.2 of [RFC7230] ✨

ALPN            = 1#protocol-id
protocol-id     = token ; percent-encoded ALPN protocol identifier

ALPN protocol names are octet sequences, and there aren't any extra format constraints on them 🌈 But any octets that aren't allowed in tokens ([RFC7230], Section 3.2.6) MUST be percent-encoded, following Section 2.1 of [RFC3986]. That also means the octet for the percent character "%" (hex 25) MUST be percent-encoded too 🙈

To make sure there's exactly one way to write any ALPN protocol name, these extra rules apply:

  • Octets in the ALPN protocol MUST NOT be percent-encoded if they are valid token characters except "%".
  • When using percent-encoding, uppercase hex digits MUST be used.

With those rules, recipients can just do a simple string comparison to match protocol identifiers 💅

Here's an example:

CONNECT www.example.com HTTP/1.1
Host: www.example.com
ALPN: h2, http%2F1.1

2.3. Usage 🦋

When you use an ALPN identifier in the ALPN header field, it names an entire application protocol stack. It doesn't name one single layer or component 👑

For a CONNECT tunnel carrying a protocol secured with TLS, the ALPN header field value holds the same list of ALPN identifiers that go out in the TLS ClientHello message [RFC7301] ✨

Where no protocol negotiation is expected to happen, like with protocols that don't use TLS, the ALPN header field holds one ALPN protocol identifier for the application protocol you're planning to use. If some other form of protocol negotiation is possible, the header field holds the set of protocols that might get negotiated 🌸

A proxy can use the ALPN header field value to handle CONNECT tunnel requests more cleanly and efficiently. Exposing protocol info at the HTTP layer lets a proxy deny requests earlier and give better error reporting, like a 403 status code. ⚠️ The ALPN header field can be falsified, though, so it isn't enough on its own to authorize a request 🙅‍♀️

A proxy could try to inspect packets to figure out which protocol is in use. That only works if the proxy understands every ALPN identifier. Protocols like TLS can hide negotiated protocols, and protocol negotiation details can change over time. So Proxies SHOULD NOT break a CONNECT tunnel only because they failed to recognize the protocol. 💀

A proxy can also use the ALPN header field value to change how it manages or prioritizes connections 🔥

3. IANA Considerations 📋

HTTP header fields get registered in the "Permanent Message Header Field Names" registry that IANA maintains [MSG-HDRS]. This document defines and registers the ALPN header field following [RFC3864], like this 🎀

Header Field Name:  ALPN

Protocol:  http

Status:  Standard

Reference:  Section 2 of this document (RFC 7639)

Change Controller:  IETF (iesg@ietf.org) - Internet Engineering Task
      Force

4. Security Considerations 🔐

Okay, this section is serious, bestie. 😭 If you use HTTP CONNECT to reach a TURN server (Traversal Using Relays around NAT, [RFC5766]), the security considerations in Section 4.3.6 of [RFC7231] apply. That section says there "are significant risks in establishing a tunnel to arbitrary servers, particularly when the destination is a well-known or reserved TCP port that is not intended for Web traffic. ... Proxies that support CONNECT SHOULD restrict its use to a limited set of known ports or a configurable whitelist of safe request targets."

The ALPN header field in this document is OPTIONAL. Clients and HTTP proxies could choose not to support it, so they might either skip sending it or ignore it when it's there. If the header field is missing or gets ignored, a proxy can't tell what the tunnel is for, so it can't use that as input for any authorization decision about the tunnel. That looks exactly the same as a client or proxy that doesn't support the ALPN header field at all 🙈

There's no confidentiality protection for the ALPN header field. ALPN identifiers that might expose confidential or sensitive information SHOULD NOT be sent, as described in Section 5 of [RFC7301] 🤫

A client could falsify the value of the ALPN header field. If the data going through the tunnel is encrypted (for example, with TLS [RFC5246]), a proxy might not be able to inspect the data directly and check that the claimed protocol is really the one in use. A proxy might still do traffic analysis [TRAFFIC], though. So a proxy can't rely on the ALPN header field value as a policy input in every case 🚫

5. References 📚

5.1. Normative References 💜

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
           Procedures for Message Header Fields", BCP 90, RFC 3864,
           DOI 10.17487/RFC3864, September 2004,
           <http://www.rfc-editor.org/info/rfc3864>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <http://www.rfc-editor.org/info/rfc3986>.

[RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
           (HTTP/1.1): Message Syntax and Routing", RFC 7230,
           DOI 10.17487/RFC7230, June 2014,
           <http://www.rfc-editor.org/info/rfc7230>.

[RFC7231]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
           (HTTP/1.1): Semantics and Content", RFC 7231,
           DOI 10.17487/RFC7231, June 2014,
           <http://www.rfc-editor.org/info/rfc7231>.

[RFC7301]  Friedl, S., Popov, A., Langley, A., and E. Stephan,
           "Transport Layer Security (TLS) Application-Layer Protocol
           Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
           July 2014, <http://www.rfc-editor.org/info/rfc7301>.
⏭️ That's part 1! Part 2 picks up with the Informative References, the Authors' Addresses, and the rest, so stay tuned, bestie 💖

5.2. Informative References 📚

okay bestie, these are the extra reads 🤓 not required to get the spec, but they're where the receipts live. the IANA registry, two RFCs, a TURN paper, and one very spicy TLS traffic analysis paper 🔥

Authors' Addresses 🎀

the squad behind this one 🫶 here's where you can find them:

Andrew Hutton
Unify
Technology Drive
Nottingham  NG9 1LA
United Kingdom

Email: andrew.hutton@unify.com


Justin Uberti
Google
747 6th Street South
Kirkland, WA  98033
United States

Email: justin@uberti.name


Martin Thomson
Mozilla
331 East Evelyn Avenue
Mountain View, CA  94041
United States

Email: martin.thomson@gmail.com

that's the whole thing, bestie 🌈💖✨

📦 where this page comes from