Path-free libcurl cookie and CA credential binding. More...

#include <curl/curl.h>
#include <string.h>
#include "mdl_net.h"
#include "mdl_net_curl_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_net_curl_credentials.c:

Enumerations
enum	mdl_cookie_limit_t : uint16_t { k_cookie_line_max = 4096U , k_cookie_name_field = 5U , k_cookie_field_count = 7U , k_cookie_ascii_del = 0x7FU }
	Maximum imported cookie row including its terminating NUL. More...
enum	cookie_row_disposition_t : uint8_t { k_cookie_row_reject = 0 , k_cookie_row_ignore , k_cookie_row_accept }
	Cookie-line disposition after strict syntax validation. More...

Functions
static char	internal_ascii_lower (char value)
	Lower-case one ASCII byte without locale state.
static bool	internal_ascii_has_prefix (const char data, size_t length, const char prefix)
	Test one bounded value for an ASCII case-insensitive prefix.
static bool	internal_cookie_field_is (const char data, size_t length, const char literal)
	Compare one bounded field with an exact ASCII literal.
static bool	internal_cookie_expiry_valid (const char *data, size_t length)
	Validate one decimal Netscape-cookie expiry field.
static bool	internal_cookie_name_valid (const char *data, size_t length)
	Validate an RFC token-style cookie name.
static bool	internal_netscape_cookie_valid (const char *line, size_t length)
	Validate one Netscape cookie-file row without accepting commands.
static bool	internal_cookie_domain_valid (const char *attribute, size_t length)
	Test whether a Set-Cookie attribute has a nonempty Domain value.
static bool	internal_set_cookie_valid (const char *line, size_t length)
	Validate a Set-Cookie row and require an explicit Domain attribute.
static cookie_row_disposition_t	internal_cookie_classify (const char *line, size_t length)
	Classify a bounded cookie-file line for safe libcurl import.
static ra8_err_t	internal_apply_cookie_line (CURL curl, const uint8_t data, size_t length)
	Import one validated bounded cookie row.
ra8_err_t	priv_mdl_net_curl_apply_cookies (CURL curl, const mdl_net_bytes_t cookies)
	Enable the cookie engine and import validated caller-owned rows.
ra8_err_t	priv_mdl_net_curl_apply_ca_blob (CURL curl, const mdl_net_bytes_t ca_pem, struct curl_blob *blob)
	Bind complete caller-owned CA PEM bytes with NOCOPY semantics.

Detailed Description

Path-free libcurl cookie and CA credential binding.

Validates bounded caller-owned bytes before importing cookies and binds complete CA PEM bytes with the NOCOPY blob contract.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file mdl_net_curl_credentials.c.

Enumeration Type Documentation

◆ cookie_row_disposition_t

enum cookie_row_disposition_t : uint8_t

Cookie-line disposition after strict syntax validation.

Enumerator
k_cookie_row_reject	Reject the complete credential input.
k_cookie_row_ignore	Recognized blank/comment framing.
k_cookie_row_accept	Safe cookie row to import.

Definition at line 25 of file mdl_net_curl_credentials.c.

◆ mdl_cookie_limit_t

enum mdl_cookie_limit_t : uint16_t

Maximum imported cookie row including its terminating NUL.

Enumerator
k_cookie_line_max	Honest fixed per-row importer bound.
k_cookie_name_field	Netscape cookie name-field ordinal.
k_cookie_field_count	Required Netscape cookie field count.
k_cookie_ascii_del	First non-printable high ASCII byte.

Definition at line 17 of file mdl_net_curl_credentials.c.

Function Documentation

◆ internal_apply_cookie_line()

ra8_err_t internal_apply_cookie_line	(	CURL *	curl,
		const uint8_t *	data,
		size_t	length )

static

Import one validated bounded cookie row.

Parameters

[in,out]	curl	Fresh easy handle.
[in]	data	Row bytes without CR/LF.
[in]	length	Row byte count.

Returns: Canonical validation or option status.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 370 of file mdl_net_curl_credentials.c.

References internal_cookie_classify(), k_cookie_line_max, k_cookie_row_accept, k_cookie_row_reject, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_fail, k_ra8_ok, and memcpy().

Referenced by priv_mdl_net_curl_apply_cookies().

◆ internal_ascii_has_prefix()

bool internal_ascii_has_prefix	(	const char *	data,
		size_t	length,
		const char *	prefix )

static

Test one bounded value for an ASCII case-insensitive prefix.

Parameters

[in]	data	Bounded bytes to inspect.
[in]	length	Readable byte count.
[in]	prefix	Lower-case NUL-terminated ASCII prefix.

Returns: Whether the complete prefix matched.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 71 of file mdl_net_curl_credentials.c.

References internal_ascii_lower().

Referenced by internal_cookie_classify(), and internal_cookie_domain_valid().

◆ internal_ascii_lower()

char internal_ascii_lower ( char value )

static

Lower-case one ASCII byte without locale state.

Parameters

[in] value Byte to map.

Returns: Lower-case ASCII byte or the unchanged input.

Return values

0	The input byte was NUL.
other	Lower-case mapping or unchanged input byte.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 47 of file mdl_net_curl_credentials.c.

References RA8_INTERNAL.

Referenced by internal_ascii_has_prefix().

◆ internal_cookie_classify()

cookie_row_disposition_t internal_cookie_classify	(	const char *	line,
		size_t	length )

static

Classify a bounded cookie-file line for safe libcurl import.

Parameters

[in]	line	Bounded row without CR/LF.
[in]	length	Readable row bytes.

Returns: Reject, ignore, or accept disposition.

Return values

k_cookie_row_reject	The row is unsafe or malformed.
k_cookie_row_ignore	The row is recognized framing only.
k_cookie_row_accept	The complete row is safe to import.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 317 of file mdl_net_curl_credentials.c.

References internal_ascii_has_prefix(), internal_cookie_field_is(), internal_netscape_cookie_valid(), internal_set_cookie_valid(), k_cookie_ascii_del, k_cookie_row_accept, k_cookie_row_ignore, k_cookie_row_reject, and RA8_INTERNAL.

Referenced by internal_apply_cookie_line().

◆ internal_cookie_domain_valid()

bool internal_cookie_domain_valid	(	const char *	attribute,
		size_t	length )

static

Test whether a Set-Cookie attribute has a nonempty Domain value.

Parameters

[in]	attribute	Bounded attribute bytes.
[in]	length	Attribute byte count.

Returns: Whether this is an explicit nonempty Domain attribute.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 238 of file mdl_net_curl_credentials.c.

References internal_ascii_has_prefix(), and RA8_INTERNAL.

Referenced by internal_set_cookie_valid().

◆ internal_cookie_expiry_valid()

bool internal_cookie_expiry_valid	(	const char *	data,
		size_t	length )

static

Validate one decimal Netscape-cookie expiry field.

Parameters

[in]	data	Field bytes.
[in]	length	Field byte count.

Returns: Whether the nonempty field contains only decimal digits.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 125 of file mdl_net_curl_credentials.c.

References RA8_INTERNAL.

Referenced by internal_netscape_cookie_valid().

◆ internal_cookie_field_is()

bool internal_cookie_field_is	(	const char *	data,
		size_t	length,
		const char *	literal )

static

Compare one bounded field with an exact ASCII literal.

Parameters

[in]	data	Bounded field bytes.
[in]	length	Readable field byte count.
[in]	literal	NUL-terminated comparison literal.

Returns: Whether the field and literal are byte-identical.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 102 of file mdl_net_curl_credentials.c.

References memcmp(), and strlen().

Referenced by internal_cookie_classify(), and internal_netscape_cookie_valid().

◆ internal_cookie_name_valid()

bool internal_cookie_name_valid	(	const char *	data,
		size_t	length )

static

Validate an RFC token-style cookie name.

Parameters

[in]	data	Bounded candidate name bytes.
[in]	length	Candidate byte count.

Returns: Whether the nonempty name contains only permitted ASCII token bytes.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 155 of file mdl_net_curl_credentials.c.

References RA8_INTERNAL, and strchr().

Referenced by internal_netscape_cookie_valid(), and internal_set_cookie_valid().

◆ internal_netscape_cookie_valid()

bool internal_netscape_cookie_valid	(	const char *	line,
		size_t	length )

static

Validate one Netscape cookie-file row without accepting commands.

Parameters

[in]	line	Bounded cookie row without a line ending.
[in]	length	Readable row bytes.

Returns: Whether the row has the required seven tab-separated fields.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 190 of file mdl_net_curl_credentials.c.

References internal_cookie_expiry_valid(), internal_cookie_field_is(), internal_cookie_name_valid(), k_cookie_field_count, k_cookie_name_field, and RA8_INTERNAL.

Referenced by internal_cookie_classify().

◆ internal_set_cookie_valid()

bool internal_set_cookie_valid	(	const char *	line,
		size_t	length )

static

Validate a Set-Cookie row and require an explicit Domain attribute.

Parameters

[in]	line	Bounded cookie row without a line ending.
[in]	length	Readable row bytes.

Returns: Whether the row has a cookie pair and a nonempty Domain attribute.

Since: 0.1.0

Parses only bounded caller bytes and rejects command-like cookie rows. Only validated borrowed credential storage reaches libcurl.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 264 of file mdl_net_curl_credentials.c.

References internal_cookie_domain_valid(), internal_cookie_name_valid(), and RA8_INTERNAL.

Referenced by internal_cookie_classify().

◆ priv_mdl_net_curl_apply_ca_blob()

ra8_err_t priv_mdl_net_curl_apply_ca_blob	(	CURL *	curl,
		const mdl_net_bytes_t *	ca_pem,
		struct curl_blob *	blob )

Bind complete caller-owned CA PEM bytes with NOCOPY semantics.

Parameters

[in,out]	curl	Fresh libcurl easy handle.
[in]	ca_pem	Complete nonempty PEM bytes, or an empty absent view.
[in,out]	blob	Stable descriptor retained by the backend when supported.

Returns: Canonical validation, option, or unsupported status.

Return values

k_ra8_ok	System CA policy remains active or the blob was bound.
k_ra8_err_invalid_arg	The view or blob descriptor is inconsistent.
k_ra8_err_not_supported	This libcurl/TLS build lacks CA blob support.
k_ra8_fail	Libcurl rejected the custom CA option.

Precondition: Nonempty ca_pem bytes remain readable through backend destruction.

Postcondition: No CA filename or hidden file read is configured.

Note: The descriptor may be NULL only when custom CA blobs are unavailable.

Since: 0.1.0

Applies validated caller-owned credentials to one easy handle. Borrowed storage remains caller-owned for libcurl's required lifetime.

Precondition: Every required pointer is non-null and remains valid for the call.

Postcondition: Documented outputs and the return value describe the same outcome.

Definition at line 422 of file mdl_net_curl_credentials.c.

References mdl_net_bytes_t::data, k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_fail, k_ra8_ok, and mdl_net_bytes_t::length.

Referenced by internal_apply_security_opts().

◆ priv_mdl_net_curl_apply_cookies()

ra8_err_t priv_mdl_net_curl_apply_cookies	(	CURL *	curl,
		const mdl_net_bytes_t *	cookies )

Enable the cookie engine and import validated caller-owned rows.

Parameters

[in,out]	curl	Fresh libcurl easy handle.
[in]	cookies	Newline-delimited bounded cookie bytes.

Returns: Canonical validation or option status.

Return values

k_ra8_ok	Every accepted cookie row was copied by libcurl.
k_ra8_err_invalid_arg	The view or a row is malformed or unsafe.
k_ra8_err_invalid_size	One row exceeds the fixed importer bound.
k_ra8_fail	libcurl rejected an otherwise valid option.

Precondition: curl and cookies are non-NULL.

Postcondition: Success enables the cookie engine without path-based file I/O.; Caller command strings cannot reach CURLOPT_COOKIELIST.

Note: Libcurl owns its copy of every accepted row.

Since: 0.1.0

Applies validated caller-owned credentials to one easy handle. Borrowed storage remains caller-owned for libcurl's required lifetime.

Precondition: Every required pointer is non-null and remains valid for the call.

Definition at line 389 of file mdl_net_curl_credentials.c.

References mdl_net_bytes_t::data, internal_apply_cookie_line(), k_ra8_err_invalid_arg, k_ra8_fail, k_ra8_ok, and mdl_net_bytes_t::length.

Referenced by internal_apply_behavior_opts().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ cookie_row_disposition_t

◆ mdl_cookie_limit_t

Function Documentation

◆ internal_apply_cookie_line()

◆ internal_ascii_has_prefix()

◆ internal_ascii_lower()

◆ internal_cookie_classify()

◆ internal_cookie_domain_valid()

◆ internal_cookie_expiry_valid()

◆ internal_cookie_field_is()

◆ internal_cookie_name_valid()

◆ internal_netscape_cookie_valid()

◆ internal_set_cookie_valid()

◆ priv_mdl_net_curl_apply_ca_blob()

◆ priv_mdl_net_curl_apply_cookies()