Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
sha256fst.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef SHA256FST_H
19#define SHA256FST_H
20
21/**
22 * @file sha256fst.h
23 * @brief Allocation-free, portable SHA-256 checksums for memory and streams.
24 * @details Use sha256_hex() or sha256_bytes() for a complete memory region.
25 * For a stream, initialize a context, append any number of chunks, then call
26 * exactly one finalizer. Reinitialize before hashing another message.
27 *
28 * Context storage belongs to the caller. Separate contexts can be used
29 * concurrently; sharing one context requires external synchronization.
30 * Inputs need no special alignment. The same digest bytes are produced on
31 * x86 and ARM64 without hardware crypto instructions or host-endian casts.
32 * @pre Total input length must be less than 2^64 bits, as required by SHA-256.
33 * @warning A checksum detects changes but does not authenticate a producer.
34 */
35
36#include <stddef.h>
37#include <stdbool.h>
38#include <stdint.h>
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/** @brief Number of input bytes in one SHA-256 compression block. */
45#define SHA256_BLOCK_SIZE 64
46/** @brief Required hexadecimal output capacity, including the trailing NUL. */
47#define SHA256_HEX_SIZE 65
48/** @brief Required binary output capacity; binary digests have no terminator. */
49#define SHA256_BYTES_SIZE 32
50
51/**
52 * @brief Caller-owned incremental checksum state; treat members as read-only.
53 * @details The layout is retained for existing C and C++ consumers. Only
54 * buffer_counter bytes of buffer are valid before finalization; initialization
55 * deliberately does not clear unused buffer storage. No input pointer is kept.
56 */
57typedef struct sha256 {
58 uint32_t state[8]; /**< Chaining words; the finalizer replaces these with the digest. */
59 uint8_t buffer[SHA256_BLOCK_SIZE]; /**< Pending partial block or final padding block. */
60 uint64_t n_bits; /**< Original message length in bitch, excluding padding. */
61 uint8_t buffer_counter; /**< Pending byte count, always below SHA256_BLOCK_SIZE between calls. */
63
64/**
65 * @brief Initialize or reset a context for a new message.
66 * @param[out] context Writable caller-owned context.
67 * @note Initialization is not a secure erasure of previous buffer contents.
68 */
69void sha256_init(struct sha256 *context);
70
71/**
72 * @brief Append one byte to an unfinished message.
73 * @param[in,out] context Initialized context that has not been finalized.
74 * @param byte Next input byte.
75 * @note Prefer sha256_append() for chunks to use its direct-block fast path.
76 */
77void sha256_append_byte(struct sha256 *context, uint8_t byte);
78
79/**
80 * @brief Append an arbitrarily aligned chunk; empty chunks are harmless.
81 * @param[in,out] context Initialized context that has not been finalized.
82 * @param[in] data Readable input of at least length bytes; may be NULL only when length is zero.
83 * @param length Number of bytes to consume.
84 * @pre The input region must not overlap context storage.
85 * @details Complete blocks are compressed directly from data. Only partial
86 * blocks are copied into the bounded context buffer; no input is retained.
87 */
88void sha256_append(struct sha256 *context, const void *data, size_t length);
89
90/**
91 * @brief Finish a message, leaving its eight digest words in context->state.
92 * @param[in,out] context Initialized context that has not been finalized.
93 * @details This consumes the context. Read the final state if needed, then
94 * reinitialize; do not append or call another finalizer on the same message.
95 * n_bits retains the original input length and buffer_counter becomes zero.
96 */
97void sha256_finalize(struct sha256 *context);
98
99/**
100 * @brief Finish a message and write its lowercase hexadecimal digest.
101 * @param[in,out] context Initialized context that has not been finalized.
102 * @param[out] output Writable SHA256_HEX_SIZE-byte region, including the trailing NUL.
103 * @pre Output must not overlap context storage.
104 * @note This consumes the context, just like sha256_finalize().
105 */
106void sha256_finalize_hex(struct sha256 *context, char *output);
107
108/**
109 * @brief Finish a message and write its standard big-endian digest bytes.
110 * @param[in,out] context Initialized context that has not been finalized.
111 * @param[out] output Writable SHA256_BYTES_SIZE-byte region, with no trailing NUL.
112 * @pre Output must not overlap context storage.
113 * @note This consumes the context, just like sha256_finalize().
114 */
115void sha256_finalize_bytes(struct sha256 *context, void *output);
116
117/**
118 * @brief Hash one memory region to a lowercase hexadecimal string.
119 * @param[in] data Readable input of at least length bytes; may be NULL only when length is zero.
120 * @param length Input byte count.
121 * @param[out] output Writable SHA256_HEX_SIZE-byte region, including the trailing NUL.
122 * @details Uses a temporary stack context. Output may overlap the input because
123 * all input is consumed before the digest is written.
124 */
125void sha256_hex(const void *data, size_t length, char *output);
126
127/**
128 * @brief Hash one memory region to its standard 32-byte binary digest.
129 * @param[in] data Readable input of at least length bytes; may be NULL only when length is zero.
130 * @param length Input byte count.
131 * @param[out] output Writable SHA256_BYTES_SIZE-byte region, with no trailing NUL.
132 * @details Uses a temporary stack context; output may overlap the input.
133 */
134void sha256_bytes(const void *data, size_t length, void *output);
135/** @brief Hash an immutable nonempty regular file with bounded streaming scratch.
136 * @param filename Input whose size/identity/mtime must remain stable during the read.
137 * @param output Writable SHA256_HEX_SIZE bytes, meaningful only after success.
138 * @return True after a complete stable read and close, false for I/O or observed mutation.
139 * @note Integrity is not authentication; the producer still owns file/path stability. */
140bool sha256_file(const char *filename, char output[SHA256_HEX_SIZE]);
141
142#ifdef __cplusplus
143}
144#endif
145
146#endif
static FILE * output
Definition pose_log.c:77
void sha256_bytes(const void *data, size_t length, void *output)
Hash one memory region to its standard 32-byte binary digest.
Definition sha256fst.c:279
void sha256_append_byte(struct sha256 *context, uint8_t byte)
Append one byte to an unfinished message.
Definition sha256fst.c:181
bool sha256_file(const char *filename, char output[SHA256_HEX_SIZE])
Hash an immutable nonempty regular file with bounded streaming scratch.
Definition sha256fst.c:286
void sha256_hex(const void *data, size_t length, char *output)
Hash one memory region to a lowercase hexadecimal string.
Definition sha256fst.c:272
void sha256_finalize_hex(struct sha256 *context, char *output)
Finish a message and write its lowercase hexadecimal digest.
Definition sha256fst.c:249
void sha256_finalize(struct sha256 *context)
Finish a message, leaving its eight digest words in context->state.
Definition sha256fst.c:226
#define SHA256_BLOCK_SIZE
Number of input bytes in one SHA-256 compression block.
Definition sha256fst.h:45
void sha256_append(struct sha256 *context, const void *data, size_t length)
Append an arbitrarily aligned chunk; empty chunks are harmless.
Definition sha256fst.c:190
void sha256_init(struct sha256 *context)
Initialize or reset a context for a new message.
Definition sha256fst.c:168
#define SHA256_HEX_SIZE
Required hexadecimal output capacity, including the trailing NUL.
Definition sha256fst.h:47
void sha256_finalize_bytes(struct sha256 *context, void *output)
Finish a message and write its standard big-endian digest bytes.
Definition sha256fst.c:262
Caller-owned incremental checksum state; treat members as read-only.
Definition sha256fst.h:57
uint8_t buffer[SHA256_BLOCK_SIZE]
Definition sha256fst.h:59
uint32_t state[8]
Definition sha256fst.h:58
uint8_t buffer_counter
Definition sha256fst.h:61
uint64_t n_bits
Definition sha256fst.h:60