Skip to content

Hostname Validator

certmonitor.validators.hostname.HostnameValidator

Bases: BaseCertValidator

A validator for checking the hostname in an SSL certificate.

Attributes:

Name Type Description
name str

The name of the validator.

name class-attribute instance-attribute 

name: str = 'hostname'

validate 

validate(cert: Dict[str, Any], host: str, port: int) -> Dict[str, Any]

Validates the hostname against the Subject Alternative Names (SANs) and Common Name (CN) in the provided SSL certificate.

Parameters:

Name Type Description Default
cert dict

The SSL certificate.

 required
host str

The hostname to validate.

 required
port int

The port number.

 required

Returns:

Name Type Description
dict Dict[str, Any]

A dictionary containing the validation results, including whether the hostname is valid, the reason for validation failure, and the alternative names (SANs) in the certificate.

Examples:

Example output (success): This example shows a certificate where the hostname matches one of the DNS SANs, so validation passes and the matched name is shown.

{
    "is_valid": true,
    "matched_name": "example.com",
    "alt_names": [
        "example.com",
        "www.example.com"
    ]
}

Example output (failure): This example shows a certificate where the hostname does not match any DNS SAN or common name, so validation fails and a reason is provided.

{
    "is_valid": false,
    "reason": "Hostname test.example.com doesn't match any of the certificate's subject alternative names or common name",
    "alt_names": [
        "example.com",
        "www.example.com"
    ]
}
Source code in certmonitor/validators/hostname.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def validate(self, cert: Dict[str, Any], host: str, port: int) -> Dict[str, Any]:
    """
    Validates the hostname against the Subject Alternative Names (SANs) and Common Name (CN) in the provided SSL certificate.

    Args:
        cert (dict): The SSL certificate.
        host (str): The hostname to validate.
        port (int): The port number.

    Returns:
        dict: A dictionary containing the validation results, including whether the hostname is valid,
              the reason for validation failure, and the alternative names (SANs) in the certificate.

    Examples:
        Example output (success):
            This example shows a certificate where the hostname matches one of the DNS SANs, so validation passes and the matched name is shown.

            {
                "is_valid": true,
                "matched_name": "example.com",
                "alt_names": [
                    "example.com",
                    "www.example.com"
                ]
            }

        Example output (failure):
            This example shows a certificate where the hostname does not match any DNS SAN or common name, so validation fails and a reason is provided.

            {
                "is_valid": false,
                "reason": "Hostname test.example.com doesn't match any of the certificate's subject alternative names or common name",
                "alt_names": [
                    "example.com",
                    "www.example.com"
                ]
            }
    """
    common_name = self._get_common_name(cert["cert_info"])
    if common_name and self._matches_hostname(host, [common_name]):
        return {"is_valid": True, "matched_name": common_name, "alt_names": []}

    if "subjectAltName" not in cert["cert_info"]:
        return {
            "is_valid": False,
            "reason": "Certificate does not contain a Subject Alternative Name extension",
        }

    sans = cert["cert_info"]["subjectAltName"]

    # Ensure sans is a list of DNS names
    if isinstance(sans, dict):
        dns_names = sans.get("DNS", [])
        if isinstance(dns_names, str):
            dns_names = [dns_names]
    else:
        dns_names = [item[1] for item in sans if item[0] == "DNS"]

    if not dns_names:
        return {
            "is_valid": False,
            "reason": "Certificate does not contain any DNS SANs",
            "alt_names": [],
        }

    # Check if the hostname matches any of the DNS names
    if self._matches_hostname(host, dns_names):
        return {"is_valid": True, "matched_name": host, "alt_names": dns_names}

    # If no match found, check for wildcard certificates
    for name in dns_names:
        if self._matches_wildcard(host, name):
            return {"is_valid": True, "matched_name": name, "alt_names": dns_names}

    return {
        "is_valid": False,
        "reason": f"Hostname {host} doesn't match any of the certificate's subject alternative names or common name",
        "alt_names": dns_names,
    }