kem: use getrandom for Encapsulate::encapsulate (#2141)

Renames the previous `Encapsulate::encapsulate` to
`encapsulate_with_rng`, replacing the original method with a `getrandom`
feature-gated method which passes `SysRng` for you.

To make this work, it's necessary for `crypto-common` to re-export its
`SysRng`, which is currently vendored from `getrandom` v0.4 since
there's not currently a prerelease available.

Author: tarcieri

crypto-common/src/generate.rs

@@ -86,7 +86,7 @@ impl<U: ArraySize> Generate for Array<u64, U> {
 }
 
 #[cfg(feature = "getrandom")]
-mod sys_rng {
+pub(crate) mod sys_rng {
     use getrandom::Error;
     use rand_core::{TryCryptoRng, TryRngCore};
 

crypto-common/src/lib.rs

@@ -19,10 +19,10 @@ mod generate;
 pub use hybrid_array as array;
 pub use hybrid_array::typenum;
 
-#[cfg(feature = "getrandom")]
-pub use getrandom::Error as RngError;
 #[cfg(feature = "rand_core")]
 pub use {generate::Generate, rand_core};
+#[cfg(feature = "getrandom")]
+pub use {generate::sys_rng::SysRng, getrandom::Error as RngError};
 
 use core::fmt;
 use hybrid_array::{

kem/README.md

@@ -18,9 +18,9 @@ impl Encapsulate<SaberEncappedKey, SaberSharedSecret> for MyPubkey {
     // Encapsulation is infallible
     type Error = !;
 
-    fn encapsulate(
+    fn encapsulate_with_rng<R: TryCryptoRng + ?Sized>(
         &self,
-        csprng: impl CryptoRngCore,
+        csprng: &mut R,
     ) -> Result<(SaberEncappedKey, SaberSharedSecret), !> {
         let (ss, ek) = saber_encapsulate(&csprng, &self.0);
         Ok((ek, ss))
@@ -43,9 +43,9 @@ impl Encapsulate<EphemeralKey, SharedSecret> for EncapContext {
     // Encapsulation fails if signature verification fails
     type Error = SigError;
 
-    fn encapsulate(
+    fn encapsulate_with_rng<R: TryCryptoRng + ?Sized>(
         &self,
-        csprng: impl CryptoRngCore,
+        csprng: &mut R,
     ) -> Result<(EphemeralKey, SharedSecret), Self::Error> {
         // Make a new ephemeral key. This will be the encapped key
         let ek = EphemeralKey::gen(&mut csprng);

kem/src/lib.rs

@@ -20,7 +20,16 @@ pub trait Encapsulate<EK, SS> {
     type Error: core::error::Error;
 
     /// Encapsulates a fresh shared secret
-    fn encapsulate<R: TryCryptoRng + ?Sized>(&self, rng: &mut R) -> Result<(EK, SS), Self::Error>;
+    fn encapsulate_with_rng<R: TryCryptoRng + ?Sized>(
+        &self,
+        rng: &mut R,
+    ) -> Result<(EK, SS), Self::Error>;
+
+    /// Encapsulate a fresh shared secret generated using the system's secure RNG.
+    #[cfg(feature = "getrandom")]
+    fn encapsulate(&self) -> Result<(EK, SS), Self::Error> {
+        self.encapsulate_with_rng(&mut crypto_common::SysRng)
+    }
 }
 
 /// A value that can be used to decapsulate an encapsulated key.