Serde serialization rework

CHANGELOG.md

@@ -6,7 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Under construction.
+### Changed
+
+- When serialized to a human-readable format using `serde`, hex-encoded objects now have a `0x` prefix. ([#94])
+
+
+### Added
+
+- `serde` utility functions to serialize bytestrings as bytes or hex/base64 encoded strings, depending on the target format. Exposed as `serde_bytes` module. ([#94])
+
+
+[#94]: https://github.com/nucypher/rust-umbral/pull/94
 
 
 ## [0.5.2] - 2022-03-15

umbral-pre/src/capsule.rs

@@ -7,7 +7,7 @@ use rand_core::{CryptoRng, RngCore};
 use typenum::op;
 
 #[cfg(feature = "serde-support")]
-use crate::serde::{serde_deserialize, serde_serialize, Representation};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use crate::capsule_frag::CapsuleFrag;
 use crate::curve::{CurvePoint, CurveScalar, NonZeroCurveScalar};
@@ -21,7 +21,7 @@ use crate::traits::{
 };
 
 #[cfg(feature = "serde-support")]
-use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use crate::serde_bytes::{deserialize_with_encoding, serialize_as_array, Encoding};
 
 /// Errors that can happen when opening a `Capsule` using reencrypted `CapsuleFrag` objects.
 #[derive(Debug, PartialEq)]
@@ -92,7 +92,7 @@ impl Serialize for Capsule {
     where
         S: Serializer,
     {
-        serde_serialize(self, serializer, Representation::Base64)
+        serialize_as_array(self, serializer, Encoding::Base64)
     }
 }
 
@@ -103,7 +103,7 @@ impl<'de> Deserialize<'de> for Capsule {
     where
         D: Deserializer<'de>,
     {
-        serde_deserialize(deserializer, Representation::Base64)
+        deserialize_with_encoding(deserializer, Encoding::Base64)
     }
 }
 
@@ -268,10 +268,10 @@ mod tests {
     };
 
     #[cfg(feature = "serde-support")]
-    use crate::serde::tests::{check_deserialization, check_serialization};
-
-    #[cfg(feature = "serde-support")]
-    use crate::serde::Representation;
+    use crate::serde_bytes::{
+        tests::{check_deserialization, check_serialization},
+        Encoding,
+    };
 
     #[test]
     fn test_serialize() {
@@ -354,7 +354,7 @@ mod tests {
         let delegating_pk = delegating_sk.public_key();
         let (capsule, _key_seed) = Capsule::from_public_key(&mut OsRng, &delegating_pk);
 
-        check_serialization(&capsule, Representation::Base64);
+        check_serialization(&capsule, Encoding::Base64);
         check_deserialization(&capsule);
     }
 }

umbral-pre/src/capsule_frag.rs

@@ -20,7 +20,7 @@ use crate::traits::{
 };
 
 #[cfg(feature = "serde-support")]
-use crate::serde::{serde_deserialize, serde_serialize, Representation};
+use crate::serde_bytes::{deserialize_with_encoding, serialize_as_array, Encoding};
 
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) struct CapsuleFragProof {
@@ -168,7 +168,7 @@ impl Serialize for CapsuleFrag {
     where
         S: Serializer,
     {
-        serde_serialize(self, serializer, Representation::Base64)
+        serialize_as_array(self, serializer, Encoding::Base64)
     }
 }
 
@@ -179,7 +179,7 @@ impl<'de> Deserialize<'de> for CapsuleFrag {
     where
         D: Deserializer<'de>,
     {
-        serde_deserialize(deserializer, Representation::Base64)
+        deserialize_with_encoding(deserializer, Encoding::Base64)
     }
 }
 
@@ -385,10 +385,10 @@ mod tests {
     };
 
     #[cfg(feature = "serde-support")]
-    use crate::serde::tests::{check_deserialization, check_serialization};
-
-    #[cfg(feature = "serde-support")]
-    use crate::serde::Representation;
+    use crate::serde_bytes::{
+        tests::{check_deserialization, check_serialization},
+        Encoding,
+    };
 
     fn prepare_cfrags() -> (
         PublicKey,
@@ -453,7 +453,7 @@ mod tests {
         let vcfrag = verified_cfrags[0].clone();
         let cfrag = CapsuleFrag::from_array(&vcfrag.to_array()).unwrap();
 
-        check_serialization(&cfrag, Representation::Base64);
+        check_serialization(&cfrag, Encoding::Base64);
         check_deserialization(&cfrag);
     }
 }

umbral-pre/src/key_frag.rs

@@ -21,7 +21,7 @@ use crate::traits::{
 };
 
 #[cfg(feature = "serde-support")]
-use crate::serde::{serde_deserialize, serde_serialize, Representation};
+use crate::serde_bytes::{deserialize_with_encoding, serialize_as_array, Encoding};
 
 #[allow(clippy::upper_case_acronyms)]
 type KeyFragIDSize = U32;
@@ -211,7 +211,7 @@ impl Serialize for KeyFrag {
     where
         S: Serializer,
     {
-        serde_serialize(self, serializer, Representation::Base64)
+        serialize_as_array(self, serializer, Encoding::Base64)
     }
 }
 
@@ -222,7 +222,7 @@ impl<'de> Deserialize<'de> for KeyFrag {
     where
         D: Deserializer<'de>,
     {
-        serde_deserialize(deserializer, Representation::Base64)
+        deserialize_with_encoding(deserializer, Encoding::Base64)
     }
 }
 
@@ -511,10 +511,10 @@ mod tests {
     use crate::{DeserializableFromArray, PublicKey, SecretKey, SerializableToArray, Signer};
 
     #[cfg(feature = "serde-support")]
-    use crate::serde::tests::{check_deserialization, check_serialization};
-
-    #[cfg(feature = "serde-support")]
-    use crate::serde::Representation;
+    use crate::serde_bytes::{
+        tests::{check_deserialization, check_serialization},
+        Encoding,
+    };
 
     fn prepare_kfrags(
         sign_delegating_key: bool,
@@ -600,7 +600,7 @@ mod tests {
         let vkfrag = verified_kfrags[0].clone();
         let kfrag = KeyFrag::from_array(&vkfrag.to_array()).unwrap();
 
-        check_serialization(&kfrag, Representation::Base64);
+        check_serialization(&kfrag, Encoding::Base64);
         check_deserialization(&kfrag);
     }
 }

umbral-pre/src/keys.rs

@@ -26,7 +26,7 @@ use crate::traits::{
 };
 
 #[cfg(feature = "serde-support")]
-use crate::serde::{serde_deserialize, serde_serialize, Representation};
+use crate::serde_bytes::{deserialize_with_encoding, serialize_as_array, Encoding};
 
 /// ECDSA signature object.
 #[derive(Clone, Debug, PartialEq)]
@@ -59,7 +59,7 @@ impl Serialize for Signature {
     where
         S: Serializer,
     {
-        serde_serialize(self, serializer, Representation::Base64)
+        serialize_as_array(self, serializer, Encoding::Base64)
     }
 }
 
@@ -70,7 +70,7 @@ impl<'de> Deserialize<'de> for Signature {
     where
         D: Deserializer<'de>,
     {
-        serde_deserialize(deserializer, Representation::Base64)
+        deserialize_with_encoding(deserializer, Encoding::Base64)
     }
 }
 
@@ -263,7 +263,7 @@ impl Serialize for PublicKey {
     where
         S: Serializer,
     {
-        serde_serialize(self, serializer, Representation::Hex)
+        serialize_as_array(self, serializer, Encoding::Hex)
     }
 }
 
@@ -274,7 +274,7 @@ impl<'de> Deserialize<'de> for PublicKey {
     where
         D: Deserializer<'de>,
     {
-        serde_deserialize(deserializer, Representation::Hex)
+        deserialize_with_encoding(deserializer, Encoding::Hex)
     }
 }
 
@@ -404,9 +404,10 @@ mod tests {
     use crate::{DeserializableFromArray, SerializableToArray, SerializableToSecretArray};
 
     #[cfg(feature = "serde-support")]
-    use crate::serde::tests::{check_deserialization, check_serialization};
-    #[cfg(feature = "serde-support")]
-    use crate::serde::Representation;
+    use crate::serde_bytes::{
+        tests::{check_deserialization, check_serialization},
+        Encoding,
+    };
 
     #[test]
     fn test_serialize_secret_key() {
@@ -466,10 +467,10 @@ mod tests {
         let pk = signer.verifying_key();
         let signature = signer.sign(message);
 
-        check_serialization(&pk, Representation::Hex);
+        check_serialization(&pk, Encoding::Hex);
         check_deserialization(&pk);
 
-        check_serialization(&signature, Representation::Base64);
+        check_serialization(&signature, Encoding::Base64);
         check_deserialization(&signature);
     }
 }

umbral-pre/src/lib.rs

@@ -116,11 +116,14 @@ extern crate std;
 extern crate alloc;
 
 #[cfg(feature = "bench-internals")]
+#[cfg_attr(docsrs, doc(cfg(feature = "bench-internals")))]
 pub mod bench; // Re-export some internals for benchmarks.
 
 #[cfg(feature = "bindings-python")]
+#[cfg_attr(docsrs, doc(cfg(feature = "bindings-python")))]
 pub mod bindings_python;
 #[cfg(feature = "bindings-wasm")]
+#[cfg_attr(docsrs, doc(cfg(feature = "bindings-wasm")))]
 pub mod bindings_wasm;
 
 mod capsule;
@@ -137,7 +140,8 @@ mod secret_box;
 mod traits;
 
 #[cfg(any(feature = "serde-support", feature = "bindings-wasm"))]
-mod serde;
+#[cfg_attr(docsrs, doc(cfg(feature = "serde-support")))]
+pub mod serde_bytes;
 
 pub use capsule::{Capsule, OpenReencryptedError};
 pub use capsule_frag::{CapsuleFrag, CapsuleFragVerificationError, VerifiedCapsuleFrag};