feat(rdp): RD Gateway transport (experimental)

RDP profiles can go through a Remote Desktop Gateway (MS-TSGU over an
HTTPS WebSocket) with its own username and password, stored like other
credentials (rdp-gateway-password). The gateway stream is bridged to a
loopback socket so the blocking RDP client uses it like any transport.

IronRDP's gateway crate (0.0.1) is vendored with fixes: it used
ironrdp-tls, which accepts any certificate, before sending Basic
credentials — the gateway is now verified against the web PKI; its
asserts on gateway-supplied lengths are errors instead of panics; and
the server port is passed through. Checked against a self-signed
openssl s_server: the connection is refused ('invalid peer certificate')
before any request or credential is sent. Not tested against a real
gateway; Basic-auth gateways only (no NTLM).

rust/vendor/ironrdp-mstsgu/src/lib.rs

@@ -0,0 +1,487 @@
+#![cfg_attr(doc, doc = include_str!("../README.md"))]
+#![doc(html_logo_url = "https://cdnweb.devolutions.net/images/projects/devolutions/logos/devolutions-icon-shadow.svg")]
+
+#[macro_use]
+mod macros;
+
+mod proto;
+
+use core::fmt;
+use core::fmt::Display;
+use core::pin::Pin;
+use core::task::Poll;
+use core::time::Duration;
+use std::io;
+
+use base64::Engine as _;
+use base64::engine::general_purpose::STANDARD;
+use futures_util::stream::{SplitSink, SplitStream};
+use futures_util::{FutureExt as _, SinkExt as _, StreamExt as _};
+use hyper::body::Bytes;
+use ironrdp_core::{Decode as _, Encode, ReadCursor, WriteCursor};
+type TlsStream<S> = tokio_rustls::client::TlsStream<S>;
+use log::{error, warn};
+use tokio::io::{AsyncRead, AsyncWrite};
+use tokio::net::TcpStream;
+use tokio::sync::oneshot;
+use tokio_tungstenite::WebSocketStream;
+use tokio_tungstenite::tungstenite::handshake::client::generate_key;
+use tokio_tungstenite::tungstenite::protocol::Role;
+use tokio_tungstenite::tungstenite::{Message, http};
+use tokio_util::sync::PollSender;
+
+use self::proto::{
+    ChannelPkt, ChannelResp, DataPkt, HandshakeReqPkt, HandshakeRespPkt, HttpCapsTy, KeepalivePkt, PktHdr, PktTy,
+    TunnelAuthPkt, TunnelAuthRespPkt, TunnelReqPkt, TunnelRespPkt,
+};
+
+#[derive(Clone, Debug)]
+pub struct GwConnectTarget {
+    pub gw_endpoint: String,
+    pub gw_user: String,
+    pub gw_pass: String,
+
+    pub server: String,
+    /// The RDP server's port behind the gateway (Nexus patch: was always 3389).
+    pub server_port: u16,
+}
+
+type Error = ironrdp_error::Error<GwErrorKind>;
+
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum GwErrorKind {
+    InvalidGwTarget,
+    Connect,
+    PacketEof,
+    UnsupportedFeature,
+    Custom,
+    Encode,
+    Decode,
+}
+
+trait GwErrorExt {
+    fn custom<E>(context: &'static str, e: E) -> Self
+    where
+        E: core::error::Error + Sync + Send + 'static;
+}
+
+impl GwErrorExt for ironrdp_error::Error<GwErrorKind> {
+    #[track_caller]
+    fn custom<E>(context: &'static str, e: E) -> Self
+    where
+        E: core::error::Error + Sync + Send + 'static,
+    {
+        Self::new(context, GwErrorKind::Custom).with_source(e)
+    }
+}
+
+impl Display for GwErrorKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let x = match self {
+            GwErrorKind::InvalidGwTarget => "invalid GW Target",
+            GwErrorKind::Connect => "connection error",
+            GwErrorKind::PacketEof => "PacketEOF",
+            GwErrorKind::UnsupportedFeature => "unsupported feature",
+            GwErrorKind::Custom => "custom",
+            GwErrorKind::Encode => "encode",
+            GwErrorKind::Decode => "decode",
+        };
+        f.write_str(x)
+    }
+}
+
+impl core::error::Error for GwErrorKind {}
+
+struct GwConn {
+    client_name: String,
+    target: GwConnectTarget,
+    ws_sink: SplitSink<WebSocketStream<TlsStream<TcpStream>>, Message>,
+    ws_stream: SplitStream<WebSocketStream<TlsStream<TcpStream>>>,
+}
+
+pub struct GwClient {
+    work: tokio::task::JoinHandle<Result<(), Error>>,
+    rx: tokio::sync::mpsc::Receiver<Bytes>,
+    rx_bufs: Vec<Bytes>,
+    tx: PollSender<Bytes>,
+}
+
+impl Drop for GwClient {
+    fn drop(&mut self) {
+        self.work.abort();
+    }
+}
+
+impl GwClient {
+    pub async fn connect(
+        target: &GwConnectTarget,
+        client_name: &str,
+    ) -> Result<(GwClient, core::net::SocketAddr), Error> {
+        let gw_host = target
+            .gw_endpoint
+            .split(":")
+            .nth(0)
+            .ok_or_else(|| Error::new("Connect", GwErrorKind::InvalidGwTarget))?;
+
+        let stream = TcpStream::connect(&target.gw_endpoint)
+            .await
+            .map_err(|e| custom_err!("TCP connect", e))?;
+        let client_addr = stream
+            .local_addr()
+            .map_err(|e| custom_err!("get socket local address", e))?;
+
+        // Nexus patch: the gateway is a public HTTPS endpoint, so its certificate is verified
+        // against the web PKI (upstream used ironrdp-tls, which accepts any certificate, before
+        // sending Basic credentials).
+        let mut roots = tokio_rustls::rustls::RootCertStore::empty();
+        roots.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
+        let config = tokio_rustls::rustls::ClientConfig::builder_with_provider(std::sync::Arc::new(
+            tokio_rustls::rustls::crypto::ring::default_provider(),
+        ))
+        .with_safe_default_protocol_versions()
+        .map_err(|e| custom_err!("TLS config", e))?
+        .with_root_certificates(roots)
+        .with_no_client_auth();
+        let name = tokio_rustls::rustls::pki_types::ServerName::try_from(gw_host.to_owned())
+            .map_err(|e| custom_err!("gateway host name", e))?;
+        let stream = tokio_rustls::TlsConnector::from(std::sync::Arc::new(config))
+            .connect(name, stream)
+            .await
+            .map_err(|e| custom_err!("TLS connect", e))?;
+
+        let auth_val: String = STANDARD.encode(format!("{}:{}", target.gw_user, target.gw_pass));
+        let req = http::Request::builder()
+            .method("RDG_OUT_DATA")
+            .header(hyper::header::HOST, gw_host)
+            .header("Rdg-Connection-Id", format!("{{{}}}", uuid::Uuid::new_v4()))
+            .uri("/remoteDesktopGateway/")
+            .header(hyper::header::AUTHORIZATION, format!("Basic {auth_val}"))
+            .header(hyper::header::CONNECTION, "Upgrade")
+            .header(hyper::header::UPGRADE, "websocket")
+            .header(hyper::header::SEC_WEBSOCKET_VERSION, "13")
+            .header(hyper::header::SEC_WEBSOCKET_KEY, generate_key())
+            .body(http_body_util::Empty::<Bytes>::new())
+            .map_err(|e| custom_err!("failed to build request", e))?;
+
+        let stream = hyper_util::rt::tokio::TokioIo::new(stream);
+        let (mut sender, mut conn) = hyper::client::conn::http1::handshake(stream)
+            .await
+            .map_err(|e| custom_err!("H1 Handshake", e))?;
+        let (tx, rx) = oneshot::channel();
+
+        let jh = tokio::task::spawn(async move {
+            tokio::select! {
+                Err(e) = &mut conn => error!("Handshake error: {:?}", e),
+                _ = rx => (),
+            }
+            conn.into_parts()
+        });
+        let resp = sender
+            .send_request(req)
+            .await
+            .map_err(|e| custom_err!("WS Upgrade Send error", e))?;
+
+        if resp.status() != http::StatusCode::SWITCHING_PROTOCOLS {
+            return Err(Error::new("WS Upgrade", GwErrorKind::Connect));
+        }
+
+        let _ = tx.send(()); // TODO: Not needed since it doesnt keep alive conn?
+        let stream = jh.await.map_err(|e| custom_err!("WS join", e))?.io.into_inner();
+
+        Self::connect_ws(target.clone(), client_name, stream)
+            .await
+            .map(|x| (x, client_addr))
+    }
+
+    async fn connect_ws(
+        target: GwConnectTarget,
+        client_name: &str,
+        tls_stream: TlsStream<TcpStream>,
+    ) -> Result<GwClient, Error> {
+        let ws_stream: WebSocketStream<_> = WebSocketStream::from_raw_socket(tls_stream, Role::Client, None).await;
+        let (ws_sink, ws_stream) = ws_stream.split();
+        let mut gw = GwConn {
+            client_name: client_name.to_owned(),
+            target,
+            ws_sink,
+            ws_stream,
+        };
+
+        gw.handshake().await?;
+        gw.tunnel().await?;
+        gw.tunnel_auth().await?;
+        gw.channel().await?;
+
+        let (in_tx, in_rx) = tokio::sync::mpsc::channel(4);
+        let (out_tx, mut out_rx) = tokio::sync::mpsc::channel::<Bytes>(4);
+
+        let work = tokio::spawn(async move {
+            let iv = Duration::from_secs(15 * 60);
+            let mut keepalive_interval = tokio::time::interval_at(tokio::time::Instant::now() + iv, iv);
+
+            loop {
+                let mut wsbuf = [0u8; 8192];
+
+                tokio::select!(
+                    _ = keepalive_interval.tick() => {
+                        let pos = {
+                            let mut cur = WriteCursor::new(&mut wsbuf);
+                            KeepalivePkt.encode(&mut cur).map_err(|e| custom_err!("PktEncode", e))?;
+                            cur.pos()
+                        };
+
+                        gw.ws_sink.send(Message::Binary(Bytes::copy_from_slice(&wsbuf[..pos]))).await.map_err(|e| custom_err!("ws send", e))?;
+                    },
+                    next = gw.ws_stream.next() => {
+                        let tmp = next.ok_or_else(|| Error::new("WS Stream Dead", GwErrorKind::Connect))?;
+                        let msg = tmp.map_err(|e| custom_err!("Stream", e))?.into_data();
+                        let mut cur = ReadCursor::new(&msg);
+                        let hdr = PktHdr::decode(&mut cur).map_err(|e| custom_err!("Header Decode", e))?;
+
+                        let header_length = usize::try_from(hdr.length).map_err(|_| Error::new("PktHdr too big", GwErrorKind::Decode))?;
+                        // Nexus patch: a short or inconsistent packet is an error, not a panic.
+                        if header_length.checked_sub(hdr.size()).is_none_or(|body| cur.len() < body) {
+                            return Err(Error::new("PktHdr length", GwErrorKind::Decode));
+                        }
+                        match hdr.ty {
+                            PktTy::Keepalive => {
+                                continue;
+                            },
+                            PktTy::Data => {
+                                let p = DataPkt::decode(&mut cur).map_err(|e| custom_err!("PktDecode", e))?;
+                                in_tx.send(Bytes::from(p.data.to_vec())).await.map_err(|e| custom_err!("in_tx dead", e))?;
+                            },
+                            x => {
+                                warn!("Unhandled gw packet type {x:?}");
+                            }
+                        }
+                    },
+                    next = out_rx.recv() => {
+                        let next = next.ok_or_else(|| Error::new("WS Sink Dead", GwErrorKind::Connect))?;
+                        let pkt = DataPkt { data: &next };
+
+                        let pos = {
+                            let mut cur = WriteCursor::new(&mut wsbuf);
+                            pkt.encode(&mut cur).map_err(|e| custom_err!("PktEncode", e))?;
+                            cur.pos()
+                        };
+                        gw.ws_sink.send(Message::Binary(Bytes::copy_from_slice(&wsbuf[..pos]))).await.map_err(|e| custom_err!("ws send", e))?;
+                    }
+                );
+            }
+        });
+
+        Ok(GwClient {
+            work,
+            rx: in_rx,
+            rx_bufs: vec![],
+            tx: PollSender::new(out_tx),
+        })
+    }
+}
+
+impl GwConn {
+    async fn send_packet<E: Encode>(&mut self, payload: &E) -> Result<(), Error> {
+        let mut buf = [0u8; 4096];
+        let pos = {
+            let mut cur = WriteCursor::new(&mut buf);
+            payload
+                .encode(&mut cur)
+                .map_err(|e| Error::new("packet encode", GwErrorKind::Encode).with_source(e))?;
+            cur.pos()
+        };
+        self.ws_sink
+            .send(Message::Binary(Bytes::copy_from_slice(&buf[..pos])))
+            .await
+            .map_err(|e| custom_err!("WebSocket send error", e))?;
+        Ok(())
+    }
+
+    async fn read_packet(&mut self) -> Result<(PktHdr, Bytes), Error> {
+        let mut msg = self
+            .ws_stream
+            .next()
+            .await
+            .ok_or_else(|| Error::new("Stream closed", GwErrorKind::Connect))?
+            .map_err(|e| custom_err!("WS err", e))?
+            .into_data();
+        let mut cur = ReadCursor::new(&msg);
+
+        let hdr = PktHdr::decode(&mut cur).map_err(|_| Error::new("PktHdr", GwErrorKind::Decode))?;
+
+        let header_length =
+            usize::try_from(hdr.length).map_err(|_| Error::new("PktHdr too big", GwErrorKind::Decode))?;
+        if header_length.checked_sub(hdr.size()) != Some(cur.len()) {
+            return Err(Error::new("read_packet", GwErrorKind::PacketEof));
+        }
+
+        Ok((hdr, msg.split_off(cur.pos())))
+    }
+
+    async fn handshake(&mut self) -> Result<(), Error> {
+        // For NTLM we would include extended_auth: NTLM_SSPI in this handshake req here.
+        let hs = HandshakeReqPkt {
+            ver_major: 1,
+            ver_minor: 0,
+            ..HandshakeReqPkt::default()
+        };
+        self.send_packet(&hs).await?;
+        let (_hdr, bytes) = self.read_packet().await?;
+
+        let mut cur = ReadCursor::new(&bytes);
+        let resp = HandshakeRespPkt::decode(&mut cur).map_err(|_| Error::new("Handshake", GwErrorKind::Decode))?;
+        if resp.error_code != 0 || resp.ver_major != 1 || resp.ver_minor != 0 || resp.server_version != 0 {
+            return Err(Error::new("Handshake", GwErrorKind::Connect));
+        }
+        Ok(())
+    }
+
+    async fn tunnel(&mut self) -> Result<(), Error> {
+        let req = TunnelReqPkt {
+            // Havent seen any server working without this.
+            caps: HttpCapsTy::MessagingConsentSign.as_u32(),
+            fields_present: 0,
+            ..TunnelReqPkt::default()
+        };
+        self.send_packet(&req).await?;
+
+        let (_hdr, bytes) = self.read_packet().await?;
+        let mut cur = ReadCursor::new(&bytes);
+
+        let resp = TunnelRespPkt::decode(&mut cur).map_err(|_| Error::new("TunnelDecode", GwErrorKind::Decode))?;
+        if resp.status_code != 0 {
+            return Err(Error::new("Tunnel", GwErrorKind::Connect));
+        }
+        if !cur.eof() {
+            return Err(Error::new("Tunnel", GwErrorKind::Decode));
+        }
+        if !resp.consent_msg.is_empty() {
+            return Err(Error::new(
+                "Received consent message but showing it not implemented",
+                GwErrorKind::UnsupportedFeature,
+            ));
+        }
+        Ok(())
+    }
+
+    async fn tunnel_auth(&mut self) -> Result<(), Error> {
+        let req = TunnelAuthPkt {
+            fields_present: 0,
+            client_name: self.client_name.clone(),
+        };
+        self.send_packet(&req).await?;
+
+        let (_hdr, bytes) = self.read_packet().await?;
+        let mut cur = ReadCursor::new(&bytes);
+        let resp: TunnelAuthRespPkt =
+            TunnelAuthRespPkt::decode(&mut cur).map_err(|_| Error::new("TunnelAuth", GwErrorKind::Decode))?;
+
+        if resp.error_code() != 0 {
+            return Err(Error::new("TunnelAuth", GwErrorKind::Connect));
+        }
+        Ok(())
+    }
+
+    async fn channel(&mut self) -> Result<ChannelResp, Error> {
+        let req = ChannelPkt {
+            resources: vec![self.target.server.clone()],
+            port: self.target.server_port,
+            protocol: 3,
+        };
+        self.send_packet(&req).await?;
+
+        let (hdr, bytes) = self.read_packet().await?;
+        if hdr.ty != PktTy::ChannelResp {
+            return Err(Error::new("ChannelResp", GwErrorKind::Decode));
+        }
+        let mut cur: ReadCursor<'_> = ReadCursor::new(&bytes);
+        let resp: ChannelResp =
+            ChannelResp::decode(&mut cur).map_err(|_| Error::new("ChannelResp", GwErrorKind::Decode))?;
+        if resp.error_code() != 0 {
+            return Err(Error::new("ChannelCreate", GwErrorKind::Connect));
+        }
+        if !cur.eof() {
+            return Err(Error::new("ChannelResp", GwErrorKind::Decode));
+        }
+        Ok(resp)
+    }
+}
+
+impl AsyncRead for GwClient {
+    fn poll_read(
+        mut self: Pin<&mut Self>,
+        cx: &mut core::task::Context<'_>,
+        buf: &mut tokio::io::ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        // Propagate error or premature exit (?)
+        match self.work.poll_unpin(cx) {
+            Poll::Ready(Err(e)) => return Poll::Ready(Err(io::Error::other(e))),
+            Poll::Ready(Ok(Err(e))) => return Poll::Ready(Err(io::Error::other(e))),
+            Poll::Ready(_) => return Poll::Ready(Err(io::Error::other("Premature Work Task end?"))),
+            _ => (),
+        }
+
+        // Get new bufs
+        if let Poll::Ready(Some(new_buf)) = self.rx.poll_recv(cx) {
+            self.rx_bufs.push(new_buf);
+        }
+
+        // Read from all queued bufs
+        let mut n = 0;
+        self.rx_bufs.retain_mut(|rx_buf| {
+            let rem = buf.remaining();
+            if rem == 0 {
+                return true;
+            }
+            let max = core::cmp::min(rem, rx_buf.len());
+            buf.put_slice(&rx_buf[..max]);
+            n += max;
+            let _ = rx_buf.split_to(max);
+
+            !rx_buf.is_empty()
+        });
+
+        if n > 0 { Poll::Ready(Ok(())) } else { Poll::Pending }
+    }
+}
+
+impl AsyncWrite for GwClient {
+    fn poll_write(
+        mut self: Pin<&mut Self>,
+        cx: &mut core::task::Context<'_>,
+        buf: &[u8],
+    ) -> Poll<Result<usize, io::Error>> {
+        // Propagate error or premature exit (?)
+        match self.work.poll_unpin(cx) {
+            Poll::Ready(Err(e)) => return Poll::Ready(Err(io::Error::other(e))),
+            Poll::Ready(Ok(Err(e))) => return Poll::Ready(Err(io::Error::other(e))),
+            Poll::Ready(_) => return Poll::Ready(Err(io::Error::other("Premature Work Task end?"))),
+            Poll::Pending => (),
+        }
+
+        match self.tx.poll_reserve(cx) {
+            Poll::Ready(Ok(())) => {
+                if self.tx.send_item(Bytes::from(buf.to_vec())).is_err() {
+                    return Poll::Ready(Err(io::Error::other("Sender closed")));
+                }
+                return Poll::Ready(Ok(buf.len()));
+            }
+            Poll::Ready(Err(err)) => {
+                return Poll::Ready(Err(io::Error::other(err)));
+            }
+            Poll::Pending => (),
+        }
+
+        Poll::Pending
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut core::task::Context<'_>) -> Poll<Result<(), io::Error>> {
+        // TODO: call flush on the backing sink (e.g. websocket, but atleast for that backend doesnt seem to matter)?
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut core::task::Context<'_>) -> Poll<Result<(), io::Error>> {
+        Poll::Ready(Ok(()))
+    }
+}

rust/vendor/ironrdp-mstsgu/src/macros.rs

@@ -0,0 +1,5 @@
+/// Creates a [`crate::Error`] with `Custom` kind and a source error attached to it
+#[macro_export]
+macro_rules! custom_err {
+    ( $context:expr, $source:expr $(,)? ) => {{ <$crate::Error as $crate::GwErrorExt>::custom($context, $source) }};
+}

rust/vendor/ironrdp-mstsgu/src/proto.rs

@@ -0,0 +1,601 @@
+use bitflags::bitflags;
+use ironrdp_core::{
+    Decode, Encode, ReadCursor, WriteCursor, cast_int, cast_length, ensure_fixed_part_size, ensure_size,
+    unsupported_value_err,
+};
+
+bitflags! {
+    /// 2.2.5.3.2 HTTP_EXTENDED_AUTH Enumeration
+    #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+    pub(crate) struct HttpExtendedAuth: u16 {
+        const HTTP_EXTENDED_AUTH_NONE = 0x01;
+        const HTTP_EXTENDED_AUTH_SC = 0x01;
+        const HTTP_EXTENDED_AUTH_PAA = 0x02;
+        const HTTP_EXTENDED_AUTH_SSPI_NTLM = 0x04;
+    }
+}
+
+/// 2.2.5.3.3 HTTP_PACKET_TYPE Enumeration
+#[repr(u16)]
+#[derive(Eq, PartialEq, Copy, Clone, Debug, Default)]
+pub(crate) enum PktTy {
+    #[default]
+    Invalid,
+    HandshakeReq = 0x01,
+    HandshakeResp = 0x02,
+    ExtendedAuth = 0x03,
+    TunnelCreate = 0x04,
+    TunnelResp = 0x05,
+    TunnelAuth = 0x06,
+    TunnelAuthResponse = 0x07,
+    ChannelCreate = 0x08,
+    ChannelResp = 0x09,
+    ChannelClose = 0x10,
+    Data = 0x0A,
+    ServiceMessage = 0x0B,
+    ReauthMessage = 0x0C,
+    Keepalive = 0x0D,
+}
+
+impl PktTy {
+    #[expect(
+        clippy::as_conversions,
+        reason = "guarantees discriminant layout, and as is the only way to cast enum -> primitive"
+    )]
+    fn as_u16(self) -> u16 {
+        self as u16
+    }
+}
+
+impl TryFrom<u16> for PktTy {
+    type Error = ();
+
+    fn try_from(val: u16) -> Result<Self, Self::Error> {
+        let mapped = match val {
+            0x01 => PktTy::HandshakeReq,
+            0x02 => PktTy::HandshakeResp,
+            0x03 => PktTy::ExtendedAuth,
+            0x04 => PktTy::TunnelCreate,
+            0x05 => PktTy::TunnelResp,
+            0x06 => PktTy::TunnelAuth,
+            0x07 => PktTy::TunnelAuthResponse,
+            0x08 => PktTy::ChannelCreate,
+            0x09 => PktTy::ChannelResp,
+            0x0A => PktTy::Data,
+            0x0B => PktTy::ServiceMessage,
+            0x0C => PktTy::ReauthMessage,
+            0x0D => PktTy::Keepalive,
+            0x10 => PktTy::ChannelClose,
+            _ => return Err(()),
+        };
+        Ok(mapped)
+    }
+}
+
+/// 2.2.10.9 HTTP_PACKET_HEADER Structure
+#[derive(Default, Debug)]
+pub(crate) struct PktHdr {
+    pub ty: PktTy,
+    pub _reserved: u16,
+    pub length: u32,
+}
+
+impl PktHdr {
+    const FIXED_PART_SIZE: usize = 4 /* ty */ + 2 /* _reserved */ + 2 /* length */;
+}
+
+impl Encode for PktHdr {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        dst.write_u16(self.ty.as_u16());
+        dst.write_u16(self._reserved);
+        dst.write_u32(self.length);
+
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_PACKET_HEADER"
+    }
+
+    fn size(&self) -> usize {
+        Self::FIXED_PART_SIZE
+    }
+}
+
+impl<'a> Decode<'a> for PktHdr {
+    fn decode(src: &mut ReadCursor<'a>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_fixed_part_size!(in: src);
+
+        let ty = src.read_u16();
+        let mty = PktTy::try_from(ty).map_err(|_| unsupported_value_err("PktHdr::ty", "ty", format!("0x{ty:x}")))?;
+
+        Ok(PktHdr {
+            ty: mty,
+            _reserved: src.read_u16(),
+            length: src.read_u32(),
+        })
+    }
+}
+
+/// 2.2.10.10 HTTP_HANDSHAKE_REQUEST_PACKET Structure
+#[derive(Default)]
+pub(crate) struct HandshakeReqPkt {
+    pub ver_major: u8,
+    pub ver_minor: u8,
+    pub client_version: u16,
+    pub extended_auth: HttpExtendedAuth,
+}
+
+impl Encode for HandshakeReqPkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::HandshakeReq,
+            length: u32::try_from(self.size()).expect("handshake packet size fits in u32"),
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+
+        dst.write_u8(self.ver_major);
+        dst.write_u8(self.ver_minor);
+        dst.write_u16(self.client_version);
+        dst.write_u16(self.extended_auth.bits());
+
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_HANDSHAKE_REQUEST_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::FIXED_PART_SIZE + 6
+    }
+}
+
+/// 2.2.10.11 HTTP_HANDSHAKE_RESPONSE_PACKET Structure
+#[derive(Debug)]
+pub(crate) struct HandshakeRespPkt {
+    pub error_code: u32,
+    pub ver_major: u8,
+    pub ver_minor: u8,
+    pub server_version: u16,
+    pub _extended_auth: HttpExtendedAuth,
+}
+
+impl HandshakeRespPkt {
+    const FIXED_PART_SIZE: usize = 4 /* error_code */ + 1 /* ver_major */ + 1 /* ver_minor */ + 2 /* server_auth */ + 1 /*extended_auth*/;
+}
+
+impl Decode<'_> for HandshakeRespPkt {
+    fn decode(src: &mut ReadCursor<'_>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_fixed_part_size!(in: src);
+
+        Ok(HandshakeRespPkt {
+            error_code: src.read_u32(),
+            ver_major: src.read_u8(),
+            ver_minor: src.read_u8(),
+            server_version: src.read_u16(),
+            _extended_auth: {
+                let raw = src.read_u16();
+                HttpExtendedAuth::from_bits(raw)
+                    .ok_or_else(|| unsupported_value_err("HandshakeResp", "extended_auth", format!("0x{raw:x}")))?
+            },
+        })
+    }
+}
+
+/// 2.2.10.18 HTTP_TUNNEL_PACKET
+#[derive(Default)]
+pub(crate) struct TunnelReqPkt {
+    pub caps: u32,
+    pub fields_present: u16,
+    pub _reserved: u16,
+}
+
+impl Encode for TunnelReqPkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::TunnelCreate,
+            length: u32::try_from(self.size()).expect("tunnel request packet size fits in u32"),
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+
+        dst.write_u32(self.caps);
+        dst.write_u16(self.fields_present);
+        dst.write_u16(self._reserved);
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_TUNNEL_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size() + 8
+    }
+}
+
+/// 2.2.5.3.9 HTTP_CAPABILITY_TYPE Enumeration
+#[repr(u32)]
+#[expect(dead_code)]
+#[derive(Copy, Clone)]
+pub(crate) enum HttpCapsTy {
+    QuarSOH = 1,
+    IdleTimeout = 2,
+    MessagingConsentSign = 4,
+    MessagingServiceMsg = 8,
+    Reauth = 0x10,
+    UdpTransport = 0x20,
+}
+
+impl HttpCapsTy {
+    #[expect(
+        clippy::as_conversions,
+        reason = "guarantees discriminant layout, and as is the only way to cast enum -> primitive"
+    )]
+    pub(crate) fn as_u32(self) -> u32 {
+        self as u32
+    }
+}
+
+/// 2.2.5.3.8 HTTP_TUNNEL_RESPONSE_FIELDS_PRESENT_FLAGS
+#[repr(u16)]
+#[derive(Copy, Clone)]
+enum HttpTunnelResponseFields {
+    TunnelID = 1,
+    Caps = 2,
+    /// nonce & server_cert
+    Soh = 4,
+    Consent = 0x10,
+}
+
+impl HttpTunnelResponseFields {
+    #[expect(
+        clippy::as_conversions,
+        reason = "guarantees discriminant layout, and as is the only way to cast enum -> primitive"
+    )]
+    fn as_u16(self) -> u16 {
+        self as u16
+    }
+}
+
+/// 2.2.10.20 HTTP_TUNNEL_RESPONSE Structure
+#[derive(Debug, Default)]
+pub(crate) struct TunnelRespPkt {
+    pub _server_version: u16,
+    pub status_code: u32,
+    pub fields_present: u16,
+    pub _reserved: u16,
+
+    // 2.2.10.21 HTTP_TUNNEL_RESPONSE_OPTIONAL
+    pub tunnel_id: Option<u32>,
+    pub caps_flags: Option<u32>,
+    pub nonce: Option<u16>,
+    pub server_cert: Vec<u8>,
+    pub consent_msg: Vec<u8>,
+}
+
+impl TunnelRespPkt {
+    const FIXED_PART_SIZE: usize = 2 /* server_version */ + 4 /* status_code */ + 2 /* fields_present */ + 2 /* reserved */;
+}
+
+impl Decode<'_> for TunnelRespPkt {
+    fn decode(src: &mut ReadCursor<'_>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_fixed_part_size!(in: src);
+
+        let mut pkt = TunnelRespPkt {
+            _server_version: src.read_u16(),
+            status_code: src.read_u32(),
+            fields_present: src.read_u16(),
+            _reserved: src.read_u16(),
+            ..TunnelRespPkt::default()
+        };
+
+        if pkt.fields_present & (HttpTunnelResponseFields::TunnelID.as_u16()) != 0 {
+            ensure_size!(in: src, size: 4);
+            pkt.tunnel_id = Some(src.read_u32());
+        }
+        if pkt.fields_present & (HttpTunnelResponseFields::Caps.as_u16()) != 0 {
+            ensure_size!(in: src, size: 4);
+            pkt.caps_flags = Some(src.read_u32());
+        }
+        if pkt.fields_present & (HttpTunnelResponseFields::Soh.as_u16()) != 0 {
+            ensure_size!(in: src, size: 2 + 2);
+            pkt.nonce = Some(src.read_u16());
+            let len = usize::from(src.read_u16());
+            ensure_size!(in: src, size: len);
+            pkt.server_cert = src.read_slice(len).to_vec();
+        }
+        if pkt.fields_present & (HttpTunnelResponseFields::Consent.as_u16()) != 0 {
+            ensure_size!(in: src, size: 2);
+            let len = usize::from(src.read_u16());
+            ensure_size!(in: src, size: len);
+            pkt.consent_msg = src.read_slice(len).to_vec();
+        }
+
+        Ok(pkt)
+    }
+}
+
+/// 2.2.10.7 HTTP_EXTENDED_AUTH_PACKET Structure
+#[expect(dead_code, reason = "defined for completeness per spec; not yet used")]
+pub(crate) struct ExtendedAuthPkt {
+    error_code: u32,
+    blob: Vec<u8>,
+}
+
+impl Encode for ExtendedAuthPkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::ExtendedAuth,
+            length: cast_int!("packet length", self.size())?,
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+
+        dst.write_u32(self.error_code);
+        let blob_len: u16 = cast_int!("blob length", self.blob.len())?;
+        dst.write_u16(blob_len);
+        dst.write_slice(&self.blob);
+
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_EXTENDED_AUTH_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size() + 6 + self.blob.len()
+    }
+}
+
+impl Decode<'_> for ExtendedAuthPkt {
+    fn decode(src: &mut ReadCursor<'_>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_size!(in: src, size: 4 + 2);
+        let error_code = src.read_u32();
+        let len = usize::from(src.read_u16());
+        ensure_size!(in: src, size: len);
+
+        Ok(ExtendedAuthPkt {
+            error_code,
+            blob: src.read_slice(len).to_vec(),
+        })
+    }
+}
+
+/// 2.2.10.14 HTTP_TUNNEL_AUTH_PACKET Structure
+pub(crate) struct TunnelAuthPkt {
+    pub fields_present: u16,
+    pub client_name: String,
+}
+
+impl Encode for TunnelAuthPkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::TunnelAuth,
+            length: cast_int!("packet length", self.size())?,
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+
+        dst.write_u16(self.fields_present);
+
+        let client_name_len = self.client_name.encode_utf16().count() * 2 + 2; // Add 2 to account for a null terminator (0x0000).
+        let client_name_len: u16 = cast_int!("client name length", client_name_len)?;
+        dst.write_u16(client_name_len);
+
+        for c in self.client_name.encode_utf16() {
+            dst.write_u16(c);
+        }
+
+        dst.write_u16(0);
+
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_TUNNEL_AUTH_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size() + 4 + 2 * (self.client_name.len() + 1)
+    }
+}
+
+/// 2.2.10.16 HTTP_TUNNEL_AUTH_RESPONSE Structure
+#[derive(Debug)]
+pub(crate) struct TunnelAuthRespPkt {
+    error_code: u32,
+    _fields_present: u16,
+    _reserved: u16,
+}
+
+impl TunnelAuthRespPkt {
+    const FIXED_PART_SIZE: usize = 4 /* error_code */ + 2 /* fields_present */ + 2 /* _reserved */;
+
+    pub(crate) fn error_code(&self) -> u32 {
+        self.error_code
+    }
+}
+
+impl Decode<'_> for TunnelAuthRespPkt {
+    fn decode(src: &mut ReadCursor<'_>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_fixed_part_size!(in: src);
+
+        Ok(TunnelAuthRespPkt {
+            error_code: src.read_u32(),
+            _fields_present: src.read_u16(),
+            _reserved: src.read_u16(),
+        })
+    }
+}
+
+/// 2.2.10.2 HTTP_CHANNEL_PACKET
+pub(crate) struct ChannelPkt {
+    pub resources: Vec<String>,
+    pub port: u16,
+    pub protocol: u16,
+}
+
+impl Encode for ChannelPkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::ChannelCreate,
+            length: cast_int!("packet length", self.size())?,
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+
+        let resources_count: u8 = cast_length!("resources count", self.resources.len())?;
+        dst.write_u8(resources_count);
+        dst.write_u8(0); // alt_names
+        dst.write_u16(self.port);
+        dst.write_u16(self.protocol);
+
+        // 2.2.10.3 HTTP_CHANNEL_PACKET_VARIABLE
+        for res in &self.resources {
+            let res_utf16_len = res.encode_utf16().count() * 2 + 2; // Add 2 to account for a null terminator (0x0000).
+            let res_len: u16 = cast_int!("resource name UTF-16 length", res_utf16_len)?;
+            dst.write_u16(res_len);
+            for b in res.encode_utf16() {
+                dst.write_u16(b);
+            }
+            dst.write_u16(0);
+        }
+
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_CHANNEL_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size() + 6 + self.resources.iter().map(|x| 2 + 2 * (x.len() + 1)).sum::<usize>()
+    }
+}
+
+/// 2.2.10.4 HTTP_CHANNEL_RESPONSE
+#[derive(Default, Debug)]
+pub(crate) struct ChannelResp {
+    error_code: u32,
+    fields_present: u16,
+    _reserved: u16,
+
+    /// 2.2.10.5 HTTP_CHANNEL_RESPONSE_OPTIONAL
+    chan_id: Option<u32>,
+    udp_port: u16,
+    authn_cookie: Vec<u8>,
+}
+
+impl ChannelResp {
+    const FIXED_PART_SIZE: usize = 4 /* error_code */ + 2 /* fields_present */ + 2 /* _reserved */;
+
+    pub(crate) fn error_code(&self) -> u32 {
+        self.error_code
+    }
+}
+
+impl Decode<'_> for ChannelResp {
+    fn decode(src: &mut ReadCursor<'_>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_fixed_part_size!(in: src);
+
+        let mut resp = ChannelResp {
+            error_code: src.read_u32(),
+            fields_present: src.read_u16(),
+            _reserved: src.read_u16(),
+            ..ChannelResp::default()
+        };
+        if resp.fields_present & 1 != 0 {
+            ensure_size!(in: src, size: 4);
+            resp.chan_id = Some(src.read_u32());
+        }
+        if resp.fields_present & 2 != 0 {
+            ensure_size!(in: src, size: 2);
+            resp.udp_port = src.read_u16();
+        }
+        if resp.fields_present & 4 != 0 {
+            ensure_size!(in: src, size: 2);
+            let len = usize::from(src.read_u16());
+            ensure_size!(in: src, size: len);
+            resp.authn_cookie = src.read_slice(len).to_vec();
+        }
+        Ok(resp)
+    }
+}
+
+/// 2.2.10.6 HTTP_DATA_PACKET
+pub(crate) struct DataPkt<'a> {
+    pub data: &'a [u8],
+}
+
+impl Encode for DataPkt<'_> {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        ensure_size!(in: dst, size: self.size());
+
+        let hdr = PktHdr {
+            ty: PktTy::Data,
+            length: cast_int!("packet length", self.size())?,
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)?;
+        let data_len: u16 = cast_int!("data payload length", self.data.len())?;
+        dst.write_u16(data_len);
+        dst.write_slice(self.data);
+        Ok(())
+    }
+
+    fn name(&self) -> &'static str {
+        "HTTP_DATA_PACKET"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size() + 2 + self.data.len()
+    }
+}
+
+impl<'a> Decode<'a> for DataPkt<'a> {
+    fn decode(src: &mut ReadCursor<'a>) -> ironrdp_core::DecodeResult<Self> {
+        ensure_size!(in: src, size: 2);
+        let len = usize::from(src.read_u16());
+        ensure_size!(in: src, size: len);
+        Ok(DataPkt {
+            data: src.read_slice(len),
+        })
+    }
+}
+
+pub(crate) struct KeepalivePkt;
+
+impl Encode for KeepalivePkt {
+    fn encode(&self, dst: &mut WriteCursor<'_>) -> ironrdp_core::EncodeResult<()> {
+        let hdr = PktHdr {
+            ty: PktTy::Keepalive,
+            length: u32::try_from(self.size()).expect("keepalive packet size fits in u32"),
+            ..PktHdr::default()
+        };
+        hdr.encode(dst)
+    }
+
+    fn name(&self) -> &'static str {
+        "KEEPALIVE"
+    }
+
+    fn size(&self) -> usize {
+        PktHdr::default().size()
+    }
+}