backports-ssl-match-hostname

3.7.0.1 · deprecated · verified Tue Apr 14

This library provides a backport of the `ssl.match_hostname()` function from Python 3.5 to earlier Python versions. It ensures proper hostname verification against SSL/TLS certificates, a critical security measure. The current version is 3.7.0.1, released in 2019. The project is considered unmaintained, as its functionality is now present in standard Python versions.

Warnings

deprecated The `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).
Fix: Upgrade 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.
breaking Security 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.
Fix: Prioritize 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.
gotcha When 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.
Fix: Always 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.

Install

pip install backports-ssl-match-hostname Install stable version

Imports

match_hostname
```
from backports.ssl_match_hostname 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
```
Similar to `match_hostname`, the `CertificateError` exception class for hostname verification issues is provided by the backport for consistency and error handling.

Quickstart

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.")

view raw JSON →