polyval: expose FieldElement under hazmat feature

.github/workflows/polyval.yml

@@ -22,15 +22,15 @@ env:
 
 jobs:
   # Ensure crate builds on a `no_std` target
-  build-no_std:
+  build-no-std:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
           targets: thumbv7em-none-eabi
-      - run: cargo check --target thumbv7em-none-eabi --release --features zeroize
+      - run: cargo check --target thumbv7em-none-eabi --release --all-features
 
   # Tests with CPU feature detection enabled
   test-autodetect:

polyval/Cargo.toml

@@ -15,12 +15,15 @@ categories = ["cryptography", "no-std"]
 rust-version = "1.85"
 edition = "2024"
 
+[features]
+hazmat = []
+
 [dependencies]
 cpubits = "0.1.0-rc.1"
 universal-hash = { version = "0.6.0-rc.8", default-features = false }
 zeroize = { version = "1", optional = true, default-features = false }
 
-[target.'cfg(any(target_arch = "aarch64", target_arch = "x86_64", target_arch = "x86"))'.dependencies]
+[target.'cfg(any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64"))'.dependencies]
 cpufeatures = "0.2"
 
 [dev-dependencies]

polyval/src/field_element.rs

@@ -28,9 +28,19 @@ use zeroize::Zeroize;
 /// - Multiplication is carryless
 ///
 /// [RFC8452 §3]: https://tools.ietf.org/html/rfc8452#section-3
-#[derive(Clone, Copy, Default, Eq, PartialEq)] // TODO(tarcieri): constant-time `*Eq`?
+#[derive(Clone, Copy, Default)]
+#[cfg_attr(test, derive(Eq, PartialEq))]
 #[repr(C, align(16))] // Make ABI and alignment compatible with SIMD registers
-pub(crate) struct FieldElement([u8; BLOCK_SIZE]);
+pub struct FieldElement([u8; BLOCK_SIZE]);
+
+impl FieldElement {
+    /// Reverse this field element at a byte-level of granularity.
+    ///
+    /// This is useful when implementing GHASH in terms of POLYVAL.
+    pub fn reverse(&mut self) {
+        self.0.reverse();
+    }
+}
 
 cfg_if! {
     if #[cfg(all(target_arch = "aarch64", not(polyval_backend = "soft")))] {
@@ -166,6 +176,7 @@ impl Add for FieldElement {
 impl Mul for FieldElement {
     type Output = Self;
 
+    /// Perform carryless multiplication within POLYVAL's field modulo its polynomial.
     #[inline]
     fn mul(self, rhs: Self) -> Self {
         soft::polymul(self, rhs)

polyval/src/hazmat.rs

@@ -0,0 +1,8 @@
+//! Hazardous materials: functionality which can be misused and needs to be used with care.
+//!
+//! <div class="warning">
+//! Functionality provided in this module is low-level and intended for constructing higher-level
+//! primitives as opposed to being used directly.
+//! </div>
+
+pub use crate::field_element::FieldElement;

polyval/src/lib.rs

@@ -6,6 +6,9 @@
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
 )]
 
+#[cfg(feature = "hazmat")]
+pub mod hazmat;
+
 mod field_element;
 mod mulx;