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

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
This commit is contained in:
christianmanivong committed 2026-11-01 22:13:20 +01:00
1 parent a809e6c02f
commit 46c1c9dc4e
5 files changed
+605

No files matched your search

+20
View File
@@ -328,6 +328,26 @@ caller's; `ssh_host_keys.HostKeyCheck` is how every SSH driver verifies against
A caller that passes neither key gets first use on every connection, as before; a driver
that ignores both still connects. Old and new versions on either side keep working.
### TLS certificates: trust on first use
The same for a driver's HTTPS API. Devices ship self-signed certificates, so a CA check
fails on all of them and turning verification off trusts whatever answers;
`tls_certificates.CertificateCheck` pins the certificate by its fingerprint instead
(NAPALM/napalm-hpe-aruba-procurve#17). No CA is consulted.
- **In:** `optional_args["tls_fingerprints"]` = `{"443": "SHA256:AB:CD:…"}`, by port: the
SHA-256 of the DER certificate as `openssl x509 -fingerprint -sha256` prints it (prefix,
colons and case optional). With one, any other certificate is refused *before* a request
carries credentials and the connection raises `TlsCertificateMismatch` (a
`ConnectionException` naming both fingerprints). Without one, the first certificate is
accepted. A driver does not fall back to another transport on a mismatch.
- **Out:** `optional_args["tls_certificate_observer"]`, a callable, gets one dict per
connection: `{"host", "port", "seen": {"fingerprint"}, "expected", "accepted"}`.
- **requests:** `check = CertificateCheck(optional_args, host, port)`;
`check.verify_server(timeout)` before the login, `check.pin(session)` so every later
connection of the session must present that certificate, the login inside
`with check.refusing():`, then `check.observe()`.
## Design principle: generic vs. device-specific logic
When adding behavior to a device-type base class, split it along one line: **would