Summary

Add support for matching certificate hostnames and IPs.

Review Request #15017 — Created April 16, 2026 and submitted April 27, 2026, 10:30 p.m.

Information

Owner

chipx86

Repository

Review Board

Branch

release-7.1.x

Bugs

Depends On

~~15016~~

Reviewers

Groups

reviewboard

People

Description

This introduces Certificate.matches_host(), which takes a hostname or
IPv4/IPv6 address and matches it against the Subject and SAN values
stored in the certificate. This supports hostnames, IPv4 addresses, and
IPv6 addresses.

matches_host() starts by determining if this is an IP address or a
hostname, and then performs only the checks needed for that type.

For IP checks, comparisons between instances are performed.

For hostname checks, matches_host() wraps a new utility function,
get_cert_hostname_matches(), which can be used without a Certificate
instance. This supports bare hostnames, hostnames with multiple labels,
and wildcard patterns.

Wildcard matching takes care to only match the first label in a hostname
(such as *.example.com) and to avoid matching bare hostnames. It does
not support partial wildcards, such as foo*, *bar, or foo*bar, as
these are largely unsupported by browsers, servers, and Certificate
Authorities these days (Chrome treats them as a security issue).

Certificate.subject_alternative_names has been updated to return
ipaddress.* instances for IP address/network values and strings for
hostnames. This allows match_host() (and other callers) to handle each
entry correctly.

Testing Done

Unit tests pass.

Commits

Summary	ID
Add support for matching certificate hostnames and IPs. This introduces `Certificate.matches_host()`, which takes a hostname or IPv4/IPv6 address and matches it against the Subject and SAN values stored in the certificate. This supports hostnames, IPv4 addresses, and IPv6 addresses. `matches_host()` starts by determining if this is an IP address or a hostname, and then performs only the checks needed for that type. For IP checks, comparisons between instances are performed. For hostname checks, `matches_host()` wraps a new utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. This supports bare hostnames, hostnames with multiple labels, and wildcard patterns. Wildcard matching takes care to only match the first label in a hostname (such as `.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo`, `bar`, or `foobar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue). `Certificate.subject_alternative_names` has been updated to return `ipaddress.*` instances for IP address/network values and strings for hostnames. This allows `match_host()` (and other callers) to handle each entry correctly.	cce7da0183927547aa7733a36ddaee6e39f97245

Summary

Add support for matching certificate hostnames and IPs.

This introduces `Certificate.matches_host()`, which takes a hostname or IPv4/IPv6 address and matches it against the Subject and SAN values stored in the certificate. This supports hostnames, IPv4 addresses, and IPv6 addresses. `matches_host()` starts by determining if this is an IP address or a hostname, and then performs only the checks needed for that type. For IP checks, comparisons between instances are performed. For hostname checks, `matches_host()` wraps a new utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. This supports bare hostnames, hostnames with multiple labels, and wildcard patterns. Wildcard matching takes care to only match the first label in a hostname (such as `*.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo*`, `*bar`, or `foo*bar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue). `Certificate.subject_alternative_names` has been updated to return `ipaddress.*` instances for IP address/network values and strings for hostnames. This allows `match_host()` (and other callers) to handle each entry correctly.

cce7da0183927547aa7733a36ddaee6e39f97245

Issues

Description	From	Last Updated
Can we add some additional tests? Certificate with cert_data (exercising the subject path) Test to verify rejection of partial wildcards …	david	April 27, 2026, 10:07 p.m.
self.subject can be None Based on the implementation of the tests (and the docstring), it looks like maybe you had …	david	April 20, 2026, 8:49 a.m.
SAN can contain IP addresses. While the wildcard logic in get_cert_hostname_matches works incidentally for that, it might be nice to …	david	April 20, 2026, 9:26 a.m.
Typo: futher -> further	david	April 20, 2026, 9:02 a.m.
Can we add a debug log in case this fails because of a partial wildcard?	david	April 21, 2026, 2:41 p.m.
This is no longer just string values.	david	April 27, 2026, 10:07 p.m.
This stray line got left over from a previous iteration.	david	April 27, 2026, 10:07 p.m.

flake8 passed.

JSHint passed.

Change Summary:

Hostname matching now uses the Subject instead of the caller-provided hostname.

Commits:

	Summary	ID
	Add support for matching certificate hostnames. This introduces `Certificate.matches_hostname()`, which takes a hostname and matches it against the hostnames and/or wildcard hostnames stored in the certificate (as both the primary hostname and in the SAN fields). It wraps a utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. Wildcard matching takes care to only match the first label in a hostname (such as `.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo`, `bar`, or `foobar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue).	2cde0d4733368274e342a5aa748efe875ff6d72b
	Add support for matching certificate hostnames. This introduces `Certificate.matches_hostname()`, which takes a hostname and matches it against the hostnames and/or wildcard hostnames stored in the certificate (as both the primary hostname and in the SAN fields). It wraps a utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. Wildcard matching takes care to only match the first label in a hostname (such as `.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo`, `bar`, or `foobar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue).	8db5a6fef00d888a815fe6768ea804686cdff372

Diff:

Revision 2 (+480)

Show changes

	docs/manual/extending/coderef/index.rst
	reviewboard/certs/cert.py
	reviewboard/certs/utils.py
	reviewboard/certs/tests/test_certificate.py
	reviewboard/certs/tests/test_utils.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

The issue has been resolved. Show all issues

Can we add some additional tests?

Certificate with cert_data (exercising the subject path)
Test to verify rejection of partial wildcards
IPv4 and IPv6 address in SAN entries
Bare cert hostname (like "localhost")

reviewboard/certs/cert.py (Diff revision 2)

The issue has been resolved. Show all issues

self.subject can be None

Based on the implementation of the tests (and the docstring), it looks like maybe you had this as self.hostname initially?

The tests are constructing the cert without cert_data (therefore without a subject), so I would expect this to raise if you ran them.

reviewboard/certs/cert.py (Diff revision 2)

The issue has been dropped. Show all issues

SAN can contain IP addresses. While the wildcard logic in get_cert_hostname_matches works incidentally for that, it might be nice to detect these and force a direct comparison instead.

chipx86

April 20, 2026, 9:26 a.m.

IP addresses in SAN don't support wildcards, so in practice we'll never get one with a wildcard. It will always be a direct comparison with any real-world cert.
Also worth noting, IP addresses in SAN entries only ever support public IPs, not private. They'll probably rarely be used.

reviewboard/certs/utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Typo: futher -> further
```

reviewboard/certs/utils.py (Diff revision 2)

The issue has been dropped. Show all issues

Can we add a debug log in case this fails because of a partial wildcard?

chipx86

April 20, 2026, 9:26 a.m.

This will yield spurious debug logs for a lot of certificates. For example, a cert with main.example.com, *.eng.example.com, *.eng.example.net, *.eng.example.org is going to debug log twice for a ci.eng.example.org during comparison, every time. I'm not sure this is where we'd want to be logging anything.

david

April 21, 2026, 2:41 p.m.
```
Sure.
```

Change Summary:


subject_alternative_names now returns strings for hostnames and ipaddress.* instances for IPs.
matches_hostname() has been renamed to match_host(), and supports IPv4/IPv6 address checks.
Hostname checks now handle a lack of a Subject Common Name.
Added normalize_cert_hostname(), which takes a valid hostname value and normalizes it for comparison/storage. (Note: I want to avoid things like whitespace checks here, as cert data should be valid or treated as a bad match, and user input should be explicitly validated elsewhere.)
Added more unit tests for testing with the various SAN value types, and testing against SSL cert data.
Fixed a typo in docs.

Summary:

Add support for matching certificate hostnames.

Add support for matching certificate hostnames and IPs.

Description:

~		This introduces `Certificate.matches_hostname()`, which takes a hostname
~		and matches it against the hostnames and/or wildcard hostnames stored in
~		the certificate (as both the primary hostname and in the SAN fields).
	~	This introduces `Certificate.matches_host()`, which takes a hostname or
	~	IPv4/IPv6 address and matches it against the Subject and SAN values
	~	stored in the certificate. This supports hostnames, IPv4 addresses, and
	+	IPv6 addresses.

~		It wraps a utility function, `get_cert_hostname_matches()`, which can be
~		used without a `Certificate` instance.
	~	`matches_host()` starts by determining if this is an IP address or a
	~	hostname, and then performs only the checks needed for that type.
	+
	+	For IP checks, comparisons between instances are performed.
	+
	+	For hostname checks, `matches_host()` wraps a new utility function,
	+	`get_cert_hostname_matches()`, which can be used without a `Certificate`
	+	instance. This supports bare hostnames, hostnames with multiple labels,
	+	and wildcard patterns.

		Wildcard matching takes care to only match the first label in a hostname
		(such as `*.example.com`) and to avoid matching bare hostnames. It does
		not support partial wildcards, such as `foo`, `bar`, or `foo*bar`, as
		these are largely unsupported by browsers, servers, and Certificate
		Authorities these days (Chrome treats them as a security issue).
	+
	+	`Certificate.subject_alternative_names` has been updated to return
	+	`ipaddress.*` instances for IP address/network values and strings for
	+	hostnames. This allows `match_host()` (and other callers) to handle each
	+	entry correctly.

Commits:

	Summary	ID
	Add support for matching certificate hostnames. This introduces `Certificate.matches_hostname()`, which takes a hostname and matches it against the hostnames and/or wildcard hostnames stored in the certificate (as both the primary hostname and in the SAN fields). It wraps a utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. Wildcard matching takes care to only match the first label in a hostname (such as `.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo`, `bar`, or `foobar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue).	8db5a6fef00d888a815fe6768ea804686cdff372
	Add support for matching certificate hostnames and IPs. This introduces `Certificate.matches_host()`, which takes a hostname or IPv4/IPv6 address and matches it against the Subject and SAN values stored in the certificate. This supports hostnames, IPv4 addresses, and IPv6 addresses. `matches_host()` starts by determining if this is an IP address or a hostname, and then performs only the checks needed for that type. For IP checks, comparisons between instances are performed. For hostname checks, `matches_host()` wraps a new utility function, `get_cert_hostname_matches()`, which can be used without a `Certificate` instance. This supports bare hostnames, hostnames with multiple labels, and wildcard patterns. Wildcard matching takes care to only match the first label in a hostname (such as `.example.com`) and to avoid matching bare hostnames. It does not support partial wildcards, such as `foo`, `bar`, or `foobar`, as these are largely unsupported by browsers, servers, and Certificate Authorities these days (Chrome treats them as a security issue). `Certificate.subject_alternative_names` has been updated to return `ipaddress.*` instances for IP address/network values and strings for hostnames. This allows `match_host()` (and other callers) to handle each entry correctly.	cce7da0183927547aa7733a36ddaee6e39f97245

Diff:

Revision 3 (+842 -14)

Show changes

	docs/manual/extending/coderef/index.rst
	reviewboard/certs/cert.py
	reviewboard/certs/utils.py
	reviewboard/certs/tests/test_certificate.py
	reviewboard/certs/tests/test_utils.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

reviewboard/certs/cert.py (Diff revision 3)
The issue has been resolved. Show all issues
```
This is no longer just string values.
```
reviewboard/certs/cert.py (Diff revision 3)
The issue has been resolved. Show all issues
```
This stray line got left over from a previous iteration.
```

Status:: Completed
Change Summary:: Pushed to release-8.x (a2fd011)