Botan 3.14.1
Crypto and TLS for C&
Botan::DNSName Class Referencefinal

#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 147 of file dns_name.cpp.

147 {
148 if(auto canon = check_and_canonicalize_dns_name(name)) {
149 /*
150 Validate the wildcard shape: at most one "*", and if present it must be in
151 the leftmost label (no "." before it). This matches the RFC 6125 6.4.3
152 form that host_wildcard_match accepts and rejects eg "*.*.example.com" or
153 "foo.*.example.com"
154 */
155 const auto first_star = canon->find('*');
156 if(first_star != std::string::npos) {
157 if(canon->find('*', first_star + 1) != std::string::npos) {
158 return std::nullopt;
159 }
160 const auto first_dot = canon->find('.');
161 if(first_dot != std::string::npos && first_dot < first_star) {
162 return std::nullopt;
163 }
164 /*
165 RFC 6125 6.4.3: "the client SHOULD NOT attempt to match a presented
166 identifier where the wildcard character is embedded within an
167 A-label or U-label"
168 */
169 if(canon->starts_with("xn--")) {
170 return std::nullopt;
171 }
172 // A wildcard match requires at least three labels, so shorter
173 // patterns ("*", "*.com") could never match any host
174 if(std::count(canon->begin(), canon->end(), '.') < 2) {
175 return std::nullopt;
176 }
177 }
178 return DNSName(std::move(*canon));
179 } else {
180 return {};
181 }
182}
const std::string & name() const
Definition dns_name.h:57

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 134 of file dns_name.cpp.

134 {
135 if(auto canon = check_and_canonicalize_dns_name(name)) {
136 // TODO(C++23) std::string::contains
137 if(canon->find('*') != std::string::npos) {
138 return {};
139 }
140 return DNSName(std::move(*canon));
141 } else {
142 return {};
143 }
144}

References name().

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

◆ 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 189 of file dns_name.cpp.

189 {
190 if(host.empty() || issued.empty()) {
191 return false;
192 }
193
194 // Maximum valid DNS name
195 if(host.size() > 253) {
196 return false;
197 }
198
199 /*
200 The wildcard if existing absorbs (host.size() - issued.size() + 1) chars,
201 which must be non-negative. So issued cannot possibly exceed host.size() + 1.
202 */
203 if(issued.size() > host.size() + 1) {
204 return false;
205 }
206
207 /*
208 If there are embedded nulls in your issued name
209 Well I feel bad for you son
210 */
211 if(issued.find('\0') != std::string_view::npos || host.find('\0') != std::string_view::npos) {
212 return false;
213 }
214
215 // '*' is not a valid character in DNS names so should not appear on the host side
216 if(host.find('*') != std::string_view::npos) {
217 return false;
218 }
219
220 // Similarly a DNS name can't end in .
221 if(host.back() == '.') {
222 return false;
223 }
224
225 // Nor can it start with one
226 if(host.front() == '.') {
227 return false;
228 }
229
230 // And a host can't have an empty name component, so reject that
231 if(host.find("..") != std::string_view::npos) {
232 return false;
233 }
234
235 // ASCII-only case-insensitive char equality, avoids locale overhead from tolower
236 auto dns_char_eq = [](char a, char b) -> bool {
237 if(a == b) {
238 return true;
239 }
240 const auto la = static_cast<unsigned char>(a | 0x20);
241 const auto lb = static_cast<unsigned char>(b | 0x20);
242 return la == lb && la >= 'a' && la <= 'z';
243 };
244
245 auto dns_char_eq_range = [&](std::string_view a, std::string_view b) -> bool {
246 if(a.size() != b.size()) {
247 return false;
248 }
249 for(size_t i = 0; i != a.size(); ++i) {
250 if(!dns_char_eq(a[i], b[i])) {
251 return false;
252 }
253 }
254 return true;
255 };
256
257 // Exact match: accept
258 if(dns_char_eq_range(issued, host)) {
259 return true;
260 }
261
262 // First detect offset of wildcard '*' if included
263 const size_t first_star = issued.find('*');
264 const bool has_wildcard = (first_star != std::string_view::npos);
265
266 // At most one wildcard is allowed
267 if(has_wildcard && issued.find('*', first_star + 1) != std::string_view::npos) {
268 return false;
269 }
270
271 // If no * at all then not a wildcard, and so not a match
272 if(!has_wildcard) {
273 return false;
274 }
275
276 /*
277 RFC 6125 6.4.3: "the client SHOULD NOT attempt to match a presented
278 identifier where the wildcard character is embedded within an
279 A-label or U-label"
280
281 The host side check rejects a partial wildcard absorbing part of an
282 A-label of the host, which would otherwise allow the same confusion.
283 */
284 const auto is_idna_prefixed = [&](std::string_view label) {
285 return label.size() >= 4 && dns_char_eq_range(label.substr(0, 4), "xn--");
286 };
287 const auto issued_label = issued.substr(0, issued.find('.'));
288 if(is_idna_prefixed(issued_label)) {
289 return false;
290 }
291 if(issued_label != "*" && is_idna_prefixed(host.substr(0, host.find('.')))) {
292 return false;
293 }
294
295 /*
296 Now walk through the issued string, making sure every character
297 matches. When we come to the (singular) '*', jump forward in the
298 hostname by the corresponding amount. We know exactly how much
299 space the wildcard takes because it must be exactly `len(host) -
300 len(issued) + 1 chars`.
301
302 We also verify that the '*' comes in the leftmost component, and
303 doesn't skip over any '.' in the hostname.
304 */
305 size_t dots_seen = 0;
306 size_t host_idx = 0;
307
308 for(size_t i = 0; i != issued.size(); ++i) {
309 if(issued[i] == '.') {
310 dots_seen += 1;
311 }
312
313 if(issued[i] == '*') {
314 // Fail: wildcard can only come in leftmost component
315 if(dots_seen > 0) {
316 return false;
317 }
318
319 /*
320 Since there is only one * we know the tail of the issued and
321 hostname must be an exact match. In this case advance host_idx
322 to match.
323 */
324 const size_t advance = (host.size() - issued.size() + 1);
325
326 if(host_idx + advance > host.size()) { // shouldn't happen
327 return false;
328 }
329
330 // Can't be any intervening .s that we would have skipped
331 for(size_t k = host_idx; k != host_idx + advance; ++k) {
332 if(host[k] == '.') {
333 return false;
334 }
335 }
336
337 host_idx += advance;
338 } else {
339 if(!dns_char_eq(issued[i], host[host_idx])) {
340 return false;
341 }
342
343 host_idx += 1;
344 }
345 }
346
347 // Wildcard issued name must have at least 3 components
348 if(dots_seen < 2) {
349 return false;
350 }
351
352 return true;
353}

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.

71{ 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 184 of file dns_name.cpp.

184 {
185 return host_wildcard_match(wildcard, m_name);
186}
static bool host_wildcard_match(std::string_view issued, std::string_view host)
Definition dns_name.cpp:189

References host_wildcard_match().

◆ 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.

57{ 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.

51{ 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: