diff --git a/Cargo.toml b/Cargo.toml index bf9a2316c..586c8fbe0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,8 +26,7 @@ alloc = [] rand-std = ["rand/std"] recovery = ["secp256k1-sys/recovery"] lowmemory = ["secp256k1-sys/lowmemory"] -global-context = ["std", "rand-std", "global-context-less-secure"] -global-context-less-secure = [] +global-context = ["std"] [dependencies] secp256k1-sys = { version = "0.4.2", default-features = false, path = "./secp256k1-sys" } diff --git a/src/context.rs b/src/context.rs index f14f2cbcd..310da6df1 100644 --- a/src/context.rs +++ b/src/context.rs @@ -9,11 +9,11 @@ use Secp256k1; #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] pub use self::alloc_only::*; -#[cfg(all(feature = "global-context-less-secure", feature = "std"))] -#[cfg_attr(docsrs, doc(cfg(any(feature = "global-context", feature = "global-context-less-secure"))))] +#[cfg(all(feature = "global-context", feature = "std"))] +#[cfg_attr(docsrs, doc(cfg(all(feature = "global-context", feature = "std"))))] /// Module implementing a singleton pattern for a global `Secp256k1` context pub mod global { - #[cfg(feature = "global-context")] + #[cfg(feature = "rand-std")] use rand; use std::ops::Deref; @@ -26,22 +26,29 @@ pub mod global { __private: (), } - /// A global, static context to avoid repeatedly creating contexts where one can't be passed + /// A global static context to avoid repeatedly creating contexts. /// - /// If the global-context feature is enabled (and not just the global-context-less-secure), - /// this will have been randomized. + /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// + /// ``` + /// # #[cfg(all(feature = "global-context", feature = "rand-std"))] { + /// use secp256k1::{PublicKey, SECP256K1}; + /// use secp256k1::rand::thread_rng; + /// let _ = SECP256K1.generate_keypair(&mut thread_rng()); + /// # } + /// ``` pub static SECP256K1: &GlobalContext = &GlobalContext { __private: () }; impl Deref for GlobalContext { type Target = Secp256k1; - #[allow(unused_mut)] // Unused when "global-context" is not enabled. + #[allow(unused_mut)] // Unused when `rand-std` is not enabled. fn deref(&self) -> &Self::Target { static ONCE: Once = Once::new(); static mut CONTEXT: Option> = None; ONCE.call_once(|| unsafe { let mut ctx = Secp256k1::new(); - #[cfg(feature = "global-context")] + #[cfg(feature = "rand-std")] { ctx.randomize(&mut rand::thread_rng()); } @@ -108,6 +115,9 @@ mod alloc_only { #[cfg(not(feature = "std"))] use alloc::alloc; + #[cfg(feature = "rand-std")] + use rand; + impl private::Sealed for SignOnly {} impl private::Sealed for All {} impl private::Sealed for VerifyOnly {} @@ -167,7 +177,23 @@ mod alloc_only { } impl Secp256k1 { - /// Lets you create a context in a generic manner(sign/verify/all) + /// Lets you create a context in a generic manner (sign/verify/all). + /// + /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// If `rand-std` feature is not enabled please consider randomizing the context as follows: + /// ``` + /// # #[cfg(all(feature = "rand-std", any(feature = "alloc", feature = "std")))] { + /// # use secp256k1::Secp256k1; + /// # use secp256k1::rand::{thread_rng, RngCore}; + /// let mut ctx = Secp256k1::new(); + /// # let mut rng = thread_rng(); + /// # let mut seed = [0u8; 32]; + /// # rng.fill_bytes(&mut seed); + /// // let seed = <32 bytes of random data> + /// ctx.seeded_randomize(&seed); + /// # } + /// ``` + #[allow(unused_mut)] // Unused when `rand-std` is not enabled. pub fn gen_new() -> Secp256k1 { #[cfg(target_arch = "wasm32")] ffi::types::sanity_checks_for_wasm(); @@ -175,30 +201,49 @@ mod alloc_only { let size = unsafe { ffi::secp256k1_context_preallocated_size(C::FLAGS) }; let layout = alloc::Layout::from_size_align(size, ALIGN_TO).unwrap(); let ptr = unsafe {alloc::alloc(layout)}; - Secp256k1 { + let mut ctx = Secp256k1 { ctx: unsafe { ffi::secp256k1_context_preallocated_create(ptr as *mut c_void, C::FLAGS) }, phantom: PhantomData, size, + }; + + #[cfg(feature = "rand-std")] + { + ctx.randomize(&mut rand::thread_rng()); } + + ctx } } impl Secp256k1 { - /// Creates a new Secp256k1 context with all capabilities + /// Creates a new Secp256k1 context with all capabilities. + /// + /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// If `rand-std` feature is not enabled please consider randomizing the context (see docs + /// for `Secp256k1::gen_new()`). pub fn new() -> Secp256k1 { Secp256k1::gen_new() } } impl Secp256k1 { - /// Creates a new Secp256k1 context that can only be used for signing + /// Creates a new Secp256k1 context that can only be used for signing. + /// + /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// If `rand-std` feature is not enabled please consider randomizing the context (see docs + /// for `Secp256k1::gen_new()`). pub fn signing_only() -> Secp256k1 { Secp256k1::gen_new() } } impl Secp256k1 { - /// Creates a new Secp256k1 context that can only be used for verification + /// Creates a new Secp256k1 context that can only be used for verification. + /// + /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// If `rand-std` feature is not enabled please consider randomizing the context (see docs + /// for `Secp256k1::gen_new()`). pub fn verification_only() -> Secp256k1 { Secp256k1::gen_new() } diff --git a/src/key.rs b/src/key.rs index bfebe6303..562f02e2f 100644 --- a/src/key.rs +++ b/src/key.rs @@ -641,7 +641,7 @@ impl Ord for PublicKey { /// feature active. This is due to security considerations, see the [`serde_keypair`] documentation /// for details. /// -/// If the `serde` and `global-context[-less-secure]` features are active `KeyPair`s can be serialized and +/// If the `serde` and `global-context` features are active `KeyPair`s can be serialized and /// deserialized by annotating them with `#[serde(with = "secp256k1::serde_keypair")]` /// inside structs or enums for which [`Serialize`] and [`Deserialize`] are being derived. /// @@ -1320,7 +1320,7 @@ impl<'de> ::serde::Deserialize<'de> for XOnlyPublicKey { /// /// [`SecretKey`]: crate::SecretKey /// [global context]: crate::SECP256K1 -#[cfg(all(feature = "global-context-less-secure", feature = "serde"))] +#[cfg(all(feature = "global-context", feature = "serde"))] pub mod serde_keypair { use serde::{Deserialize, Deserializer, Serialize, Serializer}; use key::KeyPair; @@ -1924,7 +1924,7 @@ mod test { } #[test] - #[cfg(all(feature = "global-context-less-secure", feature = "serde"))] + #[cfg(all(feature = "global-context", feature = "serde"))] fn test_serde_keypair() { use serde::{Deserialize, Deserializer, Serialize, Serializer}; use serde_test::{Configure, Token, assert_tokens}; diff --git a/src/lib.rs b/src/lib.rs index 7c73f4cbc..c007c983a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -20,9 +20,13 @@ //! and its derivatives. //! //! To minimize dependencies, some functions are feature-gated. To generate -//! random keys or to re-randomize a context object, compile with the "rand" -//! feature. To de/serialize objects with serde, compile with "serde". -//! **Important**: `serde` encoding is **not** the same as consensus encoding! +//! random keys or to re-randomize a context object, compile with the +//! `rand-std` feature. If you are willing to use the `rand-std` feature, we +//! have enabled an additional defense-in-depth sidechannel protection for +//! our context objects, which re-blinds certain operations on secret key +//! data. To de/serialize objects with serde, compile with "serde". +//! **Important**: `serde` encoding is **not** the same as consensus +//! encoding! //! //! Where possible, the bindings use the Rust type system to ensure that //! API usage errors are impossible. For example, the library uses context @@ -125,9 +129,7 @@ //! * `rand-std` - use `rand` library with its `std` feature enabled. (Implies `rand`.) //! * `recovery` - enable functions that can compute the public key from signature. //! * `lowmemory` - optimize the library for low-memory environments. -//! * `global-context` - enable use of global secp256k1 context. (Implies `std`, `rand-std` and -//! `global-context-less-secure`.) -//! * `global-context-less-secure` - enables global context without extra sidechannel protection. +//! * `global-context` - enable use of global secp256k1 context (implies `std`). //! * `serde` - implements serialization and deserialization for types in this crate using `serde`. //! **Important**: `serde` encoding is **not** the same as consensus encoding! //! * `bitcoin_hashes` - enables interaction with the `bitcoin-hashes` crate (e.g. conversions). @@ -195,8 +197,8 @@ use core::marker::PhantomData; use core::{mem, fmt, str}; use ffi::{CPtr, types::AlignedType}; -#[cfg(feature = "global-context-less-secure")] -#[cfg_attr(docsrs, doc(cfg(any(feature = "global-context", feature = "global-context-less-secure"))))] +#[cfg(feature = "global-context")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "global-context", feature = "global-context"))))] pub use context::global::SECP256K1; #[cfg(feature = "bitcoin_hashes")] @@ -955,7 +957,7 @@ mod tests { } - #[cfg(feature = "global-context-less-secure")] + #[cfg(feature = "global-context")] #[test] fn test_global_context() { use super::SECP256K1;