From 269bde042f9d6bfccb857c6921e71f01a9854f35 Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 10:46:59 +1100 Subject: [PATCH 01/10] Remove unnecessary capitalisation 'context' does not need need a capital letter in the middle of a sentence. --- src/context.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/context.rs b/src/context.rs index 310da6d..15a4b20 100644 --- a/src/context.rs +++ b/src/context.rs @@ -60,8 +60,8 @@ pub mod global { } -/// A trait for all kinds of Context's that lets you define the exact flags and a function to deallocate memory. -/// It shouldn't be possible to implement this for types outside this crate. +/// A trait for all kinds of contexts that lets you define the exact flags and a function to +/// deallocate memory. It shouldn't be possible to implement this for types outside this crate. pub unsafe trait Context : private::Sealed { /// Flags for the ffi. const FLAGS: c_uint; From 5e07e7596b3c128c2290089f87a2851946fb538d Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 10:52:28 +1100 Subject: [PATCH 02/10] Add period to sentences Add the terminating period to all docs sentences. (Also one instance of capitialize initial character in sentence.) --- src/constants.rs | 8 ++++---- src/context.rs | 24 ++++++++++++------------ src/ecdh.rs | 2 +- src/ecdsa/recovery.rs | 19 +++++++++---------- src/key.rs | 4 ++-- src/lib.rs | 30 +++++++++++++++--------------- 6 files changed, 43 insertions(+), 44 deletions(-) diff --git a/src/constants.rs b/src/constants.rs index 668683f..5754183 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -14,7 +14,7 @@ // //! # Constants -//! Constants related to the API and the underlying curve +//! Constants related to the API and the underlying curve. /// The size (in bytes) of a message pub const MESSAGE_SIZE: usize = 32; @@ -51,7 +51,7 @@ pub const FIELD_SIZE: [u8; 32] = [ 0xff, 0xff, 0xff, 0xfe, 0xff, 0xff, 0xfc, 0x2f ]; -/// The order of the secp256k1 curve +/// The order of the secp256k1 curve. pub const CURVE_ORDER: [u8; 32] = [ 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, @@ -59,7 +59,7 @@ pub const CURVE_ORDER: [u8; 32] = [ 0xbf, 0xd2, 0x5e, 0x8c, 0xd0, 0x36, 0x41, 0x41 ]; -/// The X coordinate of the generator +/// The X coordinate of the generator. pub const GENERATOR_X: [u8; 32] = [ 0x79, 0xbe, 0x66, 0x7e, 0xf9, 0xdc, 0xbb, 0xac, 0x55, 0xa0, 0x62, 0x95, 0xce, 0x87, 0x0b, 0x07, @@ -67,7 +67,7 @@ pub const GENERATOR_X: [u8; 32] = [ 0x59, 0xf2, 0x81, 0x5b, 0x16, 0xf8, 0x17, 0x98 ]; -/// The Y coordinate of the generator +/// The Y coordinate of the generator. pub const GENERATOR_Y: [u8; 32] = [ 0x48, 0x3a, 0xda, 0x77, 0x26, 0xa3, 0xc4, 0x65, 0x5d, 0xa4, 0xfb, 0xfc, 0x0e, 0x11, 0x08, 0xa8, diff --git a/src/context.rs b/src/context.rs index 15a4b20..1331f5d 100644 --- a/src/context.rs +++ b/src/context.rs @@ -11,7 +11,7 @@ pub use self::alloc_only::*; #[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 +/// Module implementing a singleton pattern for a global `Secp256k1` context. pub mod global { #[cfg(feature = "rand-std")] use rand; @@ -20,7 +20,7 @@ pub mod global { use std::sync::Once; use {Secp256k1, All}; - /// Proxy struct for global `SECP256K1` context + /// Proxy struct for global `SECP256K1` context. #[derive(Debug, Copy, Clone)] pub struct GlobalContext { __private: (), @@ -98,8 +98,8 @@ pub struct AllPreallocated<'buf> { mod private { use super::*; // A trick to prevent users from implementing a trait. - // on one hand this trait is public, on the other it's in a private module - // so it's not visible to anyone besides it's parent (the context module) + // On one hand this trait is public, on the other it's in a private module + // so it's not visible to anyone besides it's parent (the context module). pub trait Sealed {} impl<'buf> Sealed for AllPreallocated<'buf> {} @@ -289,7 +289,7 @@ unsafe impl<'buf> Context for VerifyOnlyPreallocated<'buf> { const DESCRIPTION: &'static str = "verification only"; unsafe fn deallocate(_ptr: *mut u8, _size: usize) { - // Allocated by the user + // Allocated by the user. } } @@ -298,7 +298,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> { const DESCRIPTION: &'static str = "all capabilities"; unsafe fn deallocate(_ptr: *mut u8, _size: usize) { - // Allocated by the user + // Allocated by the user. } } @@ -328,7 +328,7 @@ impl<'buf> Secp256k1> { pub fn preallocated_new(buf: &'buf mut [AlignedType]) -> Result>, Error> { Secp256k1::preallocated_gen_new(buf) } - /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for a context + /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for a context. pub fn preallocate_size() -> usize { Self::preallocate_size_gen() } @@ -354,12 +354,12 @@ impl<'buf> Secp256k1> { } impl<'buf> 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. pub fn preallocated_signing_only(buf: &'buf mut [AlignedType]) -> Result>, Error> { Secp256k1::preallocated_gen_new(buf) } - /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context + /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context. #[inline] pub fn preallocate_signing_size() -> usize { Self::preallocate_size_gen() @@ -374,7 +374,7 @@ impl<'buf> Secp256k1> { /// * The capabilities (All/SignOnly/VerifyOnly) of the context *must* match the flags passed to libsecp256k1 /// when generating the context. /// * The user must handle the freeing of the context(using the correct functions) by himself. - /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior., + /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior. /// pub unsafe fn from_raw_signining_only(raw_ctx: *mut ffi::Context) -> ManuallyDrop>> { ManuallyDrop::new(Secp256k1 { @@ -391,7 +391,7 @@ impl<'buf> Secp256k1> { Secp256k1::preallocated_gen_new(buf) } - /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context + /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context. #[inline] pub fn preallocate_verification_size() -> usize { Self::preallocate_size_gen() @@ -406,7 +406,7 @@ impl<'buf> Secp256k1> { /// * The capabilities (All/SignOnly/VerifyOnly) of the context *must* match the flags passed to libsecp256k1 /// when generating the context. /// * The user must handle the freeing of the context(using the correct functions) by himself. - /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior., + /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior. /// pub unsafe fn from_raw_verification_only(raw_ctx: *mut ffi::Context) -> ManuallyDrop>> { ManuallyDrop::new(Secp256k1 { diff --git a/src/ecdh.rs b/src/ecdh.rs index 30ad59e..a96d8de 100644 --- a/src/ecdh.rs +++ b/src/ecdh.rs @@ -13,7 +13,7 @@ // //! # ECDH -//! Support for shared secret computations +//! Support for shared secret computations. //! use core::ptr; diff --git a/src/ecdsa/recovery.rs b/src/ecdsa/recovery.rs index ca367de..4b1488f 100644 --- a/src/ecdsa/recovery.rs +++ b/src/ecdsa/recovery.rs @@ -25,11 +25,11 @@ use ffi::recovery as ffi; use super::*; use {Verification, Secp256k1, Signing, Message}; -/// A tag used for recovering the public key from a compact signature +/// A tag used for recovering the public key from a compact signature. #[derive(Copy, Clone, PartialEq, Eq, Debug)] pub struct RecoveryId(i32); -/// An ECDSA signature with a recovery ID for pubkey recovery +/// An ECDSA signature with a recovery ID for pubkey recovery. #[derive(Copy, Clone, PartialEq, Eq, Debug)] pub struct RecoverableSignature(ffi::RecoverableSignature); @@ -53,8 +53,7 @@ pub fn to_i32(self) -> i32 { impl RecoverableSignature { #[inline] /// Converts a compact-encoded byte slice to a signature. This - /// representation is nonstandard and defined by the libsecp256k1 - /// library. + /// representation is nonstandard and defined by the libsecp256k1 library. pub fn from_compact(data: &[u8], recid: RecoveryId) -> Result { if data.is_empty() {return Err(Error::InvalidSignature);} @@ -77,20 +76,20 @@ impl RecoverableSignature { } } - /// Obtains a raw pointer suitable for use with FFI functions + /// Obtains a raw pointer suitable for use with FFI functions. #[inline] pub fn as_ptr(&self) -> *const ffi::RecoverableSignature { &self.0 } - /// Obtains a raw mutable pointer suitable for use with FFI functions + /// Obtains a raw mutable pointer suitable for use with FFI functions. #[inline] pub fn as_mut_ptr(&mut self) -> *mut ffi::RecoverableSignature { &mut self.0 } #[inline] - /// Serializes the recoverable signature in compact format + /// Serializes the recoverable signature in compact format. pub fn serialize_compact(&self) -> (RecoveryId, [u8; 64]) { let mut ret = [0u8; 64]; let mut recid = 0i32; @@ -107,7 +106,7 @@ impl RecoverableSignature { } /// Converts a recoverable signature to a non-recoverable one (this is needed - /// for verification + /// for verification). #[inline] pub fn to_standard(&self) -> Signature { unsafe { @@ -135,7 +134,7 @@ impl CPtr for RecoverableSignature { } } -/// Creates a new recoverable signature from a FFI one +/// Creates a new recoverable signature from a FFI one. impl From for RecoverableSignature { #[inline] fn from(sig: ffi::RecoverableSignature) -> RecoverableSignature { @@ -144,7 +143,7 @@ impl From for RecoverableSignature { } impl Secp256k1 { - /// Constructs a signature for `msg` using the secret key `sk` and RFC6979 nonce + /// Constructs a signature for `msg` using the secret key `sk` and RFC6979 nonce. /// Requires a signing-capable context. #[deprecated(since = "0.21.0", note = "Use sign_ecdsa_recoverable instead.")] pub fn sign_recoverable(&self, msg: &Message, sk: &key::SecretKey) -> RecoverableSignature { diff --git a/src/key.rs b/src/key.rs index 562f02e..33bdeb2 100644 --- a/src/key.rs +++ b/src/key.rs @@ -57,7 +57,7 @@ impl str::FromStr for SecretKey { } } -/// The number 1 encoded as a secret key +/// The number 1 encoded as a secret key. pub const ONE_KEY: SecretKey = SecretKey([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, @@ -344,7 +344,7 @@ impl PublicKey { unsafe { let mut pk = ffi::PublicKey::new(); // We can assume the return value because it's not possible to construct - // an invalid `SecretKey` without transmute trickery or something + // an invalid `SecretKey` without transmute trickery or something. let res = ffi::secp256k1_ec_pubkey_create(secp.ctx, &mut pk, sk.as_c_ptr()); debug_assert_eq!(res, 1); PublicKey(pk) diff --git a/src/lib.rs b/src/lib.rs index c007c98..2abe90f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -205,7 +205,7 @@ pub use context::global::SECP256K1; use hashes::Hash; // Backwards compatible changes -/// Schnorr Sig related methods +/// Schnorr Signature related methods. #[deprecated(since = "0.21.0", note = "Use schnorr instead.")] pub mod schnorrsig { #[deprecated(since = "0.21.0", note = "Use crate::XOnlyPublicKey instead.")] @@ -255,7 +255,7 @@ impl ThirtyTwoByteHash for hashes::sha256t::Hash { } } -/// A (hashed) message input to an ECDSA signature +/// A (hashed) message input to an ECDSA signature. pub struct Message([u8; constants::MESSAGE_SIZE]); impl_array_newtype!(Message, u8, constants::MESSAGE_SIZE); impl_pretty_debug!(Message); @@ -302,7 +302,7 @@ impl Message { } impl From for Message { - /// Converts a 32-byte hash directly to a message without error paths + /// Converts a 32-byte hash directly to a message without error paths. fn from(t: T) -> Message { Message(t.into_32()) } @@ -314,21 +314,21 @@ pub enum Error { /// Signature failed verification IncorrectSignature, /// Badly sized message ("messages" are actually fixed-sized digests; see the `MESSAGE_SIZE` - /// constant) + /// constant). InvalidMessage, - /// Bad public key + /// Bad public key. InvalidPublicKey, - /// Bad signature + /// Bad signature. InvalidSignature, - /// Bad secret key + /// Bad secret key. InvalidSecretKey, - /// Bad recovery id + /// Bad recovery id. InvalidRecoveryId, /// Invalid tweak for add_*_assign or mul_*_assign InvalidTweak, - /// Didn't pass enough memory to context creation with preallocated memory + /// Didn't pass enough memory to context creation with preallocated memory. NotEnoughMemory, - /// Bad set of public keys + /// Bad set of public keys. InvalidPublicKeySum, /// The only valid parity values are 0 or 1. InvalidParityValue, @@ -351,7 +351,7 @@ impl Error { } } -// Passthrough Debug to Display, since errors should be user-visible +// Passthrough Debug to Display, since errors should be user-visible. impl fmt::Display for Error { fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> { f.write_str(self.as_str()) @@ -363,16 +363,16 @@ impl fmt::Display for Error { impl std::error::Error for Error {} -/// The secp256k1 engine, used to execute all signature operations +/// The secp256k1 engine, used to execute all signature operations. pub struct Secp256k1 { ctx: *mut ffi::Context, phantom: PhantomData, size: usize, } -// The underlying secp context does not contain any references to memory it does not own +// The underlying secp context does not contain any references to memory it does not own. unsafe impl Send for Secp256k1 {} -// The API does not permit any mutation of `Secp256k1` objects except through `&mut` references +// The API does not permit any mutation of `Secp256k1` objects except through `&mut` references. unsafe impl Sync for Secp256k1 {} impl PartialEq for Secp256k1 { @@ -406,7 +406,7 @@ impl Secp256k1 { &self.ctx } - /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all) + /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all). pub fn preallocate_size_gen() -> usize { let word_size = mem::size_of::(); let bytes = unsafe { ffi::secp256k1_context_preallocated_size(C::FLAGS) }; From c3be285c1dbad037609f9f11a61c4aa12d6f370e Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 10:54:32 +1100 Subject: [PATCH 03/10] Fix size constant docs Make all the various size constant docs uniform by using form 'The size ...' and also by ending with a period. --- src/constants.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/constants.rs b/src/constants.rs index 5754183..8da0e8c 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -16,31 +16,31 @@ //! # Constants //! Constants related to the API and the underlying curve. -/// The size (in bytes) of a message +/// The size (in bytes) of a message. pub const MESSAGE_SIZE: usize = 32; -/// The size (in bytes) of a secret key +/// The size (in bytes) of a secret key. pub const SECRET_KEY_SIZE: usize = 32; /// The size (in bytes) of a serialized public key. pub const PUBLIC_KEY_SIZE: usize = 33; -/// The size (in bytes) of an serialized uncompressed public key +/// The size (in bytes) of an serialized uncompressed public key. pub const UNCOMPRESSED_PUBLIC_KEY_SIZE: usize = 65; -/// The maximum size of a signature +/// The maximum size of a signature. pub const MAX_SIGNATURE_SIZE: usize = 72; -/// The maximum size of a compact signature +/// The maximum size of a compact signature. pub const COMPACT_SIGNATURE_SIZE: usize = 64; -/// Size of a Schnorr signature +/// The size of a Schnorr signature. pub const SCHNORRSIG_SIGNATURE_SIZE: usize = 64; -/// Size of a Schnorr public key +/// The size of a Schnorr public key. pub const SCHNORRSIG_PUBLIC_KEY_SIZE: usize = 32; -/// Size of a key pair +/// The size of a key pair. pub const KEY_PAIR_SIZE: usize = 96; /// The Prime for the secp256k1 field element. From d25431c1da9e290518e9e6aaace8c882fd047edb Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 10:58:38 +1100 Subject: [PATCH 04/10] Use 3rd person tense for function docs As is typical in the Rust ecosystem use the third person tense when documenting functions. E.g., ``` /// Creates a new Foo. ``` As opposed to ``` /// Create a new Foo. ``` --- src/ecdh.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/ecdh.rs b/src/ecdh.rs index a96d8de..e0df282 100644 --- a/src/ecdh.rs +++ b/src/ecdh.rs @@ -54,7 +54,7 @@ impl_from_array_len!(SharedSecret, 256, (16 20 28 32 48 64 96 128 256)); impl SharedSecret { - /// Create an empty SharedSecret + /// Creates an empty `SharedSecret`. pub(crate) fn empty() -> SharedSecret { SharedSecret { data: [0u8; 256], @@ -62,27 +62,27 @@ impl SharedSecret { } } - /// Get a pointer to the underlying data with the specified capacity. + /// Gets a pointer to the underlying data with the specified capacity. pub(crate) fn get_data_mut_ptr(&mut self) -> *mut u8 { self.data.as_mut_ptr() } - /// Get the capacity of the underlying data buffer. + /// Gets the capacity of the underlying data buffer. pub fn capacity(&self) -> usize { self.data.len() } - /// Get the len of the used data. + /// Gets the len of the used data. pub fn len(&self) -> usize { self.len } - /// True if the underlying data buffer is empty. + /// Returns true if the underlying data buffer is empty. pub fn is_empty(&self) -> bool { self.data.is_empty() } - /// Set the length of the object. + /// Sets the length of the object. pub(crate) fn set_len(&mut self, len: usize) { debug_assert!(len <= self.data.len()); self.len = len; @@ -116,7 +116,7 @@ unsafe extern "C" fn c_callback(output: *mut c_uchar, x: *const c_uchar, y: *con } impl SharedSecret { - /// Creates a new shared secret from a pubkey and secret key + /// Creates a new shared secret from a pubkey and secret key. #[inline] pub fn new(point: &PublicKey, scalar: &SecretKey) -> SharedSecret { let mut ss = SharedSecret::empty(); @@ -138,7 +138,7 @@ impl SharedSecret { } - /// Creates a new shared secret from a pubkey and secret key with applied custom hash function + /// Creates a new shared secret from a pubkey and secret key with applied custom hash function. /// The custom hash function must be in the form of `fn(x: [u8;32], y: [u8;32]) -> SharedSecret` /// `SharedSecret` can be easily created via the `From` impl from arrays. /// # Examples From f5e68f3ba76d734d9ef2a4ef9cad89879622958a Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 11:20:01 +1100 Subject: [PATCH 05/10] Add ticks around code snippet For added clarity add ticks around words that are code. --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 2abe90f..af17993 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -324,7 +324,7 @@ pub enum Error { InvalidSecretKey, /// Bad recovery id. InvalidRecoveryId, - /// Invalid tweak for add_*_assign or mul_*_assign + /// Invalid tweak for `add_*_assign` or `mul_*_assign`. InvalidTweak, /// Didn't pass enough memory to context creation with preallocated memory. NotEnoughMemory, From 3fa67624375ba529ad37f7786ca759224ff139fd Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 11:28:21 +1100 Subject: [PATCH 06/10] Add link to referenced commit To save devs looking up the commit themselves add a link to it in the rustdoc. --- src/lib.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index af17993..018df93 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -414,9 +414,10 @@ impl Secp256k1 { (bytes + word_size - 1) / word_size } - /// (Re)randomizes the Secp256k1 context for cheap sidechannel resistance; - /// see comment in libsecp256k1 commit d2275795f by Gregory Maxwell. Requires - /// compilation with "rand" feature. + /// (Re)randomizes the Secp256k1 context for cheap sidechannel resistance. + /// + /// Requires compilation with "rand" feature. See comment by Gregory Maxwell in + /// [libsecp256k1](https://github.com/bitcoin-core/secp256k1/commit/d2275795ff22a6f4738869f5528fbbb61738aa48). #[cfg(any(test, feature = "rand"))] #[cfg_attr(docsrs, doc(cfg(feature = "rand")))] pub fn randomize(&mut self, rng: &mut R) { From c9e6ca168000aa3b0aea128048a7f7a40986398c Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 18 Nov 2021 11:55:22 +1100 Subject: [PATCH 07/10] Use rust-bitcoin module doc style Recently we introduced uniform styling for module docs over in `rust-bitcoin` repo. We can do the same here but its a bit controversial because it removes the heading from module docs and every single public module in rust-secp256k1 uses a heading. Instead we use a full sentences. Also makes uniform the trailing `//!`. --- src/constants.rs | 2 +- src/ecdh.rs | 1 - src/ecdsa/recovery.rs | 2 +- src/lib.rs | 1 - 4 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/constants.rs b/src/constants.rs index 8da0e8c..07b9d02 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -13,8 +13,8 @@ // If not, see . // -//! # Constants //! Constants related to the API and the underlying curve. +//! /// The size (in bytes) of a message. pub const MESSAGE_SIZE: usize = 32; diff --git a/src/ecdh.rs b/src/ecdh.rs index e0df282..0897ddc 100644 --- a/src/ecdh.rs +++ b/src/ecdh.rs @@ -12,7 +12,6 @@ // If not, see . // -//! # ECDH //! Support for shared secret computations. //! diff --git a/src/ecdsa/recovery.rs b/src/ecdsa/recovery.rs index 4b1488f..2a3f4bc 100644 --- a/src/ecdsa/recovery.rs +++ b/src/ecdsa/recovery.rs @@ -13,9 +13,9 @@ // If not, see . // -//! # Recovery module //! Provides a signing function that allows recovering the public key from the //! signature. +//! use core::ptr; use key; diff --git a/src/lib.rs b/src/lib.rs index 018df93..e3725e5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,7 +13,6 @@ // If not, see . // -//! # Secp256k1 //! Rust bindings for Pieter Wuille's secp256k1 library, which is used for //! fast and accurate manipulation of ECDSA signatures on the secp256k1 //! curve. Such signatures are used extensively by the Bitcoin network From f95e91a6dac2b585e868910119e22599b242911e Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 10 Feb 2022 09:54:35 +0000 Subject: [PATCH 08/10] Use isn't instead of shouldn't This definitely isn't possible, change the phrase. --- src/context.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/context.rs b/src/context.rs index 1331f5d..e91eeb1 100644 --- a/src/context.rs +++ b/src/context.rs @@ -61,7 +61,7 @@ pub mod global { /// A trait for all kinds of contexts that lets you define the exact flags and a function to -/// deallocate memory. It shouldn't be possible to implement this for types outside this crate. +/// deallocate memory. It isn't possible to implement this for types outside this crate. pub unsafe trait Context : private::Sealed { /// Flags for the ffi. const FLAGS: c_uint; From c79eb976ca4c5cd02275b4f3c843380f64f563b7 Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 10 Feb 2022 09:55:41 +0000 Subject: [PATCH 09/10] Remove unnecessary explanation The nested pub inside a private module is easy to understand, we do not need an explanation. --- src/context.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/context.rs b/src/context.rs index e91eeb1..71efbfa 100644 --- a/src/context.rs +++ b/src/context.rs @@ -97,9 +97,6 @@ pub struct AllPreallocated<'buf> { mod private { use super::*; - // A trick to prevent users from implementing a trait. - // On one hand this trait is public, on the other it's in a private module - // so it's not visible to anyone besides it's parent (the context module). pub trait Sealed {} impl<'buf> Sealed for AllPreallocated<'buf> {} From c73eb2f391d797256fb09545584c998d723d6f72 Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Thu, 10 Feb 2022 09:57:15 +0000 Subject: [PATCH 10/10] Use 'extra' instead of 'cheap' The word 'extra' better describes the sidechannel resistance gained by re-randomising the context. --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index e3725e5..eddb099 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -413,7 +413,7 @@ impl Secp256k1 { (bytes + word_size - 1) / word_size } - /// (Re)randomizes the Secp256k1 context for cheap sidechannel resistance. + /// (Re)randomizes the Secp256k1 context for extra sidechannel resistance. /// /// Requires compilation with "rand" feature. See comment by Gregory Maxwell in /// [libsecp256k1](https://github.com/bitcoin-core/secp256k1/commit/d2275795ff22a6f4738869f5528fbbb61738aa48). @@ -425,7 +425,7 @@ impl Secp256k1 { self.seeded_randomize(&seed); } - /// (Re)randomizes the Secp256k1 context for cheap sidechannel resistance given 32 bytes of + /// (Re)randomizes the Secp256k1 context for extra sidechannel resistance given 32 bytes of /// cryptographically-secure random data; /// see comment in libsecp256k1 commit d2275795f by Gregory Maxwell. pub fn seeded_randomize(&mut self, seed: &[u8; 32]) {