Botan::DNSName Class Reference

#include <dns_name.h>

Public Member Functions
bool	is_wildcard () const
bool	matches_wildcard (std::string_view wildcard) const
const std::string &	name () const
auto	operator<=> (const DNSName &) const =default
bool	operator== (const DNSName &) const =default
const std::string &	to_string () const

Static Public Member Functions
static std::optional< DNSName >	from_san_string (std::string_view name)
static std::optional< DNSName >	from_string (std::string_view name)
static bool	host_wildcard_match (std::string_view issued, std::string_view host)

Detailed Description

A DNS name (host name or wildcard pattern) in canonical form.

Construction validates that the input conforms to the Preferred Name Syntax (RFC 1035 / RFC 1123 LDH labels, length limits, no leading or trailing dot). Entirely numeric names ("1.2.3.4") are rejected. The stored form is lowercased ASCII.

Definition at line 25 of file dns_name.h.

Member Function Documentation

from_san_string()

std::optional< DNSName > Botan::DNSName::from_san_string ( std::string_view name )

static

Like from_string, but additionally accepts the RFC 6125 6.4.3 wildcard form: a single "*" anywhere within the leftmost label of an otherwise-valid DNS name (e.g. "*.example.com", "foo*.example.com"). Shapes that could never produce a match - multiple "*" ("*.*.example.com"), "*" outside the leftmost label ("foo.*.example.com"), or patterns with fewer than three labels ("*", "*.com") - are rejected, as are wildcards embedded within an IDNA A-label ("xn--f*.example.com"). Intended for parsing X.509 SAN dnsName entries.

Definition at line 149 of file dns_name.cpp.

                                                                 {
   if(auto canon = check_and_canonicalize_dns_name(name)) {
      /*
      Validate the wildcard shape: at most one "*", and if present it must be in
      the leftmost label (no "." before it). This matches the RFC 6125 6.4.3
      form that host_wildcard_match accepts and rejects eg "*.*.example.com" or
      "foo.*.example.com"
      */
      const auto first_star = canon->find('*');
      if(first_star != std::string::npos) {
         if(canon->find('*', first_star + 1) != std::string::npos) {
            return std::nullopt;
         }
         const auto first_dot = canon->find('.');
         if(first_dot != std::string::npos && first_dot < first_star) {
            return std::nullopt;
         }
         /*
         RFC 6125 6.4.3: "the client SHOULD NOT attempt to match a presented
         identifier where the wildcard character is embedded within an
         A-label or U-label"
         */
         if(canon->starts_with("xn--")) {
            return std::nullopt;
         }
         // A wildcard match requires at least three labels, so shorter
         // patterns ("*", "*.com") could never match any host
         if(std::count(canon->begin(), canon->end(), '.') < 2) {
            return std::nullopt;
         }
      }
      return DNSName(std::move(*canon));
   } else {
      return {};
   }
}

References name().

Referenced by Botan::AlternativeName::add_dns(), Botan::NameConstraints::is_excluded(), Botan::NameConstraints::is_permitted(), Botan::GeneralName::matches(), and Botan::X509_Certificate::matches_dns_name().

from_string()

std::optional< DNSName > Botan::DNSName::from_string ( std::string_view name )

static

Parse and canonicalize a literal hostname. Returns nullopt if the input is not a valid DNS name per RFC 1035 / 1123, or if it contains a "*" label (use from_san_string for that).

Definition at line 136 of file dns_name.cpp.

                                                             {
   if(auto canon = check_and_canonicalize_dns_name(name)) {
      // TODO(C++23) std::string::contains
      if(canon->find('*') != std::string::npos) {
         return {};
      }
      return DNSName(std::move(*canon));
   } else {
      return {};
   }
}

References name().

Referenced by Botan::URI::Authority::from_string(), Botan::TLS::Server_Name_Indicator::hostname_acceptable_for_sni(), and Botan::X509_Certificate::matches_dns_name().

host_wildcard_match()

bool Botan::DNSName::host_wildcard_match ( std::string_view issued, std::string_view host )

static

Test if the issued name (which might be a wildcard pattern) can match the host, which should be a complete and valid DNS name.

Returns false if either the pattern or the host seem invalid

Definition at line 191 of file dns_name.cpp.

                                                                            {
   if(host.empty() || issued.empty()) {
      return false;
   }
 
   // Maximum valid DNS name
   if(host.size() > 253) {
      return false;
   }
 
   /*
   The wildcard if existing absorbs (host.size() - issued.size() + 1) chars,
   which must be non-negative. So issued cannot possibly exceed host.size() + 1.
   */
   if(issued.size() > host.size() + 1) {
      return false;
   }
 
   /*
   If there are embedded nulls in your issued name
   Well I feel bad for you son
   */
   if(issued.find('\0') != std::string_view::npos || host.find('\0') != std::string_view::npos) {
      return false;
   }
 
   // '*' is not a valid character in DNS names so should not appear on the host side
   if(host.find('*') != std::string_view::npos) {
      return false;
   }
 
   // Similarly a DNS name can't end in .
   if(host.back() == '.') {
      return false;
   }
 
   // Nor can it start with one
   if(host.front() == '.') {
      return false;
   }
 
   // And a host can't have an empty name component, so reject that
   if(host.find("..") != std::string_view::npos) {
      return false;
   }
 
   // ASCII-only case-insensitive char equality, avoids locale overhead from tolower
   auto dns_char_eq = [](char a, char b) -> bool {
      if(a == b) {
         return true;
      }
      const auto la = static_cast<unsigned char>(a | 0x20);
      const auto lb = static_cast<unsigned char>(b | 0x20);
      return la == lb && la >= 'a' && la <= 'z';
   };
 
   auto dns_char_eq_range = [&](std::string_view a, std::string_view b) -> bool {
      if(a.size() != b.size()) {
         return false;
      }
      for(size_t i = 0; i != a.size(); ++i) {
         if(!dns_char_eq(a[i], b[i])) {
            return false;
         }
      }
      return true;
   };
 
   // Exact match: accept
   if(dns_char_eq_range(issued, host)) {
      return true;
   }
 
   // First detect offset of wildcard '*' if included
   const size_t first_star = issued.find('*');
   const bool has_wildcard = (first_star != std::string_view::npos);
 
   // At most one wildcard is allowed
   if(has_wildcard && issued.find('*', first_star + 1) != std::string_view::npos) {
      return false;
   }
 
   // If no * at all then not a wildcard, and so not a match
   if(!has_wildcard) {
      return false;
   }
 
   /*
   RFC 6125 6.4.3: "the client SHOULD NOT attempt to match a presented
   identifier where the wildcard character is embedded within an
   A-label or U-label"
 
   The host side check rejects a partial wildcard absorbing part of an
   A-label of the host, which would otherwise allow the same confusion.
   */
   const auto is_idna_prefixed = [&](std::string_view label) {
      return label.size() >= 4 && dns_char_eq_range(label.substr(0, 4), "xn--");
   };
   const auto issued_label = issued.substr(0, issued.find('.'));
   if(is_idna_prefixed(issued_label)) {
      return false;
   }
   if(issued_label != "*" && is_idna_prefixed(host.substr(0, host.find('.')))) {
      return false;
   }
 
   /*
   Now walk through the issued string, making sure every character
   matches. When we come to the (singular) '*', jump forward in the
   hostname by the corresponding amount. We know exactly how much
   space the wildcard takes because it must be exactly `len(host) -
   len(issued) + 1 chars`.
 
   We also verify that the '*' comes in the leftmost component, and
   doesn't skip over any '.' in the hostname.
   */
   size_t dots_seen = 0;
   size_t host_idx = 0;
 
   for(size_t i = 0; i != issued.size(); ++i) {
      if(issued[i] == '.') {
         dots_seen += 1;
      }
 
      if(issued[i] == '*') {
         // Fail: wildcard can only come in leftmost component
         if(dots_seen > 0) {
            return false;
         }
 
         /*
         Since there is only one * we know the tail of the issued and
         hostname must be an exact match. In this case advance host_idx
         to match.
         */
         const size_t advance = (host.size() - issued.size() + 1);
 
         if(host_idx + advance > host.size()) {  // shouldn't happen
            return false;
         }
 
         // Can't be any intervening .s that we would have skipped
         for(size_t k = host_idx; k != host_idx + advance; ++k) {
            if(host[k] == '.') {
               return false;
            }
         }
 
         host_idx += advance;
      } else {
         if(!dns_char_eq(issued[i], host[host_idx])) {
            return false;
         }
 
         host_idx += 1;
      }
   }
 
   // Wildcard issued name must have at least 3 components
   if(dots_seen < 2) {
      return false;
   }
 
   return true;
}

Referenced by matches_wildcard(), and operator==().

is_wildcard()

bool Botan::DNSName::is_wildcard ( ) const

inline

True if this name is a wildcard pattern: a single "*" somewhere in the leftmost label, per RFC 6125 6.4.3 (which permits in-label partial wildcards like "foo*.example.com" as well as the complete-leftmost-label "*.example.com" form). Shapes outside this form - multiple "*" or "*" not in the leftmost label - are rejected at construction by from_san_string, so any stored "*" is already in the leftmost label.

TODO(Botan4) when RFC 9525 wildcards are used, this fn can change to just looking at the first character of m_name.

Definition at line 71 of file dns_name.h.

{ return m_name.find('*') != std::string::npos; }

matches_wildcard()

bool Botan::DNSName::matches_wildcard

(

std::string_view

wildcard

)

const

Test whether this name matches a wildcard pattern (e.g. "*.example.com"). The wildcard label must be the leftmost label. Comparison is case-insensitive.

Definition at line 186 of file dns_name.cpp.

                                                            {
   return host_wildcard_match(wildcard, m_name);
}

References host_wildcard_match().

Referenced by Botan::X509_Certificate::matches_dns_name().

name()

const std::string & Botan::DNSName::name ( ) const

inline

Access the canonicalized name

Returns

the lowercased ASCII form of the name

Definition at line 57 of file dns_name.h.

{ return m_name; }

Referenced by from_san_string(), and from_string().

operator<=>()

auto Botan::DNSName::operator<=> ( const DNSName & ) const

default

Order two names by their canonicalized form

Returns

the ordering of this name relative to the other

operator==()

bool Botan::DNSName::operator== ( const DNSName & ) const

default

Compare two names by their canonicalized form

Returns

true if the two names are equal

References host_wildcard_match().

to_string()

const std::string & Botan::DNSName::to_string ( ) const

inline

Access the canonicalized name

Returns

the lowercased ASCII form of the name

Definition at line 51 of file dns_name.h.

{ return m_name; }

Referenced by Botan::GeneralName::matches_dns(), and Botan::GeneralName::matches_email().

---

The documentation for this class was generated from the following files:

• src/lib/utils/dns_name/dns_name.h
• src/lib/utils/dns_name/dns_name.cpp