feat: TLS certificates by trust on first use #74

Merged
christianmanivong merged 4 commits from feat/tls-fingerprint-tofu into main 2026-11-01 23:21:04 +00:00
Owner

New module napalm_device_types/tls_certificates.py, the HTTPS counterpart of ssh_host_keys: trust on first use by certificate fingerprint.

  • In: optional_args["tls_fingerprints"] = {"443": "SHA256:AB:CD:…"} (SHA-256 of the DER certificate; prefix, colons, spaces and case optional on input).
  • Out: optional_args["tls_certificate_observer"] receives {host, port, seen: {fingerprint}, expected: {fingerprint} | None, accepted}; a failing observer is logged, not raised.
  • CertificateCheck: verify_server(timeout) (own stdlib-ssl handshake, no CA/hostname check), pin(session) (requests adapter with urllib3 assert_fingerprint, so every later connection must present the checked certificate), refusing() (maps urllib3's mismatch to TlsCertificateMismatch), observe().
  • TlsCertificateMismatch(ConnectionException) names both fingerprints.
  • requests>=2.25.0 is now a declared dependency.

Why: NAPALM/napalm-hpe-aruba-procurve#17 — the REST transport never verified the switch's (self-signed) certificate in practice. Decision: pin by fingerprint on first use, like SSH host keys.

Tested: tests/test_tls_certificates.py (real TLS over a socket pair with a generated self-signed certificate; failed first). pytest 1069 passed, coverage 99 % on the module, ruff, mypy strict, napalm-standard check/ratchet green. CHANGELOG [Unreleased] → Added (MINOR).

Merge order: this → release → napalm-hpe-aruba-procurve fix/rest-cert-tofu-17 (floor) → netOrk fix/rest-cert-tofu (pins; netOrk imports tls_certificates at module level).

New module `napalm_device_types/tls_certificates.py`, the HTTPS counterpart of `ssh_host_keys`: trust on first use by certificate fingerprint. - **In:** `optional_args["tls_fingerprints"]` = `{"443": "SHA256:AB:CD:…"}` (SHA-256 of the DER certificate; prefix, colons, spaces and case optional on input). - **Out:** `optional_args["tls_certificate_observer"]` receives `{host, port, seen: {fingerprint}, expected: {fingerprint} | None, accepted}`; a failing observer is logged, not raised. - `CertificateCheck`: `verify_server(timeout)` (own stdlib-ssl handshake, no CA/hostname check), `pin(session)` (requests adapter with urllib3 `assert_fingerprint`, so every later connection must present the checked certificate), `refusing()` (maps urllib3's mismatch to `TlsCertificateMismatch`), `observe()`. - `TlsCertificateMismatch(ConnectionException)` names both fingerprints. - `requests>=2.25.0` is now a declared dependency. Why: NAPALM/napalm-hpe-aruba-procurve#17 — the REST transport never verified the switch's (self-signed) certificate in practice. Decision: pin by fingerprint on first use, like SSH host keys. Tested: `tests/test_tls_certificates.py` (real TLS over a socket pair with a generated self-signed certificate; failed first). pytest 1069 passed, coverage 99 % on the module, ruff, mypy strict, `napalm-standard check`/`ratchet` green. CHANGELOG [Unreleased] → Added (MINOR). Merge order: this → release → napalm-hpe-aruba-procurve `fix/rest-cert-tofu-17` (floor) → netOrk `fix/rest-cert-tofu` (pins; netOrk imports `tls_certificates` at module level).
christianmanivong added 1 commit 2026-11-01 21:55:58 +00:00
feat: TLS certificates by trust on first use
driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 20s
driver / types (pull_request) Failing after 1m10s
driver / test (3.12) (pull_request) Successful in 1m14s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / lowest (pull_request) Successful in 38s
driver / build (pull_request) Successful in 34s
driver / security (pull_request) Successful in 1m13s
CI / driver (pull_request) Failing after 3m4s
driver / publish (pull_request) Skipped
46c1c9dc4e
Devices ship self-signed certificates, so a driver either fails the CA
check on every one of them or turns verification off and sends the
login to whatever answers on the address. tls_certificates pins the
certificate by its SHA-256 fingerprint instead, shaped like
ssh_host_keys: the caller passes the fingerprint to expect by port
(optional_args["tls_fingerprints"]), the driver refuses any other
certificate before a request carries credentials, and every certificate
seen goes to optional_args["tls_certificate_observer"]. Without a
fingerprint the first certificate is accepted.

CertificateCheck checks the certificate in a handshake of its own, then
pins a requests session to it (urllib3's assert_fingerprint, direct and
through a proxy), so no other host can step in between the check and
the login.

Refs NAPALM/napalm-hpe-aruba-procurve#17
christianmanivong added 2 commits 2026-11-01 23:06:54 +00:00
# Conflicts:
#	CHANGELOG.md
Merge remote-tracking branch 'origin/main' into feat/tls-fingerprint-tofu
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 15s
driver / test (3.13) (pull_request) Successful in 1m14s
driver / types (pull_request) Failing after 1m35s
driver / test (3.12) (pull_request) Successful in 1m27s
driver / lowest (pull_request) Successful in 34s
driver / build (pull_request) Successful in 28s
driver / security (pull_request) Successful in 59s
CI / driver (pull_request) Failing after 2m34s
driver / publish (pull_request) Skipped
516fb18c0e
# Conflicts:
#	CHANGELOG.md
christianmanivong added 1 commit 2026-11-01 23:16:02 +00:00
fix(types): the adapter's ignore holds with and without requests' stubs
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 15s
driver / types (pull_request) Successful in 57s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m10s
driver / lowest (pull_request) Successful in 30s
driver / build (pull_request) Successful in 26s
driver / security (pull_request) Successful in 53s
CI / driver (pull_request) Successful in 2m12s
driver / publish (pull_request) Skipped
63039ce758
CI installs types-requests, so HTTPAdapter is typed there and the
ignore for subclassing an untyped base is unused; locally it is needed.
christianmanivong merged commit 02d461036b into main 2026-11-01 23:21:04 +00:00
christianmanivong deleted branch feat/tls-fingerprint-tofu 2026-11-01 23:21:04 +00:00
Sign in to join this conversation.