X509Certificate2.MatchesHostname(String, Boolean, Boolean) Method

Definition

Namespace:

System.Security.Cryptography.X509Certificates

Assembly:

System.Security.Cryptography.dll

Source:

X509Certificate2.cs

Checks to see if the certificate matches the provided host name.

public bool MatchesHostname (string hostname, bool allowWildcards = true, bool allowCommonName = true);

member this.MatchesHostname : string * bool * bool -> bool

Public Function MatchesHostname (hostname As String, Optional allowWildcards As Boolean = true, Optional allowCommonName As Boolean = true) As Boolean

Parameters

hostname

String

The host name to match against.

allowWildcards

Boolean

true to allow wildcard matching for dNSName values in the Subject Alternative Name extension; otherwise, false.

allowCommonName

Boolean

true to allow matching against the subject Common Name value; otherwise, false.

Returns

Boolean

true if the certificate is a match for the requested hostname; otherwise, false

Exceptions

ArgumentException

The hostname parameter is not a valid DNS hostname or IP address.

CryptographicException

The certificate contains multiple Subject Alternative Name extensions.

-or-

The Subject Alternative Name extension or Subject Name could not be decoded.

Remarks

This method is a platform neutral implementation of IETF RFC 6125 host matching logic. The SslStream class uses the host name validator from the operating system, which may result in different values from this implementation.

The logical flow of this method is:

• If the hostname parses as an IPAddress then IPAddress matching is done; otherwise, DNS Name matching is done.
• For IPAddress matching, the value must be an exact match against an iPAddress value in an entry of the Subject Alternative Name extension.
• For DNS Name matching, the value must be an exact match against a dNSName value in an entry of the Subject Alternative Name extension, or a wildcard match against the same.
• For wildcard matching, the wildcard must be the first character in the dNSName entry, the second character must be a period (.), and the entry must have a length greater than two.
  The wildcard will only match the hostname value up to the first period (.), remaining characters must be an exact match.
• If there is no Subject Alternative Name extension, or the extension does not have any entries of the appropriate type, then Common Name matching is used as a fallback.
• For Common Name matching, if the Subject Name contains a single Common Name, and that attribute is not defined as part of a multi-valued Relative Distinguished Name, then the hostname is matched against the Common Name attribute's value.
  Note that wildcards are not used in Common Name matching.

This implementation considers SRV-ID values or URI-ID values as out-of-scope, and will not use their presence as a reason to stop the fallback from DNS-ID matching to the CN-ID.

This method does not convert non-ASCII hostnames to the IDNA representation. For Unicode domains, the caller must make use of IdnMapping or an equivalent IDNA mapper.

The "exact" matches performed by this routine are OrdinalIgnoreCase, as domain names are not case-sensitive.

This method does not determine if the hostname is authorized by a trusted authority. A trust decision cannot be made without additionally checking for trust via X509Chain.

This method does not check that the certificate has an id-kp-serverAuth (1.3.6.1.5.5.7.3.1) extended key usage.