Skip to main content

rushls_common/
proxy_protocol.rs

1//! PROXY protocol headers, read ahead of a TCP stream.
2//!
3//! A load balancer or TLS terminator in front of a listener opens its own
4//! connection, so the socket's peer is the proxy rather than the client. The
5//! proxy writes one header naming the original client before any application
6//! byte, and the rest of the stream is untouched.
7//!
8//! Both versions are accepted because proxies default to different ones:
9//! v1 is a text line (nginx `stream`), v2 is binary (AWS NLB, HAProxy
10//! `send-proxy-v2`). Only the addresses are used; v2 TLVs are skipped.
11//!
12//! A listener that enables this should make the header mandatory. An optional
13//! header would let any client that can reach the listener directly claim any
14//! address.
15//!
16//! Specification: <https://www.haproxy.org/download/2.9/doc/proxy-protocol.txt>
17
18use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr};
19
20use thiserror::Error;
21use tokio::io::{AsyncRead, AsyncReadExt};
22
23const V2_SIGNATURE: [u8; 12] = *b"\r\n\r\n\0\r\nQUIT\n";
24/// Longest legal v1 line, `\r\n` included.
25const V1_MAXIMUM: usize = 107;
26/// Addresses plus the TLVs real proxies attach fit far inside this; the
27/// header length field alone would allow a peer to demand 64 KiB of reading.
28const V2_MAXIMUM_PAYLOAD: usize = 1024;
29
30/// Why a connection did not open with a usable header.
31#[derive(Debug, Error)]
32pub enum HeaderError {
33    #[error("could not read the PROXY protocol header: {0}")]
34    Read(#[from] std::io::Error),
35    /// The usual cause is a client reaching the listener directly, bypassing
36    /// the proxy that should have written the header.
37    #[error("expected a PROXY protocol header")]
38    Missing,
39    #[error("PROXY protocol v1 line is longer than {V1_MAXIMUM} bytes")]
40    V1TooLong,
41    #[error("PROXY protocol v1 line is not ASCII")]
42    V1NotAscii,
43    #[error("malformed PROXY protocol v1 line {0:?}")]
44    V1Malformed(String),
45    #[error("unsupported PROXY protocol version {0}")]
46    V2Version(u8),
47    #[error("PROXY protocol v2 header of {0} bytes exceeds {V2_MAXIMUM_PAYLOAD}")]
48    V2TooLong(usize),
49    #[error("PROXY protocol v2 addresses are truncated ({0} bytes)")]
50    V2Truncated(usize),
51    #[error("PROXY protocol v2 family {0:#04x} is not TCP")]
52    V2Family(u8),
53    #[error("unsupported PROXY protocol v2 command {0:#x}")]
54    V2Command(u8),
55}
56
57/// Reads one header and returns the client it names.
58///
59/// `peer` is returned when the header carries no address: a v2 `LOCAL`
60/// command (proxy health checks) or an `UNKNOWN`/unspecified family. Reads
61/// exactly the header's bytes, so the stream resumes at the first byte the
62/// client sent. The caller bounds the time this may take.
63pub async fn read_header<S: AsyncRead + Unpin>(
64    io: &mut S,
65    peer: SocketAddr,
66) -> Result<SocketAddr, HeaderError> {
67    // Twelve bytes are enough to tell the versions apart: the shortest v1
68    // line, "PROXY UNKNOWN\r\n", is fifteen.
69    let mut start = [0; 12];
70    io.read_exact(&mut start).await?;
71    if start == V2_SIGNATURE {
72        read_v2(io, peer).await
73    } else if start.starts_with(b"PROXY ") {
74        read_v1(io, start, peer).await
75    } else {
76        Err(HeaderError::Missing)
77    }
78}
79
80async fn read_v1<S: AsyncRead + Unpin>(
81    io: &mut S,
82    start: [u8; 12],
83    peer: SocketAddr,
84) -> Result<SocketAddr, HeaderError> {
85    let mut line = start.to_vec();
86    // Byte at a time: reading ahead would consume bytes that belong to the
87    // application protocol. The line is at most 107 bytes.
88    while !line.ends_with(b"\r\n") {
89        if line.len() == V1_MAXIMUM {
90            return Err(HeaderError::V1TooLong);
91        }
92        line.push(io.read_u8().await?);
93    }
94    let line = std::str::from_utf8(&line[..line.len() - 2]).map_err(|_| HeaderError::V1NotAscii)?;
95    parse_v1(line, peer)
96}
97
98fn parse_v1(line: &str, peer: SocketAddr) -> Result<SocketAddr, HeaderError> {
99    let invalid = || HeaderError::V1Malformed(line.to_owned());
100    let fields: Vec<&str> = line.split(' ').collect();
101    match fields.as_slice() {
102        // The rest of an UNKNOWN line is undefined and must be ignored.
103        ["PROXY", "UNKNOWN", ..] => Ok(peer),
104        [
105            "PROXY",
106            family,
107            source,
108            _destination,
109            port,
110            _destination_port,
111        ] => {
112            let port: u16 = port.parse().map_err(|_| invalid())?;
113            let address = match *family {
114                "TCP4" => source.parse::<Ipv4Addr>().map(Into::into),
115                "TCP6" => source.parse::<Ipv6Addr>().map(Into::into),
116                _ => return Err(invalid()),
117            }
118            .map_err(|_| invalid())?;
119            Ok(SocketAddr::new(address, port))
120        }
121        _ => Err(invalid()),
122    }
123}
124
125async fn read_v2<S: AsyncRead + Unpin>(
126    io: &mut S,
127    peer: SocketAddr,
128) -> Result<SocketAddr, HeaderError> {
129    let mut fixed = [0; 4];
130    io.read_exact(&mut fixed).await?;
131    let [version_command, family, high, low] = fixed;
132    let length = usize::from(u16::from_be_bytes([high, low]));
133    if version_command >> 4 != 2 {
134        return Err(HeaderError::V2Version(version_command >> 4));
135    }
136    if length > V2_MAXIMUM_PAYLOAD {
137        return Err(HeaderError::V2TooLong(length));
138    }
139    // Consumed in full even when unused, so the stream resumes after it.
140    let mut payload = vec![0; length];
141    io.read_exact(&mut payload).await?;
142    parse_v2(version_command & 0x0f, family, &payload, peer)
143}
144
145fn parse_v2(
146    command: u8,
147    family: u8,
148    payload: &[u8],
149    peer: SocketAddr,
150) -> Result<SocketAddr, HeaderError> {
151    const LOCAL: u8 = 0x0;
152    const PROXY: u8 = 0x1;
153    const TCP_IPV4: u8 = 0x11;
154    const TCP_IPV6: u8 = 0x21;
155    const UNSPECIFIED: u8 = 0x00;
156    const UNIX_STREAM: u8 = 0x31;
157
158    let short = || HeaderError::V2Truncated(payload.len());
159    match (command, family) {
160        // The proxy's own connection, typically a health check.
161        (LOCAL, _) | (PROXY, UNSPECIFIED | UNIX_STREAM) => Ok(peer),
162        (PROXY, TCP_IPV4) => {
163            let bytes: [u8; 12] = payload
164                .get(..12)
165                .ok_or_else(short)?
166                .try_into()
167                .map_err(|_| short())?;
168            let address = Ipv4Addr::new(bytes[0], bytes[1], bytes[2], bytes[3]);
169            Ok(SocketAddr::new(
170                address.into(),
171                u16::from_be_bytes([bytes[8], bytes[9]]),
172            ))
173        }
174        (PROXY, TCP_IPV6) => {
175            let bytes: [u8; 36] = payload
176                .get(..36)
177                .ok_or_else(short)?
178                .try_into()
179                .map_err(|_| short())?;
180            let mut address = [0; 16];
181            address.copy_from_slice(&bytes[..16]);
182            Ok(SocketAddr::new(
183                Ipv6Addr::from(address).into(),
184                u16::from_be_bytes([bytes[32], bytes[33]]),
185            ))
186        }
187        (PROXY, family) => Err(HeaderError::V2Family(family)),
188        (command, _) => Err(HeaderError::V2Command(command)),
189    }
190}
191
192#[cfg(test)]
193mod tests {
194    use super::*;
195
196    type Result = std::result::Result<(), Box<dyn std::error::Error>>;
197
198    fn peer() -> SocketAddr {
199        SocketAddr::from(([10, 0, 0, 2], 40000))
200    }
201
202    /// Parses `header`, then returns the address and what the stream still holds.
203    async fn read(bytes: &[u8]) -> std::result::Result<(SocketAddr, Vec<u8>), HeaderError> {
204        let mut io = bytes;
205        let address = read_header(&mut io, peer()).await?;
206        Ok((address, io.to_vec()))
207    }
208
209    fn v2(command: u8, family: u8, payload: &[u8]) -> Vec<u8> {
210        let mut header = V2_SIGNATURE.to_vec();
211        header.push(0x20 | command);
212        header.push(family);
213        header.extend_from_slice(
214            &u16::try_from(payload.len())
215                .unwrap_or(u16::MAX)
216                .to_be_bytes(),
217        );
218        header.extend_from_slice(payload);
219        header
220    }
221
222    #[tokio::test]
223    async fn a_v1_line_names_the_client_and_leaves_the_stream_intact() -> Result {
224        let (address, rest) =
225            read(b"PROXY TCP4 203.0.113.7 10.0.0.5 51234 1935\r\n\x03rtmp").await?;
226        assert_eq!(address, "203.0.113.7:51234".parse()?);
227        assert_eq!(rest, b"\x03rtmp");
228
229        let (address, _) = read(b"PROXY TCP6 2001:db8::7 2001:db8::1 443 1935\r\n").await?;
230        assert_eq!(address, "[2001:db8::7]:443".parse()?);
231        Ok(())
232    }
233
234    #[tokio::test]
235    async fn a_v1_unknown_line_keeps_the_socket_peer() -> Result {
236        let (address, rest) = read(b"PROXY UNKNOWN ffff:f...f 1 2\r\nx").await?;
237        assert_eq!(address, peer());
238        assert_eq!(rest, b"x");
239        Ok(())
240    }
241
242    #[tokio::test]
243    async fn a_v2_header_names_the_client_and_skips_tlvs() -> Result {
244        let mut payload = vec![203, 0, 113, 7, 10, 0, 0, 5];
245        payload.extend_from_slice(&51234u16.to_be_bytes());
246        payload.extend_from_slice(&1935u16.to_be_bytes());
247        // An AWS VPC endpoint TLV, which is ignored.
248        payload.extend_from_slice(&[0xea, 0x00, 0x03, 0x01, b'v', b'p']);
249        let mut bytes = v2(0x1, 0x11, &payload);
250        bytes.extend_from_slice(b"\x03");
251        let (address, rest) = read(&bytes).await?;
252        assert_eq!(address, "203.0.113.7:51234".parse()?);
253        assert_eq!(rest, b"\x03");
254
255        let mut payload = Ipv6Addr::LOCALHOST.octets().to_vec();
256        payload.extend_from_slice(&Ipv6Addr::UNSPECIFIED.octets());
257        payload.extend_from_slice(&[0x01, 0xbb, 0x07, 0x8f]);
258        let (address, _) = read(&v2(0x1, 0x21, &payload)).await?;
259        assert_eq!(address, "[::1]:443".parse()?);
260        Ok(())
261    }
262
263    #[tokio::test]
264    async fn a_v2_local_command_keeps_the_socket_peer() -> Result {
265        let (address, rest) = read(&[v2(0x0, 0x00, &[]), b"x".to_vec()].concat()).await?;
266        assert_eq!(address, peer());
267        assert_eq!(rest, b"x");
268        Ok(())
269    }
270
271    #[tokio::test]
272    async fn anything_but_a_well_formed_header_is_refused() {
273        let refused: [&[u8]; 7] = [
274            // A client talking RTMP directly, bypassing the proxy.
275            b"\x03\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00rest",
276            b"PROXY TCP4 203.0.113.7 10.0.0.5 51234\r\n",
277            b"PROXY TCP4 not-an-address 10.0.0.5 1 2\r\n",
278            b"PROXY UDP4 203.0.113.7 10.0.0.5 1 2\r\n",
279            &[b"PROXY TCP4 ".as_slice(), &[b'1'; 120]].concat(),
280            &v2(0x1, 0x11, &[203, 0, 113]),
281            &v2(0x1, 0x12, &[0; 12]),
282        ];
283        for bytes in refused {
284            assert!(
285                read(bytes).await.is_err(),
286                "{:?}",
287                String::from_utf8_lossy(bytes)
288            );
289        }
290        assert!(matches!(
291            read(b"\x03\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00").await,
292            Err(HeaderError::Missing)
293        ));
294        let mut oversized = V2_SIGNATURE.to_vec();
295        oversized.extend_from_slice(&[0x21, 0x11, 0xff, 0xff]);
296        assert!(
297            matches!(read(&oversized).await, Err(HeaderError::V2TooLong(65535))),
298            "the length is bounded before reading"
299        );
300    }
301}