#![no_std]
#![deny(unsafe_code)]
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
extern crate alloc;
use alloc::{boxed::Box, string::String, vec::Vec};
use core::{
any, fmt,
mem::{size_of, MaybeUninit},
};
use sanitization::{ct, SecureSanitize};
#[cfg(feature = "serde")]
use serde::{de, ser, Deserialize, Serialize};
#[cfg(feature = "zeroize-interop")]
pub use zeroize;
pub struct SecretBox<S: SecureSanitize + ?Sized> {
inner_secret: Box<S>,
}
impl<S: SecureSanitize + ?Sized> SecretBox<S> {
#[must_use]
#[inline]
pub const fn new(boxed_secret: Box<S>) -> Self {
Self {
inner_secret: boxed_secret,
}
}
#[inline]
pub fn clear_secret(&mut self) {
self.inner_secret.secure_sanitize();
}
#[inline]
pub fn into_cleared(self) {
drop(self);
}
}
impl<S: sanitization::StableMutableSecretStorage + Default> SecretBox<S> {
#[must_use]
#[inline]
pub fn init_with_mut(initialize: impl FnOnce(&mut S)) -> Self {
let mut secret = Self::default();
initialize(secret.expose_secret_mut());
secret
}
#[inline]
pub fn try_init_with_mut<E>(
initialize: impl FnOnce(&mut S) -> Result<(), E>,
) -> Result<Self, E> {
let mut secret = Self::default();
initialize(secret.expose_secret_mut())?;
Ok(secret)
}
}
impl<S: CloneableSecret> SecretBox<S> {
#[must_use]
#[inline]
pub fn init_with(construct: impl FnOnce() -> S) -> Self {
let temporary = TemporarySecret::new(construct());
Self::new(Box::new(temporary.value().clone()))
}
#[inline]
pub fn try_init_with<E>(construct: impl FnOnce() -> Result<S, E>) -> Result<Self, E> {
let temporary = TemporarySecret::new(construct()?);
Ok(Self::new(Box::new(temporary.value().clone())))
}
}
impl<S: SecureSanitize + ?Sized> From<Box<S>> for SecretBox<S> {
#[inline]
fn from(source: Box<S>) -> Self {
Self::new(source)
}
}
impl<S: SecureSanitize + Default> Default for SecretBox<S> {
#[inline]
fn default() -> Self {
Self::new(Box::<S>::default())
}
}
impl<S: SecureSanitize + ?Sized> SecureSanitize for SecretBox<S> {
#[inline]
fn secure_sanitize(&mut self) {
self.clear_secret();
}
}
#[cfg(feature = "zeroize-interop")]
impl<S: SecureSanitize + ?Sized> zeroize::Zeroize for SecretBox<S> {
#[inline]
fn zeroize(&mut self) {
self.clear_secret();
}
}
#[cfg(feature = "zeroize-interop")]
impl<S: SecureSanitize + ?Sized> zeroize::ZeroizeOnDrop for SecretBox<S> {}
impl<S: SecureSanitize + ?Sized> Drop for SecretBox<S> {
#[inline]
fn drop(&mut self) {
self.clear_secret();
}
}
impl<S: SecureSanitize + ?Sized> fmt::Debug for SecretBox<S> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"SecretBox<{}>([REDACTED])",
any::type_name::<S>()
)
}
}
impl<S: SecureSanitize + ct::ConstantTimeEq + ?Sized> SecretBox<S> {
#[must_use]
#[inline]
pub fn ct_eq(&self, other: &Self) -> ct::Choice {
ct::ConstantTimeEq::ct_eq(self.inner_secret.as_ref(), other.inner_secret.as_ref())
}
}
impl<S: CloneableSecret> Clone for SecretBox<S> {
#[inline]
fn clone(&self) -> Self {
Self::new(self.inner_secret.clone())
}
}
impl<S: sanitization::StableSharedSecretStorage + ?Sized> ExposeSecret<S> for SecretBox<S> {
#[inline]
fn expose_secret(&self) -> &S {
self.inner_secret.as_ref()
}
}
impl<S: sanitization::StableMutableSecretStorage + ?Sized> ExposeSecretMut<S> for SecretBox<S> {
#[inline]
fn expose_secret_mut(&mut self) -> &mut S {
self.inner_secret.as_mut()
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
pub struct UnrestrictedSecretBox<S: SecureSanitize + ?Sized> {
inner: SecretBox<S>,
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> UnrestrictedSecretBox<S> {
#[must_use]
#[inline]
pub const fn new(boxed_secret: Box<S>) -> Self {
Self {
inner: SecretBox::new(boxed_secret),
}
}
#[inline]
pub fn clear_secret(&mut self) {
self.inner.clear_secret();
}
#[must_use]
#[inline]
pub fn into_restricted(self) -> SecretBox<S> {
self.inner
}
#[inline]
pub fn into_cleared(self) {
drop(self);
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + Default> UnrestrictedSecretBox<S> {
#[must_use]
#[inline]
pub fn init_with_mut(initialize: impl FnOnce(&mut S)) -> Self {
let mut secret = Self::default();
initialize(secret.inner.inner_secret.as_mut());
secret
}
#[inline]
pub fn try_init_with_mut<E>(
initialize: impl FnOnce(&mut S) -> Result<(), E>,
) -> Result<Self, E> {
let mut secret = Self::default();
initialize(secret.inner.inner_secret.as_mut())?;
Ok(secret)
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> From<Box<S>> for UnrestrictedSecretBox<S> {
#[inline]
fn from(source: Box<S>) -> Self {
Self::new(source)
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + Default> Default for UnrestrictedSecretBox<S> {
#[inline]
fn default() -> Self {
Self {
inner: SecretBox::default(),
}
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> SecureSanitize for UnrestrictedSecretBox<S> {
#[inline]
fn secure_sanitize(&mut self) {
self.clear_secret();
}
}
#[cfg(all(feature = "hazmat-unrestricted-exposure", feature = "zeroize-interop"))]
impl<S: SecureSanitize + ?Sized> zeroize::Zeroize for UnrestrictedSecretBox<S> {
#[inline]
fn zeroize(&mut self) {
self.clear_secret();
}
}
#[cfg(all(feature = "hazmat-unrestricted-exposure", feature = "zeroize-interop"))]
impl<S: SecureSanitize + ?Sized> zeroize::ZeroizeOnDrop for UnrestrictedSecretBox<S> {}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> fmt::Debug for UnrestrictedSecretBox<S> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"UnrestrictedSecretBox<{}>([REDACTED])",
any::type_name::<S>()
)
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ct::ConstantTimeEq + ?Sized> UnrestrictedSecretBox<S> {
#[must_use]
#[inline]
pub fn ct_eq(&self, other: &Self) -> ct::Choice {
self.inner.ct_eq(&other.inner)
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: CloneableSecret> Clone for UnrestrictedSecretBox<S> {
#[inline]
fn clone(&self) -> Self {
Self {
inner: self.inner.clone(),
}
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> ExposeSecret<S> for UnrestrictedSecretBox<S> {
#[inline]
fn expose_secret(&self) -> &S {
self.inner.inner_secret.as_ref()
}
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
impl<S: SecureSanitize + ?Sized> ExposeSecretMut<S> for UnrestrictedSecretBox<S> {
#[inline]
fn expose_secret_mut(&mut self) -> &mut S {
self.inner.inner_secret.as_mut()
}
}
pub type SecretSlice<S> = SecretBox<[S]>;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SecretSliceCapacityError {
pub length: usize,
pub capacity: usize,
}
impl fmt::Display for SecretSliceCapacityError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"secret slice source has length {} but capacity {}; no-copy boxing would discard secret-bearing capacity",
self.length, self.capacity
)
}
}
impl<S: SecureSanitize> SecretSlice<S> {
#[inline]
pub fn try_from_vec_exact(mut source: Vec<S>) -> Result<Self, SecretSliceCapacityError> {
let length = source.len();
let capacity = source.capacity();
if size_of::<S>() != 0 && capacity != length {
source.secure_sanitize();
return Err(SecretSliceCapacityError { length, capacity });
}
Ok(Self::new(source.into_boxed_slice()))
}
}
impl SecretSlice<u8> {
#[must_use]
#[inline]
pub fn init_with_len(length: usize, initialize: impl FnOnce(&mut [u8])) -> Self {
let mut secret = Self::new(alloc::vec![0_u8; length].into_boxed_slice());
initialize(secret.expose_secret_mut());
secret
}
#[inline]
pub fn try_init_with_len<E>(
length: usize,
initialize: impl FnOnce(&mut [u8]) -> Result<(), E>,
) -> Result<Self, SecretSliceInitError<E>> {
let mut secret =
try_allocate_exact_zeroed_slice(length).map_err(SecretSliceInitError::Build)?;
initialize(secret.expose_secret_mut()).map_err(SecretSliceInitError::Initialize)?;
Ok(secret)
}
#[inline]
pub fn try_init_with_len_bounded<const MAX: usize, E>(
length: usize,
initialize: impl FnOnce(&mut [u8]) -> Result<(), E>,
) -> Result<Self, SecretSliceInitError<E>> {
if length > MAX {
return Err(SecretSliceInitError::Build(
SecretSliceAllocationError::TooLong {
maximum: MAX,
actual: length,
},
));
}
Self::try_init_with_len(length, initialize)
}
}
#[derive(Debug)]
pub enum SecretSliceAllocationError {
TooLong {
maximum: usize,
actual: usize,
},
Allocation(alloc::collections::TryReserveError),
NonExactCapacity {
requested: usize,
actual: usize,
},
}
impl fmt::Display for SecretSliceAllocationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::TooLong { maximum, actual } => write!(
formatter,
"secret slice length exceeds limit: maximum {maximum} bytes, got {actual} bytes"
),
Self::Allocation(error) => write!(formatter, "secret slice allocation failed: {error}"),
Self::NonExactCapacity { requested, actual } => write!(
formatter,
"secret slice allocator returned capacity {actual} for requested length {requested}"
),
}
}
}
impl core::error::Error for SecretSliceAllocationError {
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::Allocation(error) => Some(error),
Self::TooLong { .. } | Self::NonExactCapacity { .. } => None,
}
}
}
#[derive(Debug)]
pub enum SecretSliceInitError<E> {
Build(SecretSliceAllocationError),
Initialize(E),
}
impl<E> From<SecretSliceAllocationError> for SecretSliceInitError<E> {
#[inline]
fn from(error: SecretSliceAllocationError) -> Self {
Self::Build(error)
}
}
impl<E: fmt::Display> fmt::Display for SecretSliceInitError<E> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Build(error) => error.fmt(formatter),
Self::Initialize(error) => {
write!(formatter, "secret slice initialization failed: {error}")
}
}
}
}
impl<E> core::error::Error for SecretSliceInitError<E>
where
E: core::error::Error + 'static,
{
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::Build(error) => Some(error),
Self::Initialize(error) => Some(error),
}
}
}
fn try_allocate_exact_zeroed_slice(
length: usize,
) -> Result<SecretSlice<u8>, SecretSliceAllocationError> {
let mut bytes = Vec::new();
bytes
.try_reserve_exact(length)
.map_err(SecretSliceAllocationError::Allocation)?;
if bytes.capacity() != length {
return Err(SecretSliceAllocationError::NonExactCapacity {
requested: length,
actual: bytes.capacity(),
});
}
bytes.resize(length, 0);
Ok(SecretSlice::new(bytes.into_boxed_slice()))
}
impl<S: CloneableSecret> From<Vec<S>> for SecretSlice<S> {
#[inline]
fn from(source: Vec<S>) -> Self {
let source = TemporarySecret::new(source);
Self::new(clone_slice_into_box(source.value()))
}
}
impl<S: CloneableSecret> Clone for SecretSlice<S> {
#[inline]
fn clone(&self) -> Self {
Self::new(clone_slice_into_box(self.inner_secret.as_ref()))
}
}
impl<S: SecureSanitize> Default for SecretSlice<S> {
#[inline]
fn default() -> Self {
Self::new(Vec::new().into_boxed_slice())
}
}
pub type SecretString = SecretBox<str>;
impl From<String> for SecretString {
#[inline]
fn from(source: String) -> Self {
let source = TemporarySecret::new(source);
Self::new(Box::<str>::from(source.value().as_str()))
}
}
impl From<&str> for SecretString {
#[inline]
fn from(source: &str) -> Self {
Self::new(Box::<str>::from(source))
}
}
impl Clone for SecretString {
#[inline]
fn clone(&self) -> Self {
Self::new(self.inner_secret.clone())
}
}
impl Default for SecretString {
#[inline]
fn default() -> Self {
String::new().into()
}
}
pub trait CloneableSecret: Clone + SecureSanitize {}
macro_rules! impl_cloneable_secret {
($($type:ty),+ $(,)?) => {
$(impl CloneableSecret for $type {})+
};
}
impl_cloneable_secret!(i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize,);
impl CloneableSecret for String {}
macro_rules! impl_cloneable_secret_arrays {
($($type:ty),+ $(,)?) => {
$(impl<const N: usize> CloneableSecret for [$type; N] {})+
};
}
impl_cloneable_secret_arrays!(i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize,);
pub trait ExposeSecret<S: ?Sized> {
fn expose_secret(&self) -> &S;
}
pub trait ExposeSecretMut<S: ?Sized> {
fn expose_secret_mut(&mut self) -> &mut S;
}
#[cfg(feature = "serde")]
pub trait SerializableSecret: Serialize {}
#[cfg(feature = "serde-compat-unbounded")]
impl<'de, T> Deserialize<'de> for SecretBox<T>
where
T: CloneableSecret + de::DeserializeOwned + Sized,
{
#[inline]
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: de::Deserializer<'de>,
{
Self::try_init_with(|| T::deserialize(deserializer))
}
}
#[cfg(all(
feature = "serde-compat-unbounded",
feature = "hazmat-unrestricted-exposure"
))]
impl<'de, T> Deserialize<'de> for UnrestrictedSecretBox<T>
where
T: CloneableSecret + de::DeserializeOwned + Sized,
{
#[inline]
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: de::Deserializer<'de>,
{
SecretBox::deserialize(deserializer).map(|inner| Self { inner })
}
}
#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for SecretString {
#[inline]
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: de::Deserializer<'de>,
{
deserializer.deserialize_string(SecretStringVisitor)
}
}
#[cfg(feature = "serde")]
struct SecretStringVisitor;
#[cfg(feature = "serde")]
impl<'de> de::Visitor<'de> for SecretStringVisitor {
type Value = SecretString;
fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"at most {} UTF-8 bytes of secret text",
sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN
)
}
fn visit_str<E>(self, text: &str) -> Result<Self::Value, E>
where
E: de::Error,
{
self.validate_len::<E>(text.len())?;
Ok(SecretString::from(text))
}
fn visit_string<E>(self, mut text: String) -> Result<Self::Value, E>
where
E: de::Error,
{
if let Err(error) = self.validate_len::<E>(text.len()) {
text.secure_sanitize();
return Err(error);
}
Ok(SecretString::from(text))
}
}
#[cfg(feature = "serde")]
impl SecretStringVisitor {
fn validate_len<E: de::Error>(&self, actual: usize) -> Result<(), E> {
if actual > sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN {
Err(E::invalid_length(actual, self))
} else {
Ok(())
}
}
}
#[cfg(feature = "serde")]
impl<T> Serialize for SecretBox<T>
where
T: sanitization::StableSharedSecretStorage + SerializableSecret + Serialize + Sized,
{
#[inline]
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: ser::Serializer,
{
self.expose_secret().serialize(serializer)
}
}
#[cfg(all(feature = "serde", feature = "hazmat-unrestricted-exposure"))]
impl<T> Serialize for UnrestrictedSecretBox<T>
where
T: SecureSanitize + SerializableSecret + Serialize + Sized,
{
#[inline]
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: ser::Serializer,
{
self.inner.inner_secret.as_ref().serialize(serializer)
}
}
struct TemporarySecret<T: SecureSanitize>(T);
impl<T: SecureSanitize> TemporarySecret<T> {
#[inline]
const fn new(value: T) -> Self {
Self(value)
}
#[inline]
const fn value(&self) -> &T {
&self.0
}
}
fn clone_slice_into_box<S: CloneableSecret>(source: &[S]) -> Box<[S]> {
let mut pending = PendingCloneSlice::new(source.len());
for item in source {
pending.push(item.clone());
}
pending.into_box()
}
struct PendingCloneSlice<S: SecureSanitize> {
storage: Option<Box<[MaybeUninit<S>]>>,
initialized: usize,
}
impl<S: SecureSanitize> PendingCloneSlice<S> {
fn new(length: usize) -> Self {
Self {
storage: Some(Box::<[S]>::new_uninit_slice(length)),
initialized: 0,
}
}
fn push(&mut self, value: S) {
let storage = self.storage.as_mut().expect("pending clone storage");
storage[self.initialized].write(value);
self.initialized += 1;
}
#[allow(unsafe_code)]
fn into_box(mut self) -> Box<[S]> {
let expected = self.storage.as_ref().expect("pending clone storage").len();
assert_eq!(
self.initialized, expected,
"pending clone slice is not fully initialized"
);
let storage = self.storage.take().expect("pending clone storage");
unsafe { storage.assume_init() }
}
}
impl<S: SecureSanitize> Drop for PendingCloneSlice<S> {
#[allow(unsafe_code)]
fn drop(&mut self) {
let Some(storage) = self.storage.as_mut() else {
return;
};
for slot in &mut storage[..self.initialized] {
unsafe {
slot.assume_init_mut().secure_sanitize();
slot.assume_init_drop();
}
}
}
}
impl<T: SecureSanitize> Drop for TemporarySecret<T> {
#[inline]
fn drop(&mut self) {
self.0.secure_sanitize();
}
}
#[cfg(test)]
extern crate std;
#[cfg(test)]
mod tests {
use super::*;
use alloc::vec;
use core::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::{
format, panic,
sync::{Arc, Mutex},
};
static DEFAULT_VALUE_CLEARED: AtomicBool = AtomicBool::new(false);
static DEFAULT_VALUE_TEST_LOCK: Mutex<()> = Mutex::new(());
#[cfg(feature = "serde")]
impl SerializableSecret for [u8; 4] {}
#[cfg(all(feature = "serde", feature = "hazmat-unrestricted-exposure"))]
impl SerializableSecret for String {}
#[test]
fn string_and_slice_round_trip() {
let mut source = String::with_capacity(64);
source.push_str("token");
let mut text = SecretString::from(source);
assert_eq!(text.expose_secret(), "token");
text.expose_secret_mut().make_ascii_uppercase();
assert_eq!(text.expose_secret(), "TOKEN");
text.clear_secret();
assert_eq!(text.expose_secret().as_bytes(), &[0; 5]);
let bytes = SecretSlice::from(vec![1_u8, 2, 3]);
assert_eq!(bytes.expose_secret(), &[1, 2, 3]);
}
#[cfg(feature = "hazmat-unrestricted-exposure")]
#[test]
fn hazmat_newtype_provides_explicit_unrestricted_string_exposure() {
let mut secret =
UnrestrictedSecretBox::<String>::init_with_mut(|text| text.push_str("token"));
secret.expose_secret_mut().push_str("-rotated");
assert_eq!(secret.expose_secret(), "token-rotated");
let restricted = secret.into_restricted();
assert_eq!(restricted.inner_secret.as_ref(), "token-rotated");
}
#[test]
fn exact_vector_transfer_rejects_and_sanitizes_excess_capacity() {
struct NonCloneable {
cleared: Arc<AtomicBool>,
byte: u8,
}
impl SecureSanitize for NonCloneable {
fn secure_sanitize(&mut self) {
self.byte = 0;
self.cleared.store(true, Ordering::SeqCst);
}
}
let cleared = Arc::new(AtomicBool::new(false));
let mut source = Vec::with_capacity(8);
source.push(NonCloneable {
cleared: Arc::clone(&cleared),
byte: 23,
});
let error = SecretSlice::try_from_vec_exact(source).unwrap_err();
assert_eq!(error.length, 1);
assert_eq!(error.capacity, 8);
assert!(cleared.load(Ordering::SeqCst));
}
#[test]
fn exact_vector_transfer_preserves_live_elements() {
let mut source = Vec::with_capacity(4);
source.extend_from_slice(&[3_u8, 5, 7, 11]);
assert_eq!(source.len(), source.capacity());
let secret = SecretSlice::try_from_vec_exact(source).unwrap();
assert_eq!(secret.expose_secret(), &[3, 5, 7, 11]);
}
#[test]
fn vector_conversion_clears_source_with_excess_capacity() {
let cleared = Arc::new(AtomicBool::new(false));
let mut source = Vec::with_capacity(8);
source.push(TrackedSecret {
cleared: Arc::clone(&cleared),
byte: 31,
});
let secret = SecretSlice::from(source);
assert!(cleared.load(Ordering::SeqCst));
assert_eq!(secret.expose_secret()[0].byte, 31);
}
#[test]
fn debug_is_redacted() {
let secret = SecretString::from("do-not-print");
let rendered = format!("{secret:?}");
assert!(rendered.contains("REDACTED"));
assert!(!rendered.contains("do-not-print"));
}
#[test]
fn init_with_mut_writes_final_allocation() {
let secret = SecretBox::<[u8; 4]>::init_with_mut(|bytes| {
bytes.copy_from_slice(b"test");
});
assert_eq!(secret.expose_secret(), b"test");
}
#[test]
fn runtime_slice_initializer_uses_final_length_and_propagates_errors() {
let secret = SecretSlice::<u8>::init_with_len(5, |bytes| {
assert_eq!(bytes.len(), 5);
bytes.copy_from_slice(b"token");
});
assert_eq!(secret.expose_secret(), b"token");
let result = SecretSlice::<u8>::try_init_with_len(4, |bytes| {
bytes[0] = 17;
Err::<(), _>("injected initialization failure")
});
assert!(matches!(
result,
Err(SecretSliceInitError::Initialize(
"injected initialization failure"
))
));
}
#[test]
fn bounded_runtime_slice_rejects_length_before_initialization() {
let initializer_called = AtomicBool::new(false);
let result = SecretSlice::<u8>::try_init_with_len_bounded::<4, &str>(5, |_| {
initializer_called.store(true, Ordering::SeqCst);
Ok(())
});
assert!(matches!(
result,
Err(SecretSliceInitError::Build(
SecretSliceAllocationError::TooLong {
maximum: 4,
actual: 5
}
))
));
assert!(!initializer_called.load(Ordering::SeqCst));
}
#[test]
fn runtime_slice_reports_capacity_overflow_as_allocation_failure() {
let result = SecretSlice::<u8>::try_init_with_len(usize::MAX, |_| Ok::<(), &str>(()));
assert!(matches!(
result,
Err(SecretSliceInitError::Build(
SecretSliceAllocationError::Allocation(_)
))
));
}
#[test]
fn reviewed_primitive_arrays_are_cloneable_secrets() {
fn assert_cloneable<T: CloneableSecret>() {}
assert_cloneable::<[u8; 32]>();
assert_cloneable::<[i128; 2]>();
}
#[derive(Clone)]
struct TrackedSecret {
cleared: Arc<AtomicBool>,
byte: u8,
}
impl SecureSanitize for TrackedSecret {
fn secure_sanitize(&mut self) {
self.byte = 0;
self.cleared.store(true, Ordering::SeqCst);
}
}
impl sanitization::StableSharedSecretStorage for TrackedSecret {}
impl sanitization::StableMutableSecretStorage for TrackedSecret {}
impl CloneableSecret for TrackedSecret {}
#[derive(Default)]
struct DefaultTrackedSecret(u8);
impl SecureSanitize for DefaultTrackedSecret {
fn secure_sanitize(&mut self) {
self.0 = 0;
DEFAULT_VALUE_CLEARED.store(true, Ordering::SeqCst);
}
}
impl sanitization::StableSharedSecretStorage for DefaultTrackedSecret {}
impl sanitization::StableMutableSecretStorage for DefaultTrackedSecret {}
#[test]
fn drop_sanitizes_boxed_value() {
let cleared = Arc::new(AtomicBool::new(false));
let secret = SecretBox::new(Box::new(TrackedSecret {
cleared: Arc::clone(&cleared),
byte: 42,
}));
drop(secret);
assert!(cleared.load(Ordering::SeqCst));
}
#[test]
fn cloned_secret_is_independent() {
let source = SecretBox::new(Box::new(7_u32));
let mut duplicate = source.clone();
*duplicate.expose_secret_mut() = 9;
assert_eq!(*source.expose_secret(), 7);
assert_eq!(*duplicate.expose_secret(), 9);
}
#[test]
fn custom_clone_marker_is_the_positive_opt_in() {
let cleared = Arc::new(AtomicBool::new(false));
let source = SecretBox::new(Box::new(TrackedSecret { cleared, byte: 19 }));
let duplicate = source.clone();
assert_eq!(duplicate.expose_secret().byte, 19);
}
#[test]
fn completed_slice_clones_are_sanitized_when_a_later_clone_panics() {
struct PanicCloneElement {
byte: u8,
clone_attempts: Arc<AtomicUsize>,
leaked_on_drop: Arc<AtomicBool>,
cloned: bool,
}
impl Clone for PanicCloneElement {
fn clone(&self) -> Self {
if self.clone_attempts.fetch_add(1, Ordering::SeqCst) == 1 {
panic!("injected element clone panic");
}
Self {
byte: self.byte,
clone_attempts: Arc::clone(&self.clone_attempts),
leaked_on_drop: Arc::clone(&self.leaked_on_drop),
cloned: true,
}
}
}
impl SecureSanitize for PanicCloneElement {
fn secure_sanitize(&mut self) {
self.byte = 0;
}
}
impl CloneableSecret for PanicCloneElement {}
impl Drop for PanicCloneElement {
fn drop(&mut self) {
if self.cloned && self.byte != 0 {
self.leaked_on_drop.store(true, Ordering::SeqCst);
}
}
}
let clone_attempts = Arc::new(AtomicUsize::new(0));
let leaked_on_drop = Arc::new(AtomicBool::new(false));
let source = SecretBox::new(
vec![
PanicCloneElement {
byte: 11,
clone_attempts: Arc::clone(&clone_attempts),
leaked_on_drop: Arc::clone(&leaked_on_drop),
cloned: false,
},
PanicCloneElement {
byte: 13,
clone_attempts,
leaked_on_drop: Arc::clone(&leaked_on_drop),
cloned: false,
},
]
.into_boxed_slice(),
);
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let _ = source.clone();
}));
assert!(result.is_err());
assert!(!leaked_on_drop.load(Ordering::SeqCst));
}
#[test]
fn incomplete_pending_clone_keeps_cleanup_guard_armed() {
let cleared = Arc::new(AtomicBool::new(false));
let mut pending = PendingCloneSlice::new(2);
pending.push(TrackedSecret {
cleared: Arc::clone(&cleared),
byte: 47,
});
let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
let _ = pending.into_box();
}));
assert!(result.is_err());
assert!(cleared.load(Ordering::SeqCst));
}
#[test]
fn compatibility_comparison_uses_explicit_declassification() {
let left = SecretString::from("same-token");
let equal = SecretString::from("same-token");
let different = SecretString::from("other-token");
assert!(left
.ct_eq(&equal)
.declassify("authentication token equality is intentionally public"));
assert!(!left
.ct_eq(&different)
.declassify("authentication token inequality is intentionally public"));
}
#[test]
fn init_temporary_is_sanitized_on_success() {
let cleared = Arc::new(AtomicBool::new(false));
let secret = SecretBox::init_with(|| TrackedSecret {
cleared: Arc::clone(&cleared),
byte: 42,
});
assert!(cleared.load(Ordering::SeqCst));
assert_eq!(secret.expose_secret().byte, 42);
}
#[test]
fn init_temporary_is_sanitized_when_clone_panics() {
#[derive(Default)]
struct PanicClone {
cleared: Arc<AtomicBool>,
}
impl Clone for PanicClone {
fn clone(&self) -> Self {
panic!("injected clone panic")
}
}
impl SecureSanitize for PanicClone {
fn secure_sanitize(&mut self) {
self.cleared.store(true, Ordering::SeqCst);
}
}
impl CloneableSecret for PanicClone {}
let cleared = Arc::new(AtomicBool::new(false));
let result = panic::catch_unwind({
let cleared = Arc::clone(&cleared);
move || {
let _ = SecretBox::init_with(|| PanicClone { cleared });
}
});
assert!(result.is_err());
assert!(cleared.load(Ordering::SeqCst));
}
#[test]
fn init_with_mut_sanitizes_partial_value_during_unwind() {
let _test_guard = DEFAULT_VALUE_TEST_LOCK
.lock()
.expect("default-value cleanup test lock");
DEFAULT_VALUE_CLEARED.store(false, Ordering::SeqCst);
let result = panic::catch_unwind(|| {
let _ = SecretBox::<DefaultTrackedSecret>::init_with_mut(|secret| {
secret.0 = 42;
panic!("injected initializer panic");
});
});
assert!(result.is_err());
assert!(DEFAULT_VALUE_CLEARED.load(Ordering::SeqCst));
}
#[test]
fn try_init_with_mut_sanitizes_partial_value_on_error() {
let _test_guard = DEFAULT_VALUE_TEST_LOCK
.lock()
.expect("default-value cleanup test lock");
DEFAULT_VALUE_CLEARED.store(false, Ordering::SeqCst);
let result = SecretBox::<DefaultTrackedSecret>::try_init_with_mut(|secret| {
secret.0 = 29;
Err::<(), _>("injected initialization failure")
});
assert_eq!(result.unwrap_err(), "injected initialization failure");
assert!(DEFAULT_VALUE_CLEARED.load(Ordering::SeqCst));
}
#[test]
fn into_cleared_sanitizes_exactly_once() {
struct CountedClear(Arc<AtomicUsize>);
impl SecureSanitize for CountedClear {
fn secure_sanitize(&mut self) {
self.0.fetch_add(1, Ordering::SeqCst);
}
}
let clear_count = Arc::new(AtomicUsize::new(0));
SecretBox::new(Box::new(CountedClear(Arc::clone(&clear_count)))).into_cleared();
assert_eq!(clear_count.load(Ordering::SeqCst), 1);
}
#[test]
fn fallible_constructor_preserves_generator_error() {
let result = SecretBox::<[u8; 4]>::try_init_with(|| Err::<[u8; 4], _>("failure"));
assert_eq!(result.unwrap_err(), "failure");
}
#[cfg(feature = "serde")]
#[test]
fn serde_plaintext_requires_explicit_marker() {
let secret = SecretBox::new(Box::new([1_u8, 2, 3, 4]));
assert_eq!(secret.expose_secret(), &[1, 2, 3, 4]);
assert_eq!(serde_json::to_string(&secret).unwrap(), "[1,2,3,4]");
}
#[cfg(feature = "serde")]
#[test]
#[cfg_attr(
miri,
ignore = "large JSON boundary fixture is covered natively; exact limit arithmetic has a Miri-safe unit test"
)]
fn serde_secret_string_enforces_default_input_ceiling() {
let accepted_json = format!(
"\"{}\"",
"a".repeat(sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN)
);
let accepted: SecretString = serde_json::from_str(&accepted_json).unwrap();
assert_eq!(
accepted.expose_secret().len(),
sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN
);
let rejected_json = format!(
"\"{}\"",
"b".repeat(sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN + 1)
);
assert!(serde_json::from_str::<SecretString>(&rejected_json).is_err());
}
#[cfg(feature = "serde")]
#[test]
fn serde_secret_string_limit_accepts_max_and_rejects_next_byte() {
let visitor = SecretStringVisitor;
assert!(visitor
.validate_len::<de::value::Error>(sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN)
.is_ok());
assert!(visitor
.validate_len::<de::value::Error>(sanitization::DEFAULT_SECRET_STRING_SERDE_MAX_LEN + 1)
.is_err());
}
#[cfg(feature = "serde-compat-unbounded")]
#[test]
fn generic_serde_deserialization_requires_unbounded_compatibility_opt_in() {
let secret: SecretBox<String> = serde_json::from_str("\"token\"").unwrap();
assert_eq!(secret.inner_secret.as_ref(), "token");
}
#[cfg(all(
feature = "serde-compat-unbounded",
feature = "hazmat-unrestricted-exposure"
))]
#[test]
fn unrestricted_newtype_serde_requires_both_explicit_features() {
let secret: UnrestrictedSecretBox<String> = serde_json::from_str("\"token\"").unwrap();
assert_eq!(secret.expose_secret(), "token");
assert_eq!(serde_json::to_string(&secret).unwrap(), "\"token\"");
}
}