Merge pull request #12 from dusk-network/mocello/improve_zeroize

Add safety comment for `SecretKey`

Cargo.toml

@@ -18,11 +18,11 @@ license = "MPL-2.0"
 dusk-bls12_381 = { version = "0.13", default-features = false, features = ["alloc", "pairings", "zeroize"] }
 dusk-bytes = "0.1"
 rand_core = { version = "0.6", default-features = false }
+ff = { version = "0.13", default-features = false }
+zeroize = { version = "1", default-features = false, features = ["derive"] }
 rkyv = { version = "0.7", optional = true, default-features = false }
 bytecheck = { version = "0.6", optional = true, default-features = false }
-ff = { version = "0.13", default-features = false }
 rayon = { version = "1.8", optional = true }
-zeroize = { version = "1", features = ["zeroize_derive"] }
 
 [dev-dependencies]
 rand = { version = "0.8", default-features = false, features = ["std_rng"] }

src/keys/secret.rs

@@ -18,6 +18,29 @@ use rkyv::{Archive, Deserialize, Serialize};
 
 /// A BLS secret key, holding a BLS12-381 scalar inside.
 /// Can be used for signing messages.
+///
+/// ## Safety
+///
+/// To ensure that no secret information lingers in memory after the variable
+/// goes out of scope, we advice calling `zeroize` before the variable goes out
+/// of scope.
+///
+/// ## Examples
+///
+/// Generate a random `SecretKey`:
+/// ```
+/// use bls12_381_bls::SecretKey;
+/// use rand::rngs::StdRng;
+/// use rand::SeedableRng;
+/// use zeroize::Zeroize;
+///
+/// let mut rng = StdRng::seed_from_u64(12345);
+/// let mut sk = SecretKey::random(&mut rng);
+///
+/// // do something with the sk
+///
+/// sk.zeroize();
+/// ```
 #[derive(Default, Clone, Debug, Eq, PartialEq, Zeroize)]
 #[cfg_attr(
     feature = "rkyv-impl",