[UPDATE] Minor cleanup

reactive-firewall · reactive-firewall · commit 96537eb3cc18 · 2025-09-18T14:54:26.000-07:00
* Fixed macros
* Refactored code to use macros
* added consistant 0-BSD headers
* SHA-2 Royalty-Free Patent Notice file just-in-case
* corrected CC-by-line from implementation author to patent holder (Clearification: Author's Code still 0BSD but some parts probably subject to the royalty-free U.S. Patent 6,829,355)
* added some coments to code
diff --git a/.PATENT-NOTE-6829355 b/.PATENT-NOTE-6829355
@@ -0,0 +1,6 @@
+The U.S. Government holds U.S. Patent 6,829,355 on the "Device for and method
+of
+one-way cryptographic hashing", which has been incorporated into Federal
+Information Processing Standard (FIPS) 180-2. This patent was issued on
+December 7, 2004. The National Security Agency has made U.S. Patent 6,829,355
+available royalty-free.
diff --git a/FeatherHash/sha2.c b/FeatherHash/sha2.c
@@ -1,6 +1,19 @@
 /* CC0 1.0 Universal - sha2.c
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
  Minimal SHA-256 and SHA-512 implementations per FIPS 180-4.
- No dynamic allocation. Portable C (C11/C14/C23). */
+ No dynamic allocation. Portable C (C11/C14/C23).
+*/
 #include "sha2.h"
 
 #if defined(__has_include)
@@ -20,11 +33,21 @@
 #endif /* !defined(__has_include) */
 
 /* --- Utility macros --- */
-static inline uint32_t rotr32(uint32_t x, unsigned n) {
+
+uint32_t rotr32(uint32_t x, unsigned n) {
+#if defined(__clang__) && __clang__ && __has_builtin(__builtin_rotateright32)
+	return __builtin_rotateright32(x, n);
+#else
 	return (x >> n) | (x << (32 - n));
+#endif
 }
-static inline uint64_t rotr64(uint64_t x, unsigned n) {
+
+uint64_t rotr64(uint64_t x, unsigned n) {
+#if defined(__clang__) && __clang__ && __has_builtin(__builtin_rotateright64)
+	return __builtin_rotateright64(x, n);
+#else
 	return (x >> n) | (x << (64 - n));
+#endif
 }
 
 /* --- SHA-256 implementation --- */
@@ -61,19 +84,13 @@ static void sha256_transform(uint32_t state[8], const uint8_t block[64]) {
 		((uint32_t)block[t*4 + 3]);
 	}
 	for (int t = 16; t < 64; ++t) {
-		uint32_t s0 = rotr32(w[t-15], 7) ^ rotr32(w[t-15], 18) ^ (w[t-15] >> 3);
-		uint32_t s1 = rotr32(w[t-2], 17) ^ rotr32(w[t-2], 19) ^ (w[t-2] >> 10);
-		w[t] = w[t-16] + s0 + w[t-7] + s1;
+		w[t] = w[t-16] + SIG0(w[t-15]) + w[t-7] + SIG1(w[t-2]);
 	}
 	uint32_t a = state[0], b = state[1], c = state[2], d = state[3];
 	uint32_t e = state[4], f = state[5], g = state[6], h = state[7];
 	for (int t = 0; t < 64; ++t) {
-		uint32_t S1 = rotr32(e, 6) ^ rotr32(e, 11) ^ rotr32(e, 25);
-		uint32_t ch = (e & f) ^ ((~e) & g);
-		uint32_t temp1 = h + S1 + ch + K256[t] + w[t];
-		uint32_t S0 = rotr32(a, 2) ^ rotr32(a, 13) ^ rotr32(a, 22);
-		uint32_t maj = (a & b) ^ (a & c) ^ (b & c);
-		uint32_t temp2 = S0 + maj;
+		uint32_t temp1 = h + EP1(e) + CH(e,f,g) + K256[t] + w[t];
+		uint32_t temp2 = EP0(a) + MAJ(a, b, c);
 		h = g; g = f; f = e; e = d + temp1;
 		d = c; c = b; b = a; a = temp1 + temp2;
 	}
diff --git a/FeatherHash/sha2.h b/FeatherHash/sha2.h
@@ -1,7 +1,52 @@
 /* CC0 1.0 Universal - sha2.h
- Public domain / CC0. Minimal SHA-2 declarations for sha256/sha384/sha512.
- */
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+ Minimal SHA-2 declarations for sha256/sha384/sha512.
+*/
 #ifndef FEATHERHASH_SHA2_H
+
+/*!
+ @header sha2.h
+ @discussion
+ Lightweight, portable SHA-256 implementation (API only). This component provides three primary functions:
+ - sha256_init: initialize a context
+ - sha256_update: feed bytes into the running hash
+ - sha256_final: finalize and produce the 32-byte digest
+
+ The implementation is intentionally compact and suitable for embedded or utility code. It does not allocate dynamic memory and assumes a little- or big-endian-independent byte-level input (the algorithm itself works with big-endian message words).
+
+ The API operates on a caller-allocated sha256_ctx structure, defined as: ``sha256_ctx``.
+
+ Thread safety:
+ - Each sha256_ctx instance may be used by one thread at a time. The functions do not use global mutable state.
+
+ Security notes:
+ - The implementation zeroes the context in sha256_final to reduce lifetime of sensitive intermediate state.
+ - The implementation is not hardened against side-channel attacks (timing, cache). Do not use for high-security requirements without appropriate hardening.
+
+ Usage example:
+ @code
+ sha256_ctx ctx;
+ uint8_t digest[32];
+ const uint8_t *data = ...;
+ size_t len = ...;
+
+ sha256_init(&ctx);
+ sha256_update(&ctx, data, len);
+ sha256_final(&ctx, digest);
+ @endcode
+*/
+
 #if defined(__clang__) && __clang__
 #pragma mark -
 #pragma mark sha2Header
@@ -51,24 +96,109 @@
 extern "C" {
 #endif /* !defined(__cplusplus) */
 
+#if defined(__clang__) && __clang__
+#pragma mark -
+#pragma mark Utility Functions
+#endif /* !__clang__ */
+
+/**!
+ Rotate-32 operation utility.
+
+ - Discussion:  This version is an intuitive bitwise OR of right shifted bits and the left shifted 'overflow' bits (e.g., "carried over" if you will).
+ There are certainly better versions out there than this lightweight implementation, but this version is intended for stage0 toolchains
+ after all.
+
+ - Parameter x: The ``uint32_t`` value to rotate right (32 bits).
+ - Parameter n: The ``unsigned`` distance to rotate right by.
+ - seealso: A more [general form](https://stackoverflow.com/a/776523) (that one is CC-BY-SA-4.0)
+ - seealso: The two academic implementation of identical form (a cool coincidence)
+ * By John Regehr (Publicly available academic implementation; unknown copyright)
+ on [his blog](https://blog.regehr.org/archives/1063)
+ * And by Brad Conte (public domain implementation)
+ on [his github](https://github.com/B-Con/crypto-algorithms/blob/cfbde48414baacf51fc7c74f275190881f037d32/sha256.c#L22)
+ - seealso: ``rotr64``
+ - seealso: clang's built-in [builtin_rotateright32](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-rotateright)
+ */
+static inline uint32_t rotr32(uint32_t x, unsigned n);
+
+/**!
+ Rotate-64 operation utility.
+
+ - Discussion:  This version is an intuitive bitwise OR of right shifted bits and the left shifted 'overflow' bits (e.g., "carried over" if you will).
+ There are certainly better versions out there than this lightweight implementation, but this version is intended for stage0 toolchains
+ after all.
+
+ - Parameter x: The ``uint64_t`` value to rotate right (64 bits).
+ - Parameter n: The ``unsigned`` distance to rotate right by.
+ - seealso: A more [general form](https://stackoverflow.com/a/776523) (that one is CC-BY-SA-4.0)
+ - seealso: ``rotr32``
+ - seealso: clang's built-in [builtin_rotateright32](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-rotateright)
+ */
+static inline uint64_t rotr64(uint64_t x, unsigned n);
+
+#if defined(__clang__) && __clang__
+#pragma mark -
+#pragma mark Secure Hash Algorithm Functions
+#endif /* !__clang__ */
+
 /* Context sizes:
  - SHA-256: block 64, state 8 x uint32_t
  - SHA-512/384: block 128, state 8 x uint64_t
  */
 
 /* SHA-256 */
 struct _sha256_ctx {
-	uint32_t state[8];
-	uint64_t bitlen;
-	uint8_t buf[64];
-	size_t buflen;
+	uint32_t state[8]; /* internal state (A..H) */
+	uint64_t bitlen;   /* total number of message bits processed */
+	uint8_t buf[64];   /* partial-block buffer */
+	size_t buflen;     /* number of bytes currently in buf */
 };
 typedef struct _sha256_ctx sha256_ctx;
 
+/*!
+ Initialize a ``sha256_ctx`` to begin hashing a new message.
+
+ The function sets initial state, zeroes counters and buffer length. Must be
+ called before ``sha256_update`` / ``sha256_final``.
+
+ - Parameter c: Pointer to caller-allocated ``sha256_ctx``.
+ */
 void sha256_init(sha256_ctx *c);
+
+/*!
+ Process input bytes into the running SHA-256 computation.
+
+ This function may be called multiple times to process streaming data.
+ - The function updates the context's internal bit length and buffers partial blocks.
+ - When a full 64-byte block is accumulated, it is processed immediately.
+ - The caller remains responsible for supplying all message bytes; call ``sha256_final`` to produce the digest.
+
+ - Parameter c: Pointer to an initialized ``sha256_ctx``.
+ - Parameter data: Pointer to input bytes; may be ``NULL`` only when `len` is 0.
+ - Parameter len: The ``size_t`` of bytes to process.
+ */
 void sha256_update(sha256_ctx *c, const void *data, size_t len);
+
+/*!
+ Finalize hashing and write the 32-byte (256-bit) digest in big-endian order to out.
+
+ After this call, the context is zeroed and must be re-initialized with ``sha256_init`` before reuse.
+
+ - Parameter c: Pointer to a ``sha256_ctx`` previously passed to ``sha256_init`` and ``sha256_update``.
+ - Parameter out: Pointer to a 32-byte buffer (e.g., `uint8_t[32]`) that will receive the digest.
+*/
 void sha256_final(sha256_ctx *c, uint8_t out[32]);
 
+/* --- Internal notes (for maintainers) ---
+ - K256: round constants per FIPS-180-4.
+ - sha256_transform: processes a single 512-bit block and updates 'state'.
+ - The message schedule w[0..63] is computed in-place; SIG0/SIG1/EP0/EP1/CH/MAJ are provided as macros.
+ - Endianness: input bytes are combined to big-endian 32-bit words in sha256_transform.
+ - The implementation appends the 64-bit message length in big-endian as required by the spec.
+ - Zeroing the sha256_ctx in sha256_final includes state, counters and buffer to limit exposure of intermediate values.
+ - Keep the transform function static/internal to prevent inadvertent external use.
+ */
+
 /* SHA-512 core (used for SHA-512 and SHA-384) */
 typedef struct {
 	uint64_t state[8];
@@ -86,24 +216,56 @@ void sha512_final(sha512_ctx *c, uint8_t out[64]);
 }
 #endif /* !defined(__cplusplus) */
 
-#endif /* FEATHERHASH_SHA2_H */
+/* --- SHA-256 helper macros --- */
+#ifndef FEATHERHASH_SHA2_MACROS
 
+#if defined(__clang__) && __clang__
+#pragma mark -
+#pragma mark SHA2 Macros
+#endif /* !__clang__ */
 
 #if defined(HAS_TYPEOF) && HAS_TYPEOF
-#define ROTLEFT(a, b) ({ __typeof__(a) __temp_a = (a); __typeof__(b) __temp_b = (b); ((__temp_a << __temp_b) | (__temp_a >> ((sizeof(__temp_a) * 8) - __temp_b))); })
-#define ROTRIGHT(a, b) ({ __typeof__(a) __temp_a = (a); __typeof__(b) __temp_b = (b); ((__temp_a >> __temp_b) | (__temp_a << ((sizeof(__temp_a) * 8) - __temp_b))); })
+// ROT32 left and right helper macros
+#define ROTLEFT(a, b) ({ __typeof__(a) __temp_a = (a); __typeof__(b) __temp_b = (b); (__typeof__(a))(rotl32(__temp_a, __temp_b)); })
+#define ROTRIGHT(a, b) ({ __typeof__(a) __temp_a = (a); __typeof__(b) __temp_b = (b); (__typeof__(a))(rotr32(__temp_a, __temp_b)); })
 
+// W to SIG?() with x,y,z helper macros
+#define WTSIG(w, x, y, z) ({ __typeof__(w) __temp_w = (w); __typeof__(x) __temp_x = (x); __typeof__(y) __temp_y = (y); __typeof__(z) __temp_z = (z); (__typeof__(w))((ROTRIGHT(__temp_w, __temp_x) ^ ROTRIGHT(__temp_w, __temp_y)) ^ (__temp_w >> __temp_z)); })
+// W to EP?() with x,y,z helper macros
+#define WTEP(w, x, y, z) ({ __typeof__(w) __temp_w = (w); __typeof__(x) __temp_x = (x); __typeof__(y) __temp_y = (y); __typeof__(z) __temp_z = (z); (__typeof__(w))((ROTRIGHT(__temp_w, __temp_x) ^ ROTRIGHT(__temp_w, __temp_y)) ^ ROTRIGHT(__temp_w, __temp_z)); })
+// SHA-2 EPx functions
+#define EP0(n) ({ __typeof__(n) __temp_n = (n); (__typeof__(n))(WTEP(__temp_n, 2, 13, 22)); })
+#define EP1(n) ({ __typeof__(n) __temp_n = (n); (__typeof__(n))(WTEP(__temp_n, 6, 11, 25)); })
+// SHA-2 SIGx functions
+#define SIG0(n) ({ __typeof__(n) __temp_n = (n); (__typeof__(n))(WTSIG(__temp_n, 7, 18, 3)); })
+#define SIG1(n) ({ __typeof__(n) __temp_n = (n); (__typeof__(n))(WTSIG(__temp_n, 17, 19, 10)); })
+// SHA-2 CH function
 #define CH(x, y, z) ({ __typeof__(x) __temp_x = (x); __typeof__(y) __temp_y = (y); __typeof__(z) __temp_z = (z); ((__temp_x & __temp_y) ^ (~__temp_x & __temp_z)); })
+// SHA-2 MAJ function
 #define MAJ(x, y, z) ({ __typeof__(x) __temp_x = (x); __typeof__(y) __temp_y = (y); __typeof__(z) __temp_z = (z); ((__temp_x & __temp_y) ^ (__temp_x & __temp_z) ^ (__temp_y & __temp_z)); })
 #else /* !HAS_TYPEOF */
 // Fallback implementation without __typeof__
-#define ROTLEFT(a,b) (((a) << (b)) | ((a) >> ((32)-(b))))
-#define ROTRIGHT(a,b) (((a) >> (b)) | ((a) << ((32)-(b))))
+#define ROTLEFT(a, b) (rotl32((a), (b)))
+#define ROTRIGHT(a, b) (rotr32((a), (b)))
+
+// W to SIG?() with x,y,z helper macro
+#define WTSIG(w, x, y, z) ((ROTRIGHT((w), (x)) ^ ROTRIGHT((w), (y))) ^ ((w) >> (z)))
+// W to EP?() with x,y,z helper macros
+#define WTEP(w, x, y, z) ((ROTRIGHT((w), (x)) ^ ROTRIGHT((w), (y))) ^ ROTRIGHT((w), (z)))
+// SHA-2 EPx functions
+#define EP0(n) (WTEP(n,7,18,3))
+#define EP1(n) (WTEP(n,17,19,10))
+// SHA-2 SIGx functions
+#define SIG0(n) (WTSIG(n,7,18,3))
+#define SIG1(n) (WTSIG(n,17,19,10))
+// SHA-2 CH function
 #define CH(x, y, z) (((x) & (y)) ^ (~(x) & (z)))
+// SHA-2 MAJ function
 #define MAJ(x, y, z) (((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z)))
 #endif /* !defined(HAS_TYPEOF) */
 
-#define EP0(x) (ROTRIGHT(x,2) ^ ROTRIGHT(x,13) ^ ROTRIGHT(x,22))
-#define EP1(x) (ROTRIGHT(x,6) ^ ROTRIGHT(x,11) ^ ROTRIGHT(x,25))
-#define SIG0(x) (ROTRIGHT(x,7) ^ ROTRIGHT(x,18) ^ ((x) >> 3))
-#define SIG1(x) (ROTRIGHT(x,17) ^ ROTRIGHT(x,19) ^ ((x) >> 10))
+#define FEATHERHASH_SHA2_MACROS ""
+
+#endif /* FEATHERHASH_SHA2_MACROS */
+
+#endif /* FEATHERHASH_SHA2_H */
diff --git a/FeatherHash/sha256sum.c b/FeatherHash/sha256sum.c
@@ -1,4 +1,16 @@
 /* CC0 1.0 Universal - sha256sum.c
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
  Minimal sha256sum command-line utility. */
 #include "sha2.h"
 #include "feather.h"
diff --git a/FeatherHash/sha384sum.c b/FeatherHash/sha384sum.c
@@ -1,4 +1,16 @@
 /* CC0 1.0 Universal - sha384sum.c
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
    Minimal sha384sum command-line utility. Implements SHA-384 by using SHA-512 core
    with SHA-384 initial IV and truncating output to 48 bytes. */
 #include "sha2.h"
diff --git a/FeatherHash/sha512sum.c b/FeatherHash/sha512sum.c
@@ -1,4 +1,16 @@
 /* CC0 1.0 Universal - sha512sum.c
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
  Minimal sha512sum command-line utility. */
 #include "sha2.h"
 #include "feather.h"
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (C) 2025 by Mr. Walls
+Copyright (C) 2004 by "The United States of America as represented by the National Security Agency" <wtnewbi@tycho.ncsc.mil>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.
diff --git a/dockerfile b/dockerfile
@@ -33,6 +33,7 @@ RUN apk update && \
 COPY build-featherHash.sh /FeatherHash/build-featherHash.sh
 COPY FeatherHash/* /FeatherHash/FeatherHash/
 COPY LICENSE /FeatherHash/LICENSE
+COPY LICENSE /FeatherHash/.PATENT-NOTE-6829355
 
 # Set the working directory inside the container
 WORKDIR /FeatherHash
@@ -70,5 +71,6 @@ LABEL org.opencontainers.image.licenses="0BSD"
 
 COPY --from=featherhash-bellows /FeatherHash/out/bin /bin
 COPY --from=featherhash-bellows /FeatherHash/LICENSE /LICENSE
+COPY --from=featherhash-bellows /FeatherHash/.PATENT-NOTE-6829355 /.PATENT-NOTE-6829355
 
 ENTRYPOINT ["/bin/sha256sum"]

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Copyright (C) 2025 by Mr. Walls`
	`1`	`+Copyright (C) 2004 by "The United States of America as represented by the National Security Agency" <wtnewbi@tycho.ncsc.mil>`
`2`	`2`
`3`	`3`	`Permission to use, copy, modify, and/or distribute this software for any`
`4`	`4`	`purpose with or without fee is hereby granted.`