Source code

Revision control

Copy as Markdown

Other Tools

# Threat model
## What this project does and where untrusted input enters
`happy-eyeballs` implements Happy Eyeballs v3 (draft-ietf-happy-happyeyeballs-v3) as a deterministic, sans-I/O state
machine. Firefox uses it to decide which DNS queries to send and which endpoints (address, port, HTTP version, ECH
config) to attempt a connection to. The caller performs all I/O and passes in the current time.
Untrusted input enters through:
- `HappyEyeballs::new`/`new_with_network_config`: the origin host comes from a URL, which web content controls.
- `Input::DnsResult`: A, AAAA and HTTPS records come from the network via the resolver. HTTPS records carry
peer-controlled priorities, target names, ALPN, ports, IP hints and ECH configs, in any number and combination.
- `Input::ConnectionResult`: `EchRetry` carries ECH `retry_configs` sent by the server.
- `NetworkConfig` alt-svc entries, which come from HTTP `Alt-Svc` headers sent by servers.
The application calling the API (Firefox) is trusted; the data above is not, except for the rest of `NetworkConfig`
and the `Instant`s passed in.
## Components that matter most / least
- Most important: `src/lib.rs` and `src/id.rs`, i.e. all of the state machine.
- Out of scope: `tests/`, and the FFI glue in Firefox (`netwerk/`), which is not part of this repository.
- Third-party crates (`url`, `thiserror`, `log`): in scope only where this crate misuses them, or where a bug in them is
reachable with the untrusted input above.
## How to exercise it
- `cargo test --locked` runs the test suite; it is prebuilt in this image.
- `tests/common/` has helpers to drive the state machine through DNS results and connection results with explicit
time, which are the easiest way to write a reproducer as a Rust test.
## How you rate severity
### Critical or high
- Memory safety issues reachable with the untrusted input above.
- ECH downgrade: emitting a connection attempt without ECH, or falling back to the origin, when ECH is enabled and the
HTTPS records carry an ECH config for that service.
- Attaching an ECH config, or the origin's connect name, to an endpoint it does not belong to.
- Attempting a connection that `NetworkConfig` forbids, e.g. an address family excluded by `IpPreference` or an HTTP
version that is disabled.
- A reachable `debug_assert!` that guards one of the properties above. Tests enable debug assertions; Firefox release
builds do not.
### Low
These should still be reported:
- Denial of service: panics, infinite loops, and unbounded memory or CPU use driven by DNS results, ECH retries or
alt-svc entries. A panic without memory corruption is a denial of service, not a memory-safety issue (Mozilla rates
- Reachable `debug_assert!` failures without the consequences above.
- Issues that require the application to misuse the API.
- Deviations from the specification without a security impact.
## Reports
- Include a reproducer, preferably a Rust test using the helpers in `tests/common/`, and the exact commit.
- Proposed patches should be minimal, follow the existing code style, be formatted with `cargo fmt` and pass
`cargo clippy --locked --all-targets -- -D warnings`.