Allocation-free, portable SHA-256 checksums for memory and streams. More...
#include <stddef.h>#include <stdbool.h>#include <stdint.h>

Go to the source code of this file.
Data Structures | |
| struct | sha256 |
| Caller-owned incremental checksum state; treat members as read-only. More... | |
Macros | |
| #define | SHA256_BLOCK_SIZE 64 |
| Number of input bytes in one SHA-256 compression block. | |
| #define | SHA256_HEX_SIZE 65 |
| Required hexadecimal output capacity, including the trailing NUL. | |
| #define | SHA256_BYTES_SIZE 32 |
| Required binary output capacity; binary digests have no terminator. | |
Typedefs | |
| typedef struct sha256 | sha256 |
| Caller-owned incremental checksum state; treat members as read-only. | |
Functions | |
| void | sha256_init (struct sha256 *context) |
| Initialize or reset a context for a new message. | |
| void | sha256_append_byte (struct sha256 *context, uint8_t byte) |
| Append one byte to an unfinished message. | |
| void | sha256_append (struct sha256 *context, const void *data, size_t length) |
| Append an arbitrarily aligned chunk; empty chunks are harmless. | |
| void | sha256_finalize (struct sha256 *context) |
| Finish a message, leaving its eight digest words in context->state. | |
| void | sha256_finalize_hex (struct sha256 *context, char *output) |
| Finish a message and write its lowercase hexadecimal digest. | |
| void | sha256_finalize_bytes (struct sha256 *context, void *output) |
| Finish a message and write its standard big-endian digest bytes. | |
| void | sha256_hex (const void *data, size_t length, char *output) |
| Hash one memory region to a lowercase hexadecimal string. | |
| void | sha256_bytes (const void *data, size_t length, void *output) |
| Hash one memory region to its standard 32-byte binary digest. | |
| bool | sha256_file (const char *filename, char output[SHA256_HEX_SIZE]) |
| Hash an immutable nonempty regular file with bounded streaming scratch. | |
Detailed Description
Allocation-free, portable SHA-256 checksums for memory and streams.
Use sha256_hex() or sha256_bytes() for a complete memory region. For a stream, initialize a context, append any number of chunks, then call exactly one finalizer. Reinitialize before hashing another message.
Context storage belongs to the caller. Separate contexts can be used concurrently; sharing one context requires external synchronization. Inputs need no special alignment. The same digest bytes are produced on x86 and ARM64 without hardware crypto instructions or host-endian casts.
- Precondition
- Total input length must be less than 2^64 bits, as required by SHA-256.
- Warning
- A checksum detects changes but does not authenticate a producer.
Definition in file sha256fst.h.
Macro Definition Documentation
◆ SHA256_BLOCK_SIZE
| #define SHA256_BLOCK_SIZE 64 |
Number of input bytes in one SHA-256 compression block.
Definition at line 45 of file sha256fst.h.
◆ SHA256_BYTES_SIZE
| #define SHA256_BYTES_SIZE 32 |
Required binary output capacity; binary digests have no terminator.
Definition at line 49 of file sha256fst.h.
◆ SHA256_HEX_SIZE
| #define SHA256_HEX_SIZE 65 |
Required hexadecimal output capacity, including the trailing NUL.
Definition at line 47 of file sha256fst.h.
Typedef Documentation
◆ sha256
| typedef struct sha256 sha256 |
Caller-owned incremental checksum state; treat members as read-only.
The layout is retained for existing C and C++ consumers. Only buffer_counter bytes of buffer are valid before finalization; initialization deliberately does not clear unused buffer storage. No input pointer is kept.
Function Documentation
◆ sha256_append()
| void sha256_append | ( | struct sha256 * | context, |
| const void * | data, | ||
| size_t | length ) |
Append an arbitrarily aligned chunk; empty chunks are harmless.
- Parameters
-
[in,out] context Initialized context that has not been finalized. [in] data Readable input of at least length bytes; may be NULL only when length is zero. length Number of bytes to consume.
- Precondition
- The input region must not overlap context storage.
Complete blocks are compressed directly from data. Only partial blocks are copied into the bounded context buffer; no input is retained.
Definition at line 190 of file sha256fst.c.
◆ sha256_append_byte()
| void sha256_append_byte | ( | struct sha256 * | context, |
| uint8_t | byte ) |
Append one byte to an unfinished message.
- Parameters
-
[in,out] context Initialized context that has not been finalized. byte Next input byte.
- Note
- Prefer sha256_append() for chunks to use its direct-block fast path.
Definition at line 181 of file sha256fst.c.
◆ sha256_bytes()
| void sha256_bytes | ( | const void * | data, |
| size_t | length, | ||
| void * | output ) |
Hash one memory region to its standard 32-byte binary digest.
- Parameters
-
[in] data Readable input of at least length bytes; may be NULL only when length is zero. length Input byte count. [out] output Writable SHA256_BYTES_SIZE-byte region, with no trailing NUL.
Uses a temporary stack context; output may overlap the input.
Definition at line 279 of file sha256fst.c.
◆ sha256_file()
| bool sha256_file | ( | const char * | filename, |
| char | output[SHA256_HEX_SIZE] ) |
Hash an immutable nonempty regular file with bounded streaming scratch.
- Parameters
-
filename Input whose size/identity/mtime must remain stable during the read. output Writable SHA256_HEX_SIZE bytes, meaningful only after success.
- Returns
- True after a complete stable read and close, false for I/O or observed mutation.
- Note
- Integrity is not authentication; the producer still owns file/path stability.
Definition at line 286 of file sha256fst.c.
◆ sha256_finalize()
| void sha256_finalize | ( | struct sha256 * | context | ) |
Finish a message, leaving its eight digest words in context->state.
- Parameters
-
[in,out] context Initialized context that has not been finalized.
This consumes the context. Read the final state if needed, then reinitialize; do not append or call another finalizer on the same message. n_bits retains the original input length and buffer_counter becomes zero.
Definition at line 226 of file sha256fst.c.
◆ sha256_finalize_bytes()
| void sha256_finalize_bytes | ( | struct sha256 * | context, |
| void * | output ) |
Finish a message and write its standard big-endian digest bytes.
- Parameters
-
[in,out] context Initialized context that has not been finalized. [out] output Writable SHA256_BYTES_SIZE-byte region, with no trailing NUL.
- Precondition
- Output must not overlap context storage.
- Note
- This consumes the context, just like sha256_finalize().
Definition at line 262 of file sha256fst.c.
◆ sha256_finalize_hex()
| void sha256_finalize_hex | ( | struct sha256 * | context, |
| char * | output ) |
Finish a message and write its lowercase hexadecimal digest.
- Parameters
-
[in,out] context Initialized context that has not been finalized. [out] output Writable SHA256_HEX_SIZE-byte region, including the trailing NUL.
- Precondition
- Output must not overlap context storage.
- Note
- This consumes the context, just like sha256_finalize().
Definition at line 249 of file sha256fst.c.
◆ sha256_hex()
| void sha256_hex | ( | const void * | data, |
| size_t | length, | ||
| char * | output ) |
Hash one memory region to a lowercase hexadecimal string.
- Parameters
-
[in] data Readable input of at least length bytes; may be NULL only when length is zero. length Input byte count. [out] output Writable SHA256_HEX_SIZE-byte region, including the trailing NUL.
Uses a temporary stack context. Output may overlap the input because all input is consumed before the digest is written.
Definition at line 272 of file sha256fst.c.
◆ sha256_init()
| void sha256_init | ( | struct sha256 * | context | ) |
Initialize or reset a context for a new message.
- Parameters
-
[out] context Writable caller-owned context.
- Note
- Initialization is not a secure erasure of previous buffer contents.
Definition at line 168 of file sha256fst.c.