Private bounded validator seams shared by the mdl verifiers. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_export.h"
#include "mdl_storage.h"
#include "mdl_verify.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for mdl_verify_internal.h:

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

Go to the source code of this file.

Data Structures
struct	mdl_verify_arena_t
	Allocation bridge retaining an explicit capacity failure. More...
struct	mdl_verify_io_t
	One open portable input and its immutable size snapshot. More...

Enumerations
enum	mdl_verify_limit_t : uint32_t { k_verify_member_max = 100000U }
	Bounded member policy shared by every structural verifier. More...

Functions
void *	priv_mdl_verify_workspace_take (mdl_export_workspace_t *workspace, size_t bytes, size_t alignment)
	Reserve one aligned span from the verifier's caller-owned arena.
void *	priv_mdl_verify_arena_alloc (void *opaque, size_t items, size_t size)
	Allocate one aligned miniz span from a monotonic arena.
void	priv_mdl_verify_arena_free (void opaque, void address)
	Accept a miniz free for a monotonic arena.
ra8_err_t	priv_mdl_verify_io_read_up_to (mdl_verify_io_t io, uint8_t destination, size_t length, size_t *out_read)
	Read up to a requested portable span.
bool	priv_mdl_verify_is_image (const char *name)
	Recognize supported image suffixes.
bool	priv_mdl_verify_safe_member_name (const char *name)
	Reject unsafe archive member paths.
ra8_err_t	priv_mdl_verify_tar (mdl_verify_io_t io, mdl_verify_report_t report)
	Validate an uncompressed CBT.
ra8_err_t	priv_mdl_verify_gzip_tar (mdl_verify_io_t io, mdl_export_workspace_t workspace, mdl_verify_report_t *report)
	Validate a gzip-compressed CBT.

Detailed Description

Private bounded validator seams shared by the mdl verifiers.

Publishes the borrowed-input and miniz-arena state that both the container verifier and the streamed tarball verifier operate on, together with the bounded member policy every format shares.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file mdl_verify_internal.h.

Enumeration Type Documentation

◆ mdl_verify_limit_t

enum mdl_verify_limit_t : uint32_t

Bounded member policy shared by every structural verifier.

Enumerator
k_verify_member_max	Maximum archive member count.

Definition at line 26 of file mdl_verify_internal.h.

Function Documentation

◆ priv_mdl_verify_arena_alloc()

void * priv_mdl_verify_arena_alloc	(	void *	opaque,
		size_t	items,
		size_t	size )

Allocate one aligned miniz span from a monotonic arena.

Prefixes each payload with a bounded header recording its extent so a later reallocation can copy exactly the preserved bytes.

Parameters

[in,out]	opaque	Bound mdl_verify_arena_t callback context.
[in]	items	Element count requested by miniz.
[in]	size	Element size requested by miniz.

Returns: Payload pointer, or NULL when the arena cannot serve the request.

Return values

NULL	The product overflowed or the arena is exhausted.
other	One writable payload of `items` times `size` bytes.

Precondition: opaque addresses one arena bound to a reset workspace.; The caller treats NULL as an allocation failure.

Postcondition: Failure latches the arena exhaustion flag.; Success reserves exactly one header plus payload block.

Note: Not thread-safe for a shared arena.

Since: 0.1.0

Definition at line 138 of file mdl_verify.c.

References mdl_alloc_header_t::bytes, mdl_verify_arena_t::exhausted, priv_mdl_verify_workspace_take(), RA8_PRIV, and mdl_verify_arena_t::workspace.

Referenced by internal_arena_realloc(), internal_gzip_init_inflate(), and internal_verify_zip().

◆ priv_mdl_verify_arena_free()

void priv_mdl_verify_arena_free	(	void *	opaque,
		void *	address )

Accept a miniz free for a monotonic arena.

Individual allocations remain reserved until the owning verifier resets the workspace, so this release has nothing to reclaim.

Parameters

[in,out]	opaque	Borrowed arena context.
[in]	address	Allocation being released.

Precondition: opaque is the callback context handed to miniz.; address is NULL or was produced by priv_mdl_verify_arena_alloc.

Postcondition: Arena offsets are unchanged.; address is not accessed.

Note: Miniz requires a free callback even for arena allocation.

Since: 0.1.0

Definition at line 162 of file mdl_verify.c.

References RA8_PRIV.

Referenced by internal_gzip_init_inflate(), and internal_verify_zip().

◆ priv_mdl_verify_gzip_tar()

ra8_err_t priv_mdl_verify_gzip_tar	(	mdl_verify_io_t *	io,
		mdl_export_workspace_t *	workspace,
		mdl_verify_report_t *	report )

Validate a gzip-compressed CBT.

Streams raw inflate into the USTAR state machine and checks the fixed RFC 1952 framing, the stored CRC32 and ISIZE, and that no compressed byte follows the end-of-stream marker.

Parameters

[in,out]	io	Borrowed open input positioned at offset zero.
[in,out]	workspace	Exclusive caller-owned scratch arena.
[out]	report	Candidate report populated only on success.

Returns: Framing, inflate, or structural validation status.

Return values

k_ra8_ok	The complete gzip frame and inner TAR were valid.
k_ra8_err_validation_failed	Framing, CRC, size, or structure failed.
k_ra8_err_invalid_size	The scratch arena or a byte bound was exceeded.

Precondition: All pointers are non-NULL and io is open.; workspace was reset by the owning verifier.

Postcondition: The inflater is ended on every path that opened it.; Success publishes the page, member, and metadata counts.

Note: Not thread-safe for a shared input or workspace.

Since: 0.1.0

Definition at line 460 of file mdl_verify_tarball.c.

References internal_gzip_consume(), internal_gzip_header_valid(), internal_gzip_init_inflate(), internal_io_read_exact(), internal_tar_finish(), k_gzip_header_bytes, k_gzip_min_bytes, k_mdl_storage_io_bytes, k_ra8_err_validation_failed, k_ra8_ok, RA8_PRIV, mdl_gzip_stream_t::stream, and mdl_gzip_stream_t::tar.

Referenced by internal_verify_borrowed().

◆ priv_mdl_verify_io_read_up_to()

ra8_err_t priv_mdl_verify_io_read_up_to	(	mdl_verify_io_t *	io,
		uint8_t *	destination,
		size_t	length,
		size_t *	out_read )

Read up to a requested portable span.

Repeats short reads and stops only at end of file or on failure.

Parameters

[in,out]	io	Open verifier input.
[out]	destination	Writable destination buffer.
[in]	length	Maximum byte count to transfer.
[out]	out_read	Byte count actually produced.

Returns: Portable read status.

Return values

k_ra8_ok	Data or a clean end of file was observed.
other	The portable read failed; `out_read` holds the prefix.

Precondition: io is open and destination spans length bytes.; out_read is non-NULL and does not alias destination.

Postcondition: out_read never exceeds length.; A zero count with k_ra8_ok denotes end of file.

Note: Not thread-safe for a shared input.

Since: 0.1.0

Definition at line 233 of file mdl_verify.c.

References fw_fs_read(), k_ra8_ok, and RA8_PRIV.

Referenced by internal_io_read_exact(), internal_jof_pread(), internal_zip_read(), and priv_mdl_verify_tar().

◆ priv_mdl_verify_is_image()

bool priv_mdl_verify_is_image ( const char * name )

Recognize supported image suffixes.

Applies the archive image allowlist case-insensitively.

Parameters

[in] name Archive member name.

Returns: Whether the member carries a supported image suffix.

Return values

true	The suffix is one of the supported image extensions.
false	No supported suffix matched.

Precondition: name is a NUL-terminated string.; name remains valid for the call.

Postcondition: name is unchanged.; No storage is accessed.

Note: Content magic is validated during export, never here.

Since: 0.1.0

Definition at line 79 of file mdl_verify.c.

References internal_ends_ci(), and RA8_PRIV.

Referenced by internal_tar_member(), and internal_zip_member().

◆ priv_mdl_verify_safe_member_name()

bool priv_mdl_verify_safe_member_name ( const char * name )

Reject unsafe archive member paths.

Rejects absolute, empty, dot, parent, and backslash segments.

Parameters

[in] name Archive member name, or NULL.

Returns: Whether the path is lexically contained.

Return values

true	The name is a safe relative path.
false	The name is NULL, absolute, or escapes its root.

Precondition: name is NULL or NUL-terminated.; A non-NULL name remains valid for the call.

Postcondition: name is unchanged.; No filesystem lookup occurs.

Note: This is a lexical containment check only.

Since: 0.1.0

Definition at line 86 of file mdl_verify.c.

References RA8_PRIV.

Referenced by internal_tar_member(), and internal_zip_member().

◆ priv_mdl_verify_tar()

ra8_err_t priv_mdl_verify_tar	(	mdl_verify_io_t *	io,
		mdl_verify_report_t *	report )

Validate an uncompressed CBT.

Streams borrowed reads straight into the USTAR state machine, so no archive-sized buffer is retained for any member.

Parameters

[in,out]	io	Borrowed open input positioned at offset zero.
[out]	report	Candidate report populated only on success.

Returns: Structural validation status.

Return values

k_ra8_ok	Every record and the terminating pair were valid.
k_ra8_err_validation_failed	A record, name, or terminator was invalid.
k_ra8_err_invalid_size	A member count or byte total exceeded its bound.

Precondition: Both pointers are non-NULL and io is open.; The bound storage supplies a nonzero I/O buffer.

Postcondition: The input remains open and its final cursor is unspecified.; Success publishes the page, member, and metadata counts.

Note: Not thread-safe for a shared input.

Since: 0.1.0

Definition at line 255 of file mdl_verify_tarball.c.

References internal_tar_feed(), internal_tar_finish(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_ok, priv_mdl_verify_io_read_up_to(), and RA8_PRIV.

Referenced by internal_verify_borrowed().

◆ priv_mdl_verify_workspace_take()

void * priv_mdl_verify_workspace_take	(	mdl_export_workspace_t *	workspace,
		size_t	bytes,
		size_t	alignment )

Reserve one aligned span from the verifier's caller-owned arena.

Rounds the bump cursor up to alignment, refuses a request that would leave the arena, and records the resulting high-water mark.

Parameters

[in,out]	workspace	Exclusive caller-owned bump arena.
[in]	bytes	Nonzero span extent to reserve.
[in]	alignment	Power-of-two alignment required by the caller.

Returns: Reserved span, or NULL when the request cannot be satisfied.

Return values

NULL	The request was malformed or the arena is exhausted.
other	One writable span of `bytes` bytes inside the arena.

Precondition: workspace is non-NULL and owns writable arena storage.; alignment is a nonzero power of two.

Postcondition: Success advances the arena cursor past the reserved span.; Failure leaves the arena cursor and high-water mark unchanged.

Note: Not thread-safe for a shared workspace.

Since: 0.1.0

Definition at line 30 of file mdl_verify.c.

References mdl_export_workspace::cap, mdl_export_workspace::data, mdl_export_workspace::high_water, memcpy(), and mdl_export_workspace::used.

Referenced by internal_gzip_init_inflate(), and priv_mdl_verify_arena_alloc().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_verify_limit_t

Function Documentation

◆ priv_mdl_verify_arena_alloc()

◆ priv_mdl_verify_arena_free()

◆ priv_mdl_verify_gzip_tar()

◆ priv_mdl_verify_io_read_up_to()

◆ priv_mdl_verify_is_image()

◆ priv_mdl_verify_safe_member_name()

◆ priv_mdl_verify_tar()

◆ priv_mdl_verify_workspace_take()