CertificatePinner class

Public-key / certificate pinning for dart:io connections.

Pins are SHA-256 digests in any of these spellings:

  • sha256/<base64> (HPKP style) or bare base64 / base64url
  • 64 hex characters, optionally separated by :

Hosts are matched case-insensitively. *.example.com matches exactly one extra label (api.example.com), never the apex and never deeper names.

Normal TLS validation always stays on: a pin can only add a restriction, it never makes an otherwise untrusted certificate acceptable. To talk to a server with a private CA or a self-signed certificate, pass a SecurityContext that trusts it.

dart:io only exposes the leaf certificate of a connection, so pins must be leaf pins (intermediate / root pins cannot be checked).

Constructors

CertificatePinner({required Map<String, List<String>> pins, PinningMode mode = PinningMode.publicKey, bool rejectUnpinnedHosts = false})
Throws ArgumentError if a host is blank, has no pins, or a pin is not a valid SHA-256 digest.

Properties

hashCode → int
The hash code for this object.
no setterinherited
mode → PinningMode
Whether pins are public-key or whole-certificate digests.
final
pinnedHosts → Iterable<String>
Hosts (and wildcard patterns) that have pins configured.
no setter
rejectUnpinnedHosts → bool
When true, connections to hosts without any pin are refused.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

check(String host, X509Certificate? certificate) → void
Throws CertificatePinningException unless certificate satisfies the pins of host.
createHttpClient({SecurityContext? context, Duration? connectionTimeout}) → HttpClient
Returns an HttpClient that refuses every connection whose leaf certificate does not match the pins of the target host.
fingerprint(List<int> der) → String?
Fingerprint of der for this pinner's mode; null if unparsable.
isPinned(String host) → bool
Whether any pin is configured for host.
matches(String host, List<int> der) → bool
Whether the DER certificate satisfies the pins of host.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pinsForHost(String host) → Set<String>
Pins configured for host (canonical base64). Empty when unpinned.
toString() → String
A string representation of this object.
inherited
validateHost(String host, {int port = 443, Duration timeout = const Duration(seconds: 10), SecurityContext? context}) → Future<bool>
Opens a TLS connection to host and reports whether its leaf certificate matches the configured pins.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

certificateFingerprint(List<int> der) → String
Base64 SHA-256 of the whole DER certificate.
extractSpki(List<int> der) → Uint8List?
Extracts the DER-encoded SubjectPublicKeyInfo from a DER-encoded X.509 certificate. Returns null for anything that is not well formed.
normalizeHost(String host) → String
Lower-cases and trims host and drops a trailing root dot.
normalizePin(String pin) → String
Converts any accepted pin spelling into canonical standard base64.
spkiFingerprint(List<int> der) → String?
Base64 SHA-256 of the SubjectPublicKeyInfo of a DER certificate, or null when der is not a parsable X.509 certificate.