Skip to content

Commit 476ced6

Browse files
committed
Merge #307: Fixing documentation for BIP 340-related functions
931b560 Fixing documentation for BIP 340-related functions (Dr Maxim Orlovsky) Pull request description: ACKs for top commit: thomaseizinger: ACK 931b560 apoelstra: ACK 931b560 Tree-SHA512: d78fbda138e636c04c6f356e2a41fcdd0270eea710a9af6c965ff90acfd6740bd650a8909638c558badd52d307cbdcd914fa25846236b064ca8c38faccec8be8
2 parents 5dcdffa + 931b560 commit 476ced6

File tree

1 file changed

+38
-20
lines changed

1 file changed

+38
-20
lines changed

src/schnorrsig.rs

Lines changed: 38 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ use rand::thread_rng;
77
#[cfg(any(test, feature = "rand"))]
88
use rand::{CryptoRng, Rng};
99

10-
use super::Error::{InvalidPublicKey, InvalidSecretKey, InvalidSignature};
1110
use super::{from_hex, Error};
1211
use core::{fmt, ptr, str};
1312
use ffi::{self, CPtr};
@@ -108,7 +107,7 @@ impl str::FromStr for PublicKey {
108107
Ok(constants::SCHNORRSIG_PUBLIC_KEY_SIZE) => {
109108
PublicKey::from_slice(&res[0..constants::SCHNORRSIG_PUBLIC_KEY_SIZE])
110109
}
111-
_ => Err(InvalidPublicKey),
110+
_ => Err(Error::InvalidPublicKey),
112111
}
113112
}
114113
}
@@ -123,7 +122,7 @@ impl Signature {
123122
ret[..].copy_from_slice(data);
124123
Ok(Signature(ret))
125124
}
126-
_ => Err(InvalidSignature),
125+
_ => Err(Error::InvalidSignature),
127126
}
128127
}
129128
}
@@ -143,9 +142,11 @@ impl KeyPair {
143142

144143
/// Creates a Schnorr KeyPair directly from generic Secp256k1 secret key
145144
///
146-
/// Panics if internal representation of the provided [`SecretKey`] does not
147-
/// holds correct secret key value obtained from Secp256k1 library
148-
/// previously
145+
/// # Panic
146+
///
147+
/// Panics if internal representation of the provided [`SecretKey`] does not hold correct secret
148+
/// key value obtained from Secp256k1 library previously, specifically when secret key value is
149+
/// out-of-range (0 or in excess of the group order).
149150
#[inline]
150151
pub fn from_secret_key<C: Signing>(
151152
secp: &Secp256k1<C>,
@@ -161,35 +162,44 @@ impl KeyPair {
161162
}
162163
}
163164

164-
/// Creates a Schnorr KeyPair directly from a secret key slice
165+
/// Creates a Schnorr KeyPair directly from a secret key slice.
166+
///
167+
/// # Errors
168+
///
169+
/// [`Error::InvalidSecretKey`] if the provided data has an incorrect length, exceeds Secp256k1
170+
/// field `p` value or the corresponding public key is not even.
165171
#[inline]
166172
pub fn from_seckey_slice<C: Signing>(
167173
secp: &Secp256k1<C>,
168174
data: &[u8],
169175
) -> Result<KeyPair, Error> {
170176
if data.is_empty() || data.len() != constants::SECRET_KEY_SIZE {
171-
return Err(InvalidSecretKey);
177+
return Err(Error::InvalidSecretKey);
172178
}
173179

174180
unsafe {
175181
let mut kp = ffi::KeyPair::new();
176182
if ffi::secp256k1_keypair_create(secp.ctx, &mut kp, data.as_c_ptr()) == 1 {
177183
Ok(KeyPair(kp))
178184
} else {
179-
Err(InvalidSecretKey)
185+
Err(Error::InvalidSecretKey)
180186
}
181187
}
182188
}
183189

184190
/// Creates a Schnorr KeyPair directly from a secret key string
191+
///
192+
/// # Errors
193+
///
194+
/// [`Error::InvalidSecretKey`] if corresponding public key for the provided secret key is not even.
185195
#[inline]
186196
pub fn from_seckey_str<C: Signing>(secp: &Secp256k1<C>, s: &str) -> Result<KeyPair, Error> {
187197
let mut res = [0u8; constants::SECRET_KEY_SIZE];
188198
match from_hex(s, &mut res) {
189199
Ok(constants::SECRET_KEY_SIZE) => {
190200
KeyPair::from_seckey_slice(secp, &res[0..constants::SECRET_KEY_SIZE])
191201
}
192-
_ => Err(InvalidPublicKey),
202+
_ => Err(Error::InvalidPublicKey),
193203
}
194204
}
195205

@@ -218,10 +228,15 @@ impl KeyPair {
218228
*SecretKey::from_keypair(self).as_ref()
219229
}
220230

221-
/// Tweak a keypair by adding the given tweak to the secret key and updating the
222-
/// public key accordingly.
223-
/// Will return an error if the resulting key would be invalid or if
224-
/// the tweak was not a 32-byte length slice.
231+
/// Tweak a keypair by adding the given tweak to the secret key and updating the public key
232+
/// accordingly.
233+
///
234+
/// Will return an error if the resulting key would be invalid or if the tweak was not a 32-byte
235+
/// length slice.
236+
///
237+
/// NB: Will not error if the tweaked public key has an odd value and can't be used for
238+
/// BIP 340-342 purposes.
239+
// TODO: Add checked implementation
225240
#[inline]
226241
pub fn tweak_add_assign<C: Verification>(
227242
&mut self,
@@ -261,7 +276,7 @@ impl PublicKey {
261276
&mut self.0
262277
}
263278

264-
/// Creates a new Schnorr public key from a Schnorr key pair
279+
/// Creates a new Schnorr public key from a Schnorr key pair.
265280
#[inline]
266281
pub fn from_keypair<C: Signing>(secp: &Secp256k1<C>, keypair: &KeyPair) -> PublicKey {
267282
let mut pk_parity = 0;
@@ -279,10 +294,15 @@ impl PublicKey {
279294
}
280295

281296
/// Creates a Schnorr public key directly from a slice
297+
///
298+
/// # Errors
299+
///
300+
/// Returns [`Error::InvalidPublicKey`] if the length of the data slice is not 32 bytes or the
301+
/// slice does not represent a valid Secp256k1 point x coordinate
282302
#[inline]
283303
pub fn from_slice(data: &[u8]) -> Result<PublicKey, Error> {
284304
if data.is_empty() || data.len() != constants::SCHNORRSIG_PUBLIC_KEY_SIZE {
285-
return Err(InvalidPublicKey);
305+
return Err(Error::InvalidPublicKey);
286306
}
287307

288308
unsafe {
@@ -295,15 +315,13 @@ impl PublicKey {
295315
{
296316
Ok(PublicKey(pk))
297317
} else {
298-
Err(InvalidPublicKey)
318+
Err(Error::InvalidPublicKey)
299319
}
300320
}
301321
}
302322

303323
#[inline]
304-
/// Serialize the key as a byte-encoded pair of values. In compressed form
305-
/// the y-coordinate is represented by only a single bit, as x determines
306-
/// it up to one bit.
324+
/// Serialize the key as a byte-encoded x coordinate value (32 bytes).
307325
pub fn serialize(&self) -> [u8; constants::SCHNORRSIG_PUBLIC_KEY_SIZE] {
308326
let mut ret = [0u8; constants::SCHNORRSIG_PUBLIC_KEY_SIZE];
309327

0 commit comments

Comments
 (0)