Registry /
auth-security / backports-ssl-match-hostname
Install & Compatibility
Where this runs
tested against v3.7.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.030s · 19.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.026s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
match_hostname
✓ from backports.ssl_match_hostname import match_hostname
✗ from ssl import match_hostname
On older Python versions where this backport is needed, directly importing from `ssl` would result in an ImportError or an older/buggy implementation. The backport specifically provides the newer logic.
CertificateError
✓ from backports.ssl_match_hostname import CertificateError
✗ from ssl import CertificateError
Similar to `match_hostname`, the `CertificateError` exception class for hostname verification issues is provided by the backport for consistency and error handling.
This quickstart demonstrates the core usage of `match_hostname()` within a simulated SSL context. In a real-world scenario, you would obtain the peer certificate from an active `sslsock` object after establishing an SSL/TLS connection. It's crucial to handle `CertificateError` to manage hostname mismatches securely.
import socket
import ssl
from backports.ssl_match_hostname import match_hostname, CertificateError
def verify_ssl_hostname(hostname: str, port: int):
try:
# Simulate a socket connection (replace with actual connection in real use)
# For demonstration, we'll create a dummy context and peer certificate
context = ssl.create_default_context()
with socket.create_connection((hostname, port)) as sock:
with context.wrap_socket(sock, server_hostname=hostname) as sslsock:
cert = sslsock.getpeercert()
match_hostname(cert, hostname)
print(f"Hostname '{hostname}' successfully matched certificate.")
except CertificateError as e:
print(f"Certificate hostname mismatch for '{hostname}': {e}")
except Exception as e:
print(f"An error occurred: {e}")
# Example Usage (replace with a real hostname and port for actual testing)
# For a live example, you'd connect to a server with SSL.
# Using a dummy here for runnable example without actual network call or certs.
# To make it runnable for demonstration, let's just show the logic structure.
# This part is illustrative, assumes you have a 'cert' object from a real ssl connection
# For an actual runnable quickstart with mock, it's complex.
# The essence is `match_hostname(sslsock.getpeercert(), hostname)`
# For a truly runnable example (requires a running SSL server at specified host/port)
# try:
# hostname = "www.google.com"
# port = 443
# context = ssl.create_default_context()
# with socket.create_connection((hostname, port)) as sock:
# with context.wrap_socket(sock, server_hostname=hostname) as sslsock:
# cert = sslsock.getpeercert()
# match_hostname(cert, hostname)
# print(f"Hostname '{hostname}' successfully matched certificate.")
# except CertificateError as e:
# print(f"Certificate hostname mismatch for '{hostname}': {e}")
# except Exception as e:
# print(f"An error occurred: {e}")
print("Consult the documentation for actual socket setup as this is a backport.")
Debug
Known issues
deprecatedThe `backports-ssl-match-hostname` library is a backport for older Python versions and is not actively maintained. For Python 3.2 and newer, the `ssl.match_hostname()` function is included in the standard library. For Python 3.7+, the implementation includes further updates (e.g., RFC 6125 compliance, IP address handling).fixUpgrade to a modern, supported Python version (3.7+) and use the built-in `ssl.match_hostname()` directly. If an older Python version is strictly required, ensure you understand the maintenance status and potential security implications.
affects: < 3.2
breakingSecurity vulnerabilities (CVEs) related to SSL hostname matching have been discovered and patched in the upstream Python `ssl` module (e.g., RFC 6125 compliance, wildcard matching denial-of-service). An unmaintained backport might not receive these critical security updates, leaving applications vulnerable.fixPrioritize upgrading Python to a version where `ssl.match_hostname()` is actively maintained and patched by the Python core team. If using the backport on older systems, regularly review Python's upstream security advisories for `ssl.match_hostname` and evaluate if the backport has integrated the fixes.
affects: All versions of the backport if not manually updated to reflect upstream patches.
gotchaWhen using `backports-ssl-match-hostname` on Python versions that *do* have a built-in `ssl.match_hostname`, care must be taken to ensure the backport's version is used if that's the intention (e.g., for specific behavior). However, generally, the built-in version should be preferred if available and up-to-date.fixAlways import from `backports.ssl_match_hostname` when specifically targeting the backport. For modern Python, remove the backport dependency and import from `ssl` directly. Be aware of import order and path if both are present.
affects: Python >= 3.2 (where `ssl.match_hostname` was introduced).
Errors
Common errors & fixes
ImportError: No module named backports.ssl_match_hostname
This error occurs when a Python application, often an older one or one with specific dependencies like `docker` or `SaltStack`, attempts to import `backports.ssl_match_hostname` but the package is not installed in the active Python environment or is not accessible.
fixInstall the package using pip: `pip install backports.ssl-match-hostname` or, if using a system package manager (like on Ubuntu or Fedora for Python 2), install it via `sudo apt-get install python-backports.ssl-match-hostname` or `sudo dnf install python2-backports-ssl_match_hostname` respectively.
ModuleNotFoundError: No module named 'backports'
Similar to `ImportError`, this indicates that the `backports` namespace package, which `backports.ssl_match_hostname` resides in, cannot be found by the Python interpreter. This often happens in environments like Docker containers or specific Linux distributions where the package might be missing or installed incorrectly for the Python version being used.
fixEnsure the package is installed using pip: `pip install backports.ssl-match-hostname`. If using Python 3 and encountering this with an older application, verify the correct Python interpreter and its site-packages are being used. For system-wide installations, consider `sudo apt-get install python3-backports.ssl-match-hostname` if available for your distribution, or ensure the virtual environment is correctly activated.
backports.ssl_match_hostname.CertificateError: hostname 'example.com' doesn't match 'www.example.com'
This error signals that the hostname provided for verification does not match any of the hostnames listed in the SSL/TLS certificate presented by the server. This is a security feature to prevent man-in-the-middle attacks, and it occurs when there's a mismatch between the requested hostname and the certificate's subject or Subject Alternative Names (SANs).
fixEnsure the hostname used in your connection attempt exactly matches a Common Name (CN) or a Subject Alternative Name (SAN) in the server's SSL certificate. If you are the certificate owner, consider regenerating the certificate to include all necessary hostnames (e.g., both `example.com` and `www.example.com`) in the SAN field. If the mismatch is expected in a test environment, you might temporarily disable hostname verification (e.g., `check_hostname=False` in `SSLContext`), but this is not recommended for production.
ssl.match_hostname() is deprecated since Python 3.7
While not an error *from* the `backports-ssl-match-hostname` library itself, developers often encounter this message when their code (or a dependency) is still relying on the `ssl.match_hostname` function (or its backport) in Python versions 3.7 and later. In newer Python versions, hostname matching for TLS connections is handled directly by OpenSSL, making the Python `ssl.match_hostname` function redundant and eventually removed.
fixFor Python 3.7 and newer, avoid using `backports-ssl-match-hostname` or direct calls to `ssl.match_hostname()`. Instead, rely on the standard `ssl` module's default behavior for hostname verification, which uses OpenSSL's capabilities. If an application explicitly uses the backport, it may indicate it's designed for older Python versions and might need an update to align with modern Python's SSL handling practices.
Upgrade
Version history
3.7.0.1latest on PyPI · released Jan 12, 2019
Audit
Dependencies
sslrequiredRequired for Python versions earlier than 2.6, where the 'ssl' module was not in the standard library. For 2.6+, 'ssl' is built-in.
ipaddressoptionalRequired for proper handling of IP addresses in ServerAltName fields, aligning with Python 3.5's capabilities, if not provided by the target Python version.