From 37935674eb5614d2e2ff943f164f193108905312 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Fri, 6 Jul 2018 00:10:21 +0000 Subject: [PATCH 1/7] Add doctest for Scalar::random(). --- src/scalar.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/scalar.rs b/src/scalar.rs index 945691c..d4c921e 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -436,6 +436,21 @@ impl Scalar { /// # Returns /// /// A random scalar within ℤ/lℤ. + /// + /// # Example + /// + /// ``` + /// extern crate rand; + /// # extern crate curve25519_dalek; + /// # + /// # fn main() { + /// use curve25519_dalek::scalar::Scalar; + /// + /// use rand::OsRng; + /// + /// let mut csprng: OsRng = OsRng::new().unwrap(); + /// let a: Scalar = Scalar::random(&mut csprng); + /// # } #[cfg(feature = "std")] pub fn random(rng: &mut T) -> Self { let mut scalar_bytes = [0u8; 64]; From 3854eb0fd84e9d3e4926ee238016aefbfa6a8222 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Fri, 6 Jul 2018 00:10:41 +0000 Subject: [PATCH 2/7] Remove extra line and unneeded XXX comment from Scalar::hash_from_bytes. --- src/scalar.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/scalar.rs b/src/scalar.rs index d4c921e..f490948 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -480,7 +480,6 @@ impl Scalar { /// let s = Scalar::hash_from_bytes::(msg.as_bytes()); /// # } /// ``` - /// pub fn hash_from_bytes(input: &[u8]) -> Scalar where D: Digest + Default { @@ -497,7 +496,6 @@ impl Scalar { pub fn from_hash(hash: D) -> Scalar where D: Digest + Default { - // XXX this seems clumsy let mut output = [0u8; 64]; output.copy_from_slice(hash.result().as_slice()); Scalar::from_bytes_mod_order_wide(&output) From 61daa9dce6c2c5011b63db3e6849d5ad73b2e6d5 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Fri, 6 Jul 2018 00:12:35 +0000 Subject: [PATCH 3/7] Add a doctest for Scalar::from_u64(). --- src/scalar.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/scalar.rs b/src/scalar.rs index f490948..328af05 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -527,6 +527,26 @@ impl Scalar { } /// Construct a scalar from the given `u64`. + /// + /// # Inputs + /// + /// An `u64` to convert to a `Scalar`. + /// + /// # Returns + /// + /// A `Scalar` corresponding to the input `u64`. + /// + /// # Example + /// + /// ``` + /// use curve25519_dalek::scalar::Scalar; + /// + /// let fourtytwo = Scalar::from_u64(42); + /// let six = Scalar::from_u64(6); + /// let seven = Scalar::from_u64(7); + /// + /// assert!(fourtytwo == six * seven); + /// ``` pub fn from_u64(x: u64) -> Scalar { let mut s_bytes = [0u8; 32]; for i in 0..8 { From ff16e93102590ba87f56d6e022745b1a26bfe3e6 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Tue, 17 Jul 2018 00:21:37 +0000 Subject: [PATCH 4/7] Add doctest for Scalar::from_hash(). --- src/lib.rs | 3 +++ src/scalar.rs | 31 +++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index c28ff31..97fbb81 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,6 +37,9 @@ extern crate core; #[cfg(feature = "alloc")] extern crate alloc; +#[cfg(test)] +extern crate sha2; + extern crate rand; extern crate clear_on_drop; extern crate byteorder; diff --git a/src/scalar.rs b/src/scalar.rs index 328af05..3219bfc 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -471,6 +471,7 @@ impl Scalar { /// # extern crate curve25519_dalek; /// # use curve25519_dalek::scalar::Scalar; /// extern crate sha2; + /// /// use sha2::Sha512; /// /// # // Need fn main() here in comment so the doctest compiles @@ -493,6 +494,36 @@ impl Scalar { /// Use this instead of `hash_from_bytes` if it is more convenient /// to stream data into the `Digest` than to pass a single byte /// slice. + /// + /// # Example + /// + /// ``` + /// # extern crate curve25519_dalek; + /// # use curve25519_dalek::scalar::Scalar; + /// extern crate sha2; + /// + /// use sha2::Digest; + /// use sha2::Sha512; + /// + /// # fn main() { + /// let mut h = Sha512::default(); + /// + /// h.input(b"To really appreciate architecture, you may even need to commit a murder."); + /// h.input(b"While the programs used for The Manhattan Transcripts are of the most extreme"); + /// h.input(b"nature, they also parallel the most common formula plot: the archetype of"); + /// h.input(b"murder. Other phantasms were occasionally used to underline the fact that"); + /// h.input(b"perhaps all architecture, rather than being about functional standards, is"); + /// h.input(b"about love and death."); + /// + /// let s = Scalar::from_hash(h); + /// + /// println!("{:?}", s.to_bytes()); + /// assert!(s == Scalar::from_bits([ 21, 88, 208, 252, 63, 122, 210, 152, + /// 154, 38, 15, 23, 16, 167, 80, 150, + /// 192, 221, 77, 226, 62, 25, 224, 148, + /// 239, 48, 176, 10, 185, 69, 168, 11, ])); + /// # } + /// ``` pub fn from_hash(hash: D) -> Scalar where D: Digest + Default { From 74a28559c4acb6fc6bf8d0089d3d628377c42a1c Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Tue, 17 Jul 2018 00:22:34 +0000 Subject: [PATCH 5/7] Add example code for Scalar.to_bytes() and Scalar.as_bytes(). --- src/scalar.rs | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/src/scalar.rs b/src/scalar.rs index 3219bfc..4e9286d 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -533,11 +533,31 @@ impl Scalar { } /// Convert this `Scalar` to its underlying sequence of bytes. + /// + /// # Example + /// + /// ``` + /// use curve25519_dalek::scalar::Scalar; + /// + /// let s: Scalar = Scalar::zero(); + /// + /// assert!(s.to_bytes() == [0u8; 32]); + /// ``` pub fn to_bytes(&self) -> [u8; 32] { self.bytes } - /// View this `Scalar` as a sequence of bytes. + /// View this `Scalar` as its underlying sequence of bytes. + /// + /// # Example + /// + /// ``` + /// use curve25519_dalek::scalar::Scalar; + /// + /// let s: Scalar = Scalar::zero(); + /// + /// assert!(s.as_bytes() == &[0u8; 32]); + /// ``` pub fn as_bytes(&self) -> &[u8; 32] { &self.bytes } From 7b22fe6e87c0be332ad0844010ddd212415316d9 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Fri, 20 Jul 2018 00:04:25 +0000 Subject: [PATCH 6/7] Change the wording on the Scalar::as_bytes() docstring. --- src/scalar.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/scalar.rs b/src/scalar.rs index 4e9286d..6c3bcfe 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -547,7 +547,7 @@ impl Scalar { self.bytes } - /// View this `Scalar` as its underlying sequence of bytes. + /// View the little-endian byte encoding of the integer representing this Scalar. /// /// # Example /// From 73a5f4711adefecdb0f7d74dc31116b7cb042f42 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Fri, 20 Jul 2018 00:06:31 +0000 Subject: [PATCH 7/7] Remove unnecessary extern crate sha2 from test code. --- src/lib.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 97fbb81..c28ff31 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,9 +37,6 @@ extern crate core; #[cfg(feature = "alloc")] extern crate alloc; -#[cfg(test)] -extern crate sha2; - extern crate rand; extern crate clear_on_drop; extern crate byteorder;