types-backports

from backports.ssl_match_hostname import match_hostname, CertificateError

import backports.ssl_match_hostname

from backports.ssl_match_hostname import match_hostname, CertificateError
import ssl
import socket

# Get peer certificate from SSL connection
sock = ssl.wrap_socket(socket.socket())
sock.connect(('example.com', 443))
cert = sock.getpeercert()

# Verify hostname matches certificate
try:
    match_hostname(cert, 'example.com')
    print("Hostname matches certificate")
except CertificateError as e:
    print(f"Hostname verification failed: {e}")
finally:
    sock.close()

# Advanced usage with certificate inspection
def verify_with_details(hostname, port=443):
    """Verify hostname with detailed certificate information."""
    context = ssl.create_default_context()
    with socket.create_connection((hostname, port)) as sock:
        with context.wrap_socket(sock, server_hostname=hostname) as ssock:
            cert = ssock.getpeercert()
            
            # Extract certificate details
            subject = dict(x[0] for x in cert['subject'])
            common_name = subject.get('commonName', '')
            
            try:
                match_hostname(cert, hostname)
                return True, f"Verified: {common_name}"
            except CertificateError as e:
                return False, f"Failed for {common_name}: {e}"

# Example usage
success, message = verify_with_details('example.com')
print(message)

def match_hostname(cert: _PeerCertRetDictType, hostname: str) -> None:
    """
    Verify that cert (in decoded format as returned by SSLSocket.getpeercert()) 
    matches the given hostname.
    
    Parameters:
    - cert: SSL certificate data structure from SSLSocket.getpeercert()
    - hostname: str, hostname to verify against certificate
    
    Returns:
    None: Function doesn't return a value, raises exception on failure
    
    Raises:
    CertificateError: If hostname doesn't match certificate
    """

class CertificateError(ValueError):
    """
    Exception raised when SSL certificate validation fails during hostname matching.
    
    Inherits from ValueError and is raised by match_hostname when the provided
    certificate does not match the given hostname.
    """

def __getattr__(name: str) -> Incomplete:
    """
    Provides dynamic attribute access for incomplete typing in the backports namespace.
    
    Parameters:
    - name: str, attribute name being accessed
    
    Returns:
    Incomplete: Placeholder type for incomplete typing
    """

from typing import Any, Dict, List, Union

# SSL certificate dictionary structure as returned by SSLSocket.getpeercert()
_PeerCertRetDictType = Dict[str, Union[
    str,                    # Simple string fields like 'serialNumber', 'version'
    List[List[str]],       # Subject/issuer DN components
    List[str]              # subjectAltName entries  
]]

# Placeholder type for incomplete typing from _typeshed
Incomplete = Any