constant_time: Introduce LeakyWord.

Introduce a new type alias for words that are not intended to be
secret, and clarify some aspects of `Word` and the new `LeakyWord`.

src/constant_time.rs

@@ -17,9 +17,10 @@
 use crate::{c, error};
 
 mod boolmask;
+mod leaky;
 mod word;
 
-pub(crate) use self::{boolmask::BoolMask, word::Word};
+pub(crate) use self::{boolmask::BoolMask, leaky::LeakyWord, word::Word};
 
 /// Returns `Ok(())` if `a == b` and `Err(error::Unspecified)` otherwise.
 /// The comparison of `a` and `b` is done in constant time with respect to the

src/constant_time/leaky.rs

@@ -0,0 +1,27 @@
+// Copyright 2015-2024 Brian Smith.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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.
+
+#[cfg(target_pointer_width = "64")]
+type CompilerWord = u64;
+
+#[cfg(target_pointer_width = "32")]
+type CompilerWord = u32;
+
+/// A native word that isn't secret.
+///
+/// `LeakyWord` supports `as` conversions to/from native types.
+///
+/// XXX: This isn't the native word size on targets where a pointer isn't the
+/// same size as a native word. TODO: Fix this.
+pub(crate) type LeakyWord = CompilerWord;

src/constant_time/word.rs

@@ -1,4 +1,4 @@
-// Copyright 2015-2016 Brian Smith.
+// Copyright 2015-2024 Brian Smith.
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted, provided that the above
@@ -12,8 +12,33 @@
 // OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 // CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-#[cfg(target_pointer_width = "64")]
-pub(crate) type Word = u64;
+use super::LeakyWord;
 
-#[cfg(target_pointer_width = "32")]
-pub(crate) type Word = u32;
+/// A native word that may hold a secret.
+///
+/// XXX: Currently this is a type alias of `LeakyWord` so it doesn't enforce,
+/// except by convention, the prevention of leaks. This is a temporary state to
+/// support the refactorings that will
+///
+/// XXX: This isn't the native word size on targets where a pointer isn't the
+/// same size as a native word. TODO: Fix this.
+///
+/// XXX: Over time, we'll evolve Word into a newtype with an API that minimizes
+/// leaks and makes all leaks explicit, like so:
+pub(crate) type Word = LeakyWord;
+
+/* TODO:
+#[repr(transparent)]
+pub(crate) struct Word(LeakyWord);
+
+impl Word {
+    pub fn leak_word(self) -> LeakyWord { self.0 }
+}
+
+impl From<LeakyWord> for Word {
+    fn from(w: LeakyWord) -> Self {
+        // TODO: Use a stronger `black_box`.
+        Self(core::hint::black_box(w))
+    }
+}
+*/