diff --git a/src/constants.rs b/src/constants.rs index 668683f..07b9d02 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -13,34 +13,34 @@ // If not, see . // -//! # 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 +/// 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. @@ -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 310da6d..71efbfa 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: (), @@ -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 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; @@ -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> {} @@ -289,7 +286,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 +295,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 +325,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 +351,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 +371,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 +388,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 +403,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..0897ddc 100644 --- a/src/ecdh.rs +++ b/src/ecdh.rs @@ -12,8 +12,7 @@ // If not, see . // -//! # ECDH -//! Support for shared secret computations +//! Support for shared secret computations. //! use core::ptr; @@ -54,7 +53,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 +61,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 +115,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 +137,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 diff --git a/src/ecdsa/recovery.rs b/src/ecdsa/recovery.rs index 1b3ab86..16e4086 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; @@ -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 { @@ -144,7 +143,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 { @@ -153,7 +152,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 e7a0be0..b802a86 100644 --- a/src/key.rs +++ b/src/key.rs @@ -62,7 +62,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, @@ -355,7 +355,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 2e4a1a2..93e1c1a 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 @@ -221,7 +220,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.")] @@ -271,7 +270,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); @@ -318,7 +317,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()) } @@ -345,21 +344,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 + /// 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, @@ -382,7 +381,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()) @@ -394,16 +393,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 { @@ -437,7 +436,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) }; @@ -445,9 +444,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 extra 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) { @@ -456,7 +456,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]) {