Hardened, bounded URL + HTTP/1.x response-head parsing for a safe fetcher. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for n_url_safe.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	n_url_safe
	The parts of an absolute http(s) URL. More...
struct	n_url_safe_head
	The response-head fields a fetcher acts on. More...

Macros
#define	N_URL_SAFE_HEAD_MAX 16384u
	Largest response head (status line + headers, through CRLFCRLF) accepted.
#define	N_URL_SAFE_HOST_MAX 253u
	Longest hostname / IP literal accepted (RFC 1035 limit).
#define	N_URL_SAFE_MAX 1024u
	Longest URL / path / Location accepted.
#define	N_URL_SAFE_MIME_MAX 127u
	Longest captured Content-Type (mime), parameters dropped.

Functions
int	n_url_safe_find (const char text, size_t len, char out, size_t cap)
	find the first http(s) URL in a block of text
int	n_url_safe_head_parse (const char buf, size_t len, n_url_safe_head out)
	parse an HTTP/1.x response head from [buf, buf+len)
int	n_url_safe_parse (const char url, size_t len, n_url_safe out)
	parse an absolute http(s) URL [url, url+len) into a bounded struct
int	n_url_safe_resolve (const char base, size_t base_len, const char loc, size_t loc_len, char *out, size_t cap)
	resolve a redirect Location against a request URL

Detailed Description

Hardened, bounded URL + HTTP/1.x response-head parsing for a safe fetcher.

A deliberately narrow, non-allocating companion to the general n_url API (n_network.h) – for the kind of program that fetches an ATTACKER-SUPPLIED http(s) URL (link previews, webhooks, avatar imports, ...). Where n_url_parse is a full, allocating URL model (query params, canonicalize, build), these fill a caller-owned stack struct, reject SSRF / phishing vectors (userinfo, non-http(s) scheme, bad host/port), and cap every field – so a hostile URL or server response can neither over-read nor allocate. Pair with n_ssrf to classify the resolved address, and drive the sockets/TLS in the caller.

Provides: split an absolute URL into parts, parse the response head (status + the few headers a fetcher acts on), resolve a redirect Location, and find the first URL in a block of text.

Author: Castagnier Mickael

Version: 1.0

Definition in file n_url_safe.h.

Data Structure Documentation

◆ n_url_safe

struct n_url_safe

The parts of an absolute http(s) URL.

host is the bare hostname or IP literal (an IPv6 literal has its brackets stripped); path includes any query, with the fragment dropped and defaulting to "/".

Examples: ex_url_safe.c.

Definition at line 59 of file n_url_safe.h.

Collaboration diagram for n_url_safe:

Data Fields
char	host[253u+1]
int	https	1 = https (default port 443), 0 = http (80)
char	path[1024u+1]
uint16_t	port

◆ n_url_safe_head

struct n_url_safe_head

The response-head fields a fetcher acts on.

Examples: ex_url_safe.c.

Definition at line 67 of file n_url_safe.h.

Collaboration diagram for n_url_safe_head:

Data Fields
int	chunked	Transfer-Encoding: chunked present.
long long	content_length	Content-Length, or -1 if absent.
char	content_type[127u+1]	mime, params dropped
size_t	head_len	bytes through the terminating CRLFCRLF
char	location[1024u+1]	Location (redirects).
int	status	HTTP status code, e.g. 200 / 301

Macro Definition Documentation

◆ N_URL_SAFE_HEAD_MAX

#define N_URL_SAFE_HEAD_MAX 16384u

Largest response head (status line + headers, through CRLFCRLF) accepted.

Definition at line 54 of file n_url_safe.h.

Referenced by n_url_safe_head_parse().

◆ N_URL_SAFE_HOST_MAX

#define N_URL_SAFE_HOST_MAX 253u

Longest hostname / IP literal accepted (RFC 1035 limit).

Definition at line 48 of file n_url_safe.h.

Referenced by n_url_safe_parse().

◆ N_URL_SAFE_MAX

#define N_URL_SAFE_MAX 1024u

Longest URL / path / Location accepted.

Examples: ex_url_safe.c.

Definition at line 50 of file n_url_safe.h.

Referenced by main(), and n_url_safe_parse().

◆ N_URL_SAFE_MIME_MAX

#define N_URL_SAFE_MIME_MAX 127u

Longest captured Content-Type (mime), parameters dropped.

Definition at line 52 of file n_url_safe.h.

Function Documentation

◆ n_url_safe_find()

int n_url_safe_find	(	const char *	text,
		size_t	len,
		char *	out,
		size_t	cap )

find the first http(s) URL in a block of text

Writes it to out (cap includes the NUL). Trailing sentence punctuation is trimmed. The candidate must pass n_url_safe_parse (so a userinfo / malformed URL is skipped, and scanning continues), which makes this a safe trigger: it never surfaces a URL n_url_safe_parse would reject.

Parameters

text	the text to scan
len	its length
out	output buffer for the found URL
cap	capacity of out (including the NUL)

Returns: 1 if a URL was found, 0 otherwise

Definition at line 344 of file n_url_safe.c.

References ci_prefix(), and n_url_safe_parse().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_url_safe_head_parse()

int n_url_safe_head_parse	(	const char *	buf,
		size_t	len,
		n_url_safe_head *	out )

parse an HTTP/1.x response head from [buf, buf+len)

Returns 1 only when a complete head (through CRLFCRLF) is present and the status line is well-formed; 0 if incomplete, malformed, or larger than N_URL_SAFE_HEAD_MAX. On success out->head_len is the offset of the body. Header names are matched case-insensitively; unknown headers are ignored. Bounded and over-read safe.

Parameters

buf	the received bytes
len	number of bytes in buf
out	the parsed head to fill

Returns: 1 on success, 0 otherwise

Definition at line 230 of file n_url_safe.c.

References n_url_safe_head::chunked, ci_prefix(), n_url_safe_head::content_length, n_url_safe_head::content_type, copy_clean(), copy_mime(), has_token(), n_url_safe_head::head_len, le(), n_url_safe_head::location, N_URL_SAFE_HEAD_MAX, name_eq(), parse_clen(), and n_url_safe_head::status.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_url_safe_parse()

int n_url_safe_parse	(	const char *	url,
		size_t	len,
		n_url_safe *	out )

parse an absolute http(s) URL [url, url+len) into a bounded struct

Rejects a non-http(s) scheme, userinfo ("user@host" – an SSRF / phishing vector), an empty or over-long host, a bad port, control bytes, and anything longer than the caps. IPv6 literals in brackets are accepted (brackets stripped into host).

Parameters

url	the URL bytes
len	number of bytes in url
out	the parsed URL to fill

Returns: 1 on success, 0 otherwise

Definition at line 76 of file n_url_safe.c.

References ci_prefix(), n_url_safe::host, n_url_safe::https, N_URL_SAFE_HOST_MAX, N_URL_SAFE_MAX, parse_port(), n_url_safe::path, and n_url_safe::port.

Referenced by n_url_safe_find(), n_url_safe_resolve(), and uparse().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_url_safe_resolve()

int n_url_safe_resolve	(	const char *	base,
		size_t	base_len,
		const char *	loc,
		size_t	loc_len,
		char *	out,
		size_t	cap )

resolve a redirect Location against a request URL

Handles an absolute http(s) target, a scheme-relative "//host/..." and a root-relative "/path"; a bare relative path is refused (returns 0). The result is re-validated with n_url_safe_parse.

Parameters

base	the request URL
base_len	its length
loc	the Location value
loc_len	its length
out	output buffer for the absolute URL
cap	capacity of out (including the NUL)

Returns: 1 on success, 0 otherwise

Definition at line 308 of file n_url_safe.c.

References ci_prefix(), n_url_safe::host, n_url_safe::https, n_url_safe_parse(), and n_url_safe::port.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Functions

Detailed Description

Data Structure Documentation

◆ n_url_safe

◆ n_url_safe_head

Macro Definition Documentation

◆ N_URL_SAFE_HEAD_MAX

◆ N_URL_SAFE_HOST_MAX

◆ N_URL_SAFE_MAX

◆ N_URL_SAFE_MIME_MAX

Function Documentation

◆ n_url_safe_find()

◆ n_url_safe_head_parse()

◆ n_url_safe_parse()

◆ n_url_safe_resolve()