Clean-room gzip member decoder (RFC 1952) over the miniz DEFLATE core. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_decomp_limits.h"
#include "ra8_err.h"
#include "unarch_io.h"

Include dependency graph for unarch_gzip.h:

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

Go to the source code of this file.

Enumerations
enum	unarch_gzip_dims_t : uint16_t { k_unarch_gzip_sig_len = 2U , k_unarch_gzip_str_max = 2048U }
	Grammar sizes and fail-closed bounds of the gzip decoder. More...

Functions
bool	unarch_gzip_magic (const uint8_t *sig, size_t sig_len)
	Whether `sig` begins with the gzip member magic (1F 8B).
ra8_err_t	unarch_gzip_unwrap (unarch_read_fn read, void ctx, uint64_t size, uint8_t out, size_t out_cap, const ra8_decomp_limits_t limits, size_t out_len)
	Decode one whole gzip member from a read seam into a caller arena.

Detailed Description

Clean-room gzip member decoder (RFC 1952) over the miniz DEFLATE core.

Tag: [Ring 4 / Domain] {World: NS}

The gzip leg of the archive-hardening subsystem: a first-party RFC 1952 container parser wrapped around the vendored miniz tinfl DEFLATE decompressor (the same SOUP core the ZIP / RBKC paths already use). unarch_gzip_unwrap decodes exactly one gzip member fetched through the shared seek+read seam (unarch_io.h) into a caller arena:

The header is parsed fail-closed: magic, DEFLATE compression method, reserved flag bits rejected, bounded FEXTRA / FNAME / FCOMMENT fields, and the optional FHCRC header checksum verified when present.
The DEFLATE stream is inflated in bounded passes, each charged against the unified decompression-limits policy (ra8_decomp_limits.h): output cap, compression-ratio bound, iteration budget.
The trailer's CRC32 and ISIZE are both verified against the produced bytes, and trailing bytes after the member are rejected (no multi-member concatenation).

Clean-room licensing: The container grammar is written from RFC 1952; only the DEFLATE bitstream itself is delegated to the vendored miniz (see docs/SOUP/miniz.md). This wrapper is first-party MIT.

Note: Not thread-safe: the DEFLATE state is a module-static single-client arena (zero heap, NASA P10 Rule 3), serialised by the single-threaded reader loop.

See also: ra8_decomp_limits.h The policy every decode is charged against.; unarch_io.h The seek+read seam the decoder consumes.; unarch_tar.h The tar walker layered over unwrapped bytes.

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

Since: Version 0.1.0

Definition in file unarch_gzip.h.

Enumeration Type Documentation

◆ unarch_gzip_dims_t

enum unarch_gzip_dims_t : uint16_t

Grammar sizes and fail-closed bounds of the gzip decoder.

The fixed sizes come from RFC 1952; the string bound is this decoder's fail-closed limit on the optional NUL-terminated FNAME / FCOMMENT fields (a hostile header cannot stall the parser with an unterminated string).

Since: Version 0.1.0

Enumerator
k_unarch_gzip_sig_len	Magic length (1F 8B).
k_unarch_gzip_str_max	Max FNAME / FCOMMENT bytes accepted.

Definition at line 66 of file unarch_gzip.h.

Function Documentation

◆ unarch_gzip_magic()

bool unarch_gzip_magic	(	const uint8_t *	sig,
		size_t	sig_len )

nodiscard

Whether sig begins with the gzip member magic (1F 8B).

Pure signature probe so open paths can route a wrapped archive without constructing a decoder.

Parameters

[in]	sig	Leading archive bytes (may be NULL).
[in]	sig_len	Readable length of `sig` in bytes.

Returns: Whether the bytes begin a gzip member.

Return values

true	Both magic bytes match.
false	`sig` is NULL, too short, or not gzip.

Precondition: sig holds sig_len readable bytes when non-NULL.; sig_len is the true readable length (untrusted values are safe).

Postcondition: No state is modified (pure read).; The result depends only on the first two bytes.

Note: Thread-safe: pure read.

See also: unarch_gzip_unwrap()

Since: Version 0.1.0

Definition at line 422 of file unarch_gzip.c.

References k_gz_id1, k_gz_id2, k_gz_idx_id1, k_gz_idx_id2, and k_unarch_gzip_sig_len.

Referenced by comic_open_wrapped(), and internal_open_unwrapped().

◆ unarch_gzip_unwrap()

ra8_err_t unarch_gzip_unwrap	(	unarch_read_fn	read,
		void *	ctx,
		uint64_t	size,
		uint8_t *	out,
		size_t	out_cap,
		const ra8_decomp_limits_t *	limits,
		size_t *	out_len )

nodiscard

Decode one whole gzip member from a read seam into a caller arena.

Parses the RFC 1952 header, inflates the DEFLATE stream in bounded passes charged against limits, and verifies the trailer (payload CRC32 + ISIZE). Fail-closed on everything else: a non-gzip or non-DEFLATE header, reserved flag bits, oversized name/comment fields, a failed header or payload checksum, truncation, corruption, output overrun, a policy breach, and trailing bytes after the member.

Parameters

[in]	read	Byte reader over the gzip member (non-NULL).
[in]	ctx	Context passed to `read`.
[in]	size	Member length in bytes (> 0).
[out]	out	Destination arena (non-NULL, `out_cap` bytes).
[in]	out_cap	Capacity of `out` in bytes (> 0).
[in]	limits	Policy to enforce, or NULL for the default.
[out]	out_len	Receives the decoded byte count (non-NULL).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Member decoded and verified.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	`size` or `out_cap` is 0.
k_ra8_err_invalid_arg	`limits` has a zero field.
k_ra8_err_not_supported	Not gzip, not DEFLATE, or reserved flag bits set.
k_ra8_err_no_mem	`out` is too small for the member.
k_ra8_err_checksum_mismatch	Header FHCRC, payload CRC32, or ISIZE verification failed.
k_ra8_err_validation_failed	Truncated / corrupt stream, oversized header field, or trailing bytes after the member.
k_ra8_err_decomp_output_cap	Output exceeds the policy cap.
k_ra8_err_decomp_ratio	Output breached the ratio bound.
k_ra8_err_decomp_iterations	The decode loop budget ran out.

Precondition: read serves offsets [0, size) of the member.; No other gzip decode is in flight (module-static DEFLATE state).

Postcondition: On k_ra8_ok, out[0..*out_len) holds the decoded bytes.; On any error *out_len == 0.

Note: Not thread-safe (single-client DEFLATE state).

See also: unarch_gzip_magic()

Since: Version 0.1.0

Definition at line 437 of file unarch_gzip.c.

References gz_inflate_t::budget, gz_inflate_t::crc, gz_inflate_t::done, internal_inflate_pass(), internal_parse_header(), internal_verify_trailer(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, gz_inflate_t::out, gz_inflate_t::out_cap, RA8_CHECK_NULL_PTR, ra8_decomp_budget_init(), ra8_log_error, s_gz_inflator, gz_inflate_t::src, and gz_inflate_t::total.

Referenced by internal_unwrap().