Crate serdect

Source
Expand description

§RustCrypto: Constant-Time Serde Helpers

Crate Docs Build Status Apache 2.0/MIT Licensed MSRV

Constant-time serde serializer/deserializer helpers for data that potentially contains secrets (e.g. cryptographic keys)

Documentation

§About

Serialization is a potential sidechannel for leaking sensitive secrets such as cryptographic keys.

This crate provides “best effort” constant-time helper methods for reducing the amount of timing variability involved in serializing/deserializing data when using serde, Rust’s standard serialization framework.

These helper methods conditionally serialize data as hexadecimal using the constant-time base16ct crate when using human-readable formats such as JSON or TOML. When using a binary format, the data is serialized as-is into binary.

While this crate can’t ensure that format implementations don’t perform other kinds of data-dependent branching on the contents of the serialized data, using a constant-time hex serialization with human-readable formats should help reduce the overall timing variability.

§Minimum Supported Rust Version

Rust 1.56 or newer.

In the future, we reserve the right to change MSRV (i.e. MSRV is out-of-scope for this crate’s SemVer guarantees), however when we do it will be accompanied by a minor version bump.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Usage

§Implementing Deserialize and Serialize for arrays.

struct SecretData([u8; 32]);

impl<'de> Deserialize<'de> for SecretData {
   fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
   where
       D: Deserializer<'de>,
   {
       let mut buffer = [0; 32];
       serdect::array::deserialize_hex_or_bin(&mut buffer, deserializer)?;
       Ok(Self(buffer))
   }
}

impl Serialize for SecretData {
   fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
   where
       S: Serializer,
   {
       serdect::array::serialize_hex_lower_or_bin(&self.0, serializer)
   }
}

let data = SecretData([42; 32]);

let serialized = bincode::serialize(&data).unwrap();
// bincode, a binary serialization format, is serialized into bytes.
assert_eq!(serialized.as_slice(), [42; 32]);

let serialized = serde_json::to_string(&data).unwrap();
// JSON, a human-readable serialization format, is serialized into lower-case HEX.
assert_eq!(
   serialized,
   "\"2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a\""
);

§Implementing Deserialize and Serialize for slices.

struct SecretData(Vec<u8>);

impl<'de> Deserialize<'de> for SecretData {
   fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
   where
       D: Deserializer<'de>,
   {
       serdect::slice::deserialize_hex_or_bin_vec(deserializer).map(Self)
   }
}

impl Serialize for SecretData {
   fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
   where
       S: Serializer,
   {
       serdect::slice::serialize_hex_lower_or_bin(&self.0, serializer)
   }
}

let data = SecretData(vec![42; 32]);

let serialized = bincode::serialize(&data).unwrap();
// bincode, a binary serialization format is serialized into bytes.
assert_eq!(
   serialized.as_slice(),
   [
       // Not fixed-size, so a size will be encoded.
       32, 0, 0, 0, 0, 0, 0, 0,
       // Actual data.
       42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42,
       42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42,
   ]
);

let serialized = serde_json::to_string(&data).unwrap();
// JSON, a human-readable serialization format is serialized into lower-case HEX.
assert_eq!(
   serialized,
   "\"2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a\""
);

Re-exports§

Modules§

  • array
    Serialization primitives for arrays.
  • slice
    Serialization primitives for slices.