PATTERN Cited by 1 source

SSH certificate extension smuggling

Use an existing protocol's extension field to carry orthogonal data, so the new capability ships without any changes to the protocol, the client binary, or the server binary. The protocol doesn't know about the new meaning; the extension field just transports opaque bytes; only the endpoints that care inspect the extension.

Canonical instance: OPKSSH

SSH's public-key format supports SSH certificates, which are signed public keys with structured additional data including an extension field (PROTOCOL.certkeys) that permits arbitrary key-value pairs. OPKSSH packs a PK Token (an OIDC ID Token committing to the user's public key) into this extension field. The SSH client transmits the certificate normally; the SSH server receives it normally; the only change is that the server's AuthorizedKeysCommand hook — OpenSSH's external-program-for-key-validation interface — is pointed at the OpenPubkey verifier instead of checking authorized_keys.

Result: zero changes to the SSH client or server binary; two-line change to sshd_config; full end-to-end OIDC-SSO SSH.

Why this shape works

1. The extension field is already in the wire format. It's not a protocol version bump. Old clients/servers that don't care about the extension simply ignore it; new endpoints that care inspect it.
2. No MITM / middle-box compatibility work. Bastions, jump hosts, and SSH proxies don't have to know about the extension — they forward certificates byte-for-byte.
3. No binary updates for the typical install base. OPKSSH users can SSH from anywhere with a standard OpenSSH client version from the past decade (SSH certificates have been a standard feature since OpenSSH 5.4, 2010).
4. The extension field is exactly what it's for. Protocol designers built extension fields in anticipation of this shape. OPKSSH isn't smuggling data through a bug or a hidden seam — it's using a documented escape hatch.

Prerequisites for the pattern to apply

• The protocol must have an extension field (or extensibility seam — TLS extensions, HTTP headers, gRPC metadata, DNS TXT records, OIDC custom claims).
• The extension must allow opaque data of sufficient size (PK Tokens are kilobyte-scale, well within SSH-certificate extension limits).
• There must be a hook on the consuming endpoint to run endpoint-specific logic against the extension content — OpenSSH's AuthorizedKeysCommand is load-bearing here.

Related patterns (same family)

• patterns/protocol-algorithm-negotiation — also adds crypto-agility without flag days, but via algorithm advertisement rather than extension smuggling. Combines orthogonally with this pattern (cf. systems/openssh's use of both).
• patterns/protocol-compatible-drop-in-proxy — a structural variant: instead of smuggling new data into an existing protocol's extension field, speak the protocol byte-for-byte while running different logic behind it. Both preserve wire compatibility; this pattern preserves binary compatibility on both sides, while the drop-in proxy preserves client-binary compatibility only.

Not the same as

• Protocol tunneling (e.g. SSH over HTTP CONNECT): the outer protocol doesn't know the inner protocol exists, and the inner protocol is fully self-contained. Extension smuggling uses a single protocol that natively carries the extension data; no tunnel.
• Out-of-band channels (e.g. SAML assertion carried in a separate HTTP POST): extension smuggling rides in the same protocol session, not a parallel one.

Seen in

• sources/2025-03-25-cloudflare-opkssh-open-sourcing — OPKSSH packages the PK Token into an SSH certificate extension field; the SSH server's AuthorizedKeysCommand is pointed at the OpenPubkey verifier, which parses the extension and validates identity + key binding.