Botan 3.14.1
Crypto and TLS for C&
uri.cpp
Go to the documentation of this file.
1/*
2* (C) 2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#include <botan/uri.h>
8
9#include <botan/assert.h>
10#include <botan/internal/charset.h>
11#include <botan/internal/parsing.h>
12
13namespace Botan {
14
15namespace {
16
17std::optional<uint16_t> parse_port(std::string_view s) {
18 // RFC 3986 port is "*DIGIT" but we reject leading zeros ("host:0080")
19 if(const auto port = parse_u16(s, /*require_canonical=*/true)) {
20 if(*port > 0) {
21 return port;
22 }
23 }
24
25 return {};
26}
27
28bool is_valid_percent_escape(char c1, char c2) {
29 const auto is_hex_digit = [](char c) {
30 return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
31 };
32
33 if(!is_hex_digit(c1) || !is_hex_digit(c2)) {
34 return false;
35 }
36
37 // Proactively reject embedded null (%00)
38 if(c1 == '0' && c2 == '0') {
39 return false;
40 }
41
42 return true;
43}
44
45bool validate_path_query_fragment(std::string_view tail) {
46 /*
47 * RFC 3986 syntax for the path/query/fragment of a URI:
48 *
49 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
50 * pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
51 * segment = *pchar
52 * path-abempty = *( "/" segment )
53 * query = *( pchar / "/" / "?" )
54 * fragment = *( pchar / "/" / "?" )
55 */
56
57 constexpr auto is_pchar_or_slash = CharacterValidityTable::alpha_numeric_plus("-._~!$&'()*+,;=:@/");
58
59 enum class State : uint8_t { Path, Query, Fragment };
60 State state = State::Path;
61
62 for(size_t i = 0; i < tail.size(); ++i) {
63 const char c = tail[i];
64 if(c == '%') {
65 if(i + 2 >= tail.size() || !is_valid_percent_escape(tail[i + 1], tail[i + 2])) {
66 return false;
67 }
68 i += 2;
69 continue;
70 }
71 if(c == '?') {
72 // First '?' transitions from path to query, any further '?' are literal
73 if(state == State::Path) {
74 state = State::Query;
75 }
76 continue;
77 }
78 if(c == '#') {
79 // There is only one '#' fragment delimiter, second '#' is invalid
80 if(state == State::Fragment) {
81 return false;
82 }
83 state = State::Fragment;
84 continue;
85 }
86 if(!is_pchar_or_slash(c)) {
87 return false;
88 }
89 }
90 return true;
91}
92
93bool validate_userinfo(std::string_view userinfo) {
94 constexpr auto is_valid_userinfo_char = CharacterValidityTable::alpha_numeric_plus("-._~!$&'()*+,;=:");
95
96 for(size_t i = 0; i < userinfo.size(); ++i) {
97 const char c = userinfo[i];
98 if(c == '%') {
99 if(i + 2 >= userinfo.size() || !is_valid_percent_escape(userinfo[i + 1], userinfo[i + 2])) {
100 return false;
101 }
102 i += 2;
103 continue;
104 }
105 if(!is_valid_userinfo_char(c)) {
106 return false;
107 }
108 }
109 return true;
110}
111
112} // namespace
113
114std::strong_ordering URI::operator<=>(const URI& other) const {
115 const bool has_authority = raw_authority().has_value();
116 const bool other_has_authority = other.raw_authority().has_value();
117
118 return std::tie(m_scheme, has_authority, m_authority, m_path, m_query, m_fragment) <=>
119 std::tie(
120 other.m_scheme, other_has_authority, other.m_authority, other.m_path, other.m_query, other.m_fragment);
121}
122
123bool URI::operator==(const URI& other) const {
124 return m_scheme == other.m_scheme && raw_authority().has_value() == other.raw_authority().has_value() &&
125 m_authority == other.m_authority && m_path == other.m_path && m_query == other.m_query &&
126 m_fragment == other.m_fragment;
127}
128
129std::optional<std::string_view> URI::raw_authority() const {
130 const auto colon = m_raw.find(':');
131 BOTAN_ASSERT_NOMSG(colon != std::string::npos);
132
133 const size_t rest_offset = colon + 1;
134 if(m_raw.size() < rest_offset + 2 || m_raw[rest_offset] != '/' || m_raw[rest_offset + 1] != '/') {
135 return std::nullopt;
136 }
137
138 const size_t authority_start = rest_offset + 2;
139 const auto authority_end = m_raw.find_first_of("/?#", authority_start);
140 const size_t authority_len =
141 (authority_end == std::string::npos) ? std::string::npos : authority_end - authority_start;
142 return std::string_view(m_raw).substr(authority_start, authority_len);
143}
144
145std::strong_ordering URI::Authority::operator<=>(const URI::Authority& other) const {
146 /*
147 Userinfo is compared without normalization; RFC 3986 6.2.2.1:
148 When a URI uses components of the generic syntax, the component
149 syntax equivalence rules always apply; namely, that the scheme
150 and host are case-insensitive and therefore should be normalized
151 to lowercase. ... The other generic syntax components are assumed
152 to be case-sensitive unless specifically defined otherwise by the
153 scheme.
154 */
155 return std::tie(m_userinfo, m_host, m_port) <=> std::tie(other.m_userinfo, other.m_host, other.m_port);
156}
157
159 return m_userinfo == other.m_userinfo && m_host == other.m_host && m_port == other.m_port;
160}
161
162//static
163std::optional<URI> URI::from_string(std::string_view raw) {
164 // Empty string is not a valid URI
165 if(raw.empty()) {
166 return {};
167 }
168
169 // RFC 3986:
170 // scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
171 constexpr auto is_scheme_cont_char = CharacterValidityTable::alpha_numeric_plus("+-.");
172
173 const auto is_ascii_alpha = [](char c) -> bool { return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'); };
174
175 // Check the first scheme character
176 if(!is_ascii_alpha(raw.front())) {
177 return {};
178 }
179
180 // Scan the rest of the scheme
181 size_t i = 1;
182 while(i < raw.size() && is_scheme_cont_char(raw[i])) {
183 ++i;
184 }
185 // Scheme wasn't followed by ':' -> invalid
186 if(i >= raw.size() || raw[i] != ':') {
187 return {};
188 }
189
190 // Canonicalize the scheme
191 const std::string scheme = tolower_string(raw.substr(0, i));
192
193 auto rest = raw.substr(i + 1);
194
195 std::optional<Authority> parsed_authority;
196 std::string_view path_query_fragment;
197
198 if(rest.starts_with("//")) {
199 rest.remove_prefix(2); // Strip off the '//'
200
201 // Authority runs to the first '/', '?' or '#'. The remaining is `path ? query # fragment`,
202 // which is validated against the RFC 3986 character set.
203 const auto end = rest.find_first_of("/?#");
204 const auto authority = (end == std::string_view::npos) ? rest : rest.substr(0, end);
205 path_query_fragment = (end == std::string_view::npos) ? std::string_view{} : rest.substr(end);
206
207 // Parse and validate non-empty authority strings (hostname, IPv4, or IPv6 address)
208 if(!authority.empty()) {
209 parsed_authority = Authority::from_string(authority);
210 if(!parsed_authority.has_value()) {
211 return {};
212 }
213 }
214 } else {
215 path_query_fragment = rest;
216 }
217
218 // Validate any `path ? query # fragment` portions of the URL
219 if(!validate_path_query_fragment(path_query_fragment)) {
220 return {};
221 }
222
223 // Split into path / query / fragment. Validation above guarantees at most
224 // one '#', so the first '#' is the fragment delimiter, and within the
225 // pre-fragment portion the first '?' (if any) is the query delimiter.
226 const auto hash = path_query_fragment.find('#');
227 const auto pre_fragment =
228 (hash == std::string_view::npos) ? path_query_fragment : path_query_fragment.substr(0, hash);
229 std::optional<std::string> fragment;
230 if(hash != std::string_view::npos) {
231 fragment = std::string(path_query_fragment.substr(hash + 1));
232 }
233
234 const auto qmark = pre_fragment.find('?');
235 const auto path = (qmark == std::string_view::npos) ? pre_fragment : pre_fragment.substr(0, qmark);
236 std::optional<std::string> query;
237 if(qmark != std::string_view::npos) {
238 query = std::string(pre_fragment.substr(qmark + 1));
239 }
240
241 // Accept
242 return URI(
243 std::string(raw), scheme, std::move(parsed_authority), std::string(path), std::move(query), std::move(fragment));
244}
245
246//static
247std::optional<URI::Authority> URI::Authority::from_string(std::string_view raw) {
248 if(raw.empty()) {
249 return {};
250 }
251
252 // Capture the full input now; the userinfo prefix is stripped from
253 // `raw` below, and m_raw must reflect the original
254 const std::string original_input(raw);
255
256 /*
257 RFC 3986
258 userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
259
260 Thus a unencoded '@' is not allowed inside userinfo, and the single '@' splits the
261 username from the authority. The @ being present at all is significant; an empty
262 userinfo ("https://@example.com/") is distinct from no userinfo at all.
263 */
264 std::optional<std::string> userinfo;
265 const auto first_at = raw.find('@');
266 if(first_at != std::string_view::npos) {
267 if(raw.find('@', first_at + 1) != std::string_view::npos) {
268 return {};
269 }
270 const auto userinfo_view = raw.substr(0, first_at);
271 if(!validate_userinfo(userinfo_view)) {
272 return {};
273 }
274 userinfo = std::string(userinfo_view);
275 raw.remove_prefix(first_at + 1);
276 }
277
278 std::string_view host_view;
279 std::string_view port_str;
280 std::optional<Host> host;
281
282 if(!raw.empty() && raw.front() == '[') {
283 // Bracketed IPv6 literal.
284 const auto close = raw.find(']');
285 if(close == std::string_view::npos) {
286 return {};
287 }
288 host_view = raw.substr(1, close - 1);
289 if(host_view.empty()) {
290 return {};
291 }
292 const auto after = raw.substr(close + 1);
293 if(!after.empty()) {
294 if(after.front() != ':') {
295 return {};
296 }
297 port_str = after.substr(1);
298 }
299 auto ipv6 = IPv6Address::from_string(host_view);
300 if(!ipv6.has_value()) {
301 return {};
302 }
303 host = *ipv6;
304 } else {
305 // host[:port] with no brackets. Only one ':' is allowed (port).
306 const auto colon = raw.find(':');
307 if(colon == std::string_view::npos) {
308 host_view = raw;
309 } else {
310 host_view = raw.substr(0, colon);
311 port_str = raw.substr(colon + 1);
312
313 // Verify the `:` char is the only one that appears
314 if(port_str.find(':') != std::string::npos) {
315 return {};
316 }
317 }
318
319 if(host_view.empty()) {
320 return {};
321 }
322
323 // Technically valid per RFC 3986 but likely not something we want to support
324 if(host_view.ends_with('.')) {
325 return {};
326 }
327
328 if(auto ipv4 = IPv4Address::from_string(host_view)) {
329 host = *ipv4;
330 } else if(auto dns = DNSName::from_string(host_view)) {
331 host = std::move(*dns);
332 } else {
333 return {};
334 }
335 }
336
337 std::optional<uint16_t> port;
338
339 if(!port_str.empty()) {
340 port = parse_port(port_str);
341 if(!port.has_value()) {
342 return {};
343 }
344 }
345
346 return Authority(original_input, std::move(userinfo), std::move(*host), port);
347}
348
350 return std::visit([](const auto& h) -> std::string { return h.to_string(); }, m_host);
351}
352
354 if(std::holds_alternative<DNSName>(m_host)) {
355 return HostKind::DNS;
356 } else if(std::holds_alternative<IPv4Address>(m_host)) {
357 return HostKind::IPv4;
358 } else if(std::holds_alternative<IPv6Address>(m_host)) {
359 return HostKind::IPv6;
360 } else {
362 }
363}
364
365//static
366std::vector<URI> URI::filter_scheme(std::string_view scheme, std::span<const URI> uris) {
367 std::vector<URI> results;
368
369 const auto normalized_scheme = tolower_string(scheme);
370
371 for(const auto& uri : uris) {
372 if(uri.scheme() == normalized_scheme && uri.authority().has_value()) {
373 results.push_back(uri);
374 }
375 }
376
377 return results;
378}
379
380} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_UNREACHABLE()
Definition assert.h:173
static constexpr CharacterValidityTable alpha_numeric_plus(std::string_view extras)
Definition charset.h:114
static std::optional< DNSName > from_string(std::string_view name)
Definition dns_name.cpp:134
static std::optional< IPv4Address > from_string(std::string_view str)
static std::optional< IPv6Address > from_string(std::string_view str)
std::strong_ordering operator<=>(const Authority &other) const
Definition uri.cpp:145
const std::optional< std::string > & userinfo() const
Definition uri.h:87
static std::optional< Authority > from_string(std::string_view raw)
Definition uri.cpp:247
const Host & host() const
Definition uri.h:56
bool operator==(const Authority &other) const
Definition uri.cpp:158
std::optional< uint16_t > port() const
Definition uri.h:74
HostKind host_kind() const
Definition uri.cpp:353
std::string host_to_string() const
Definition uri.cpp:349
const std::string & original_input() const
Definition uri.h:79
const std::optional< std::string > & fragment() const
Definition uri.h:168
static std::optional< URI > from_string(std::string_view raw)
Definition uri.cpp:163
const std::string & scheme() const
Definition uri.h:127
static std::vector< URI > filter_scheme(std::string_view scheme, std::span< const URI > uris)
Definition uri.cpp:366
std::strong_ordering operator<=>(const URI &other) const
Definition uri.cpp:114
const std::optional< std::string > & query() const
Definition uri.h:161
const std::string & original_input() const
Definition uri.h:173
const std::optional< Authority > & authority() const
Definition uri.h:132
std::optional< std::string_view > raw_authority() const
Definition uri.cpp:129
bool operator==(const URI &other) const
Definition uri.cpp:123
const std::string & path() const
Definition uri.h:154
std::string tolower_string(std::string_view str)
Definition parsing.cpp:125
std::optional< uint16_t > parse_u16(std::string_view input, bool require_canonical)
Definition parsing.cpp:59