diff --git a/src/signed/base.rs b/src/signed/base.rs index 68906f0..f3a1d3b 100644 --- a/src/signed/base.rs +++ b/src/signed/base.rs @@ -7,26 +7,33 @@ macro_rules! signed_impls { } impl $sname { + /// Generate a new signed number from an unsigned number and a + /// boolean describing whether or not the new number is negative. + /// Note that if the value is zero, the value of the negative flag + /// will be ignored. pub fn new(negative: bool, value: $name) -> $sname { if value.is_zero() { $sname{ negative: false, value: value } } else { - $sname{ negative: negative, value: value } + $sname{ negative: negative, value: value } + } } - } - + + /// Return a new number that is the negated version of this number. pub fn negate(&self) -> $sname { if self.value.is_zero() { self.clone() } else { - $sname{ negative: !self.negative, value: self.value.clone() } + $sname{ negative: !self.negative, value: self.value.clone() } + } } - } - + + /// Return the absolute value of the number. pub fn abs(&self) -> $sname { $sname{ negative: false, value: self.value.clone() } } + /// Return true iff the value is negative and not zero. pub fn is_negative(&self) -> bool { self.negative } diff --git a/src/signed/egcd.rs b/src/signed/egcd.rs index 1f7bb60..0813ab7 100644 --- a/src/signed/egcd.rs +++ b/src/signed/egcd.rs @@ -1,4 +1,8 @@ +/// GCD computations, with extended information pub trait EGCD { + /// Compute the extended GCD for this value and the given value. + /// If the inputs to this function are x (self) and y (the argument), + /// and the results are (a, b, g), then (a * x) + (b * y) = g. fn egcd(&self, rhs: &Self) -> (T, T, T); } diff --git a/src/signed/mod.rs b/src/signed/mod.rs index 0515807..37cf770 100644 --- a/src/signed/mod.rs +++ b/src/signed/mod.rs @@ -1,3 +1,14 @@ +//! This module includes a large number of signed integer types for very +//! large integers, designed to try to match good performance with a high +//! assurance threshold. +//! +//! The types provided in this module, and the functions available for each +//! of those types, is derived from standard bit widths for RSA, DSA, and +//! Elliptic Curve encryption schemes. If this library does not include a +//! function you would like for another cryptographic scheme, please reach +//! out to the authors; in many cases, the relevant code can be automatically +//! generated. +//! #[macro_use] mod add; #[macro_use] diff --git a/src/signed/modinv.rs b/src/signed/modinv.rs index 758a305..6394ef2 100644 --- a/src/signed/modinv.rs +++ b/src/signed/modinv.rs @@ -1,4 +1,8 @@ +/// Computations of the modular inverse. pub trait ModInv: Sized { + /// Compute the modular inverse of this number under the given + /// modulus, if it exists. If self is a, the modulus / argument + /// is phi, and the result is Some(m), then (a * m) % phi = 1. fn modinv(&self, phi: &Self) -> Option; } diff --git a/src/unsigned/barrett.rs b/src/unsigned/barrett.rs index abde097..2044c45 100644 --- a/src/unsigned/barrett.rs +++ b/src/unsigned/barrett.rs @@ -7,6 +7,9 @@ macro_rules! barrett_impl { } impl $bar { + /// Generate a new Barrett number from the given input. This operation + /// is relatively slow, so you should only do it if you plan to use + /// reduce() multiple times with the ame number. pub fn new(m: $name) -> $bar { // Step #1: Figure out k let mut k = 0; @@ -27,7 +30,9 @@ macro_rules! barrett_impl { // Done! $bar { k: k, m: resm, mu: mu } } - + + // Reduce the input by this value; in other words, perform a mod + // operation. pub fn reduce(&self, x: &$dbl) -> $name { // 1. q1←⌊x/bk−1⌋, q2←q1 · μ, q3←⌊q2/bk+1⌋. let q1: $name64 = $name64::from(x >> ((self.k - 1) * 64)); @@ -58,6 +63,7 @@ macro_rules! barrett_impl { } impl $name { + /// Generate a Barrett number from this number. pub fn generate_barrett(&self) -> $bar { $bar::new(self.clone()) } diff --git a/src/unsigned/base.rs b/src/unsigned/base.rs index 78fd9be..b4793b7 100644 --- a/src/unsigned/base.rs +++ b/src/unsigned/base.rs @@ -1,8 +1,15 @@ +/// A trait definition for large numbers. pub trait CryptoNum { + /// Generate a new value of the given type. fn zero() -> Self; + /// Test if the number is zero. fn is_zero(&self) -> bool; + /// Test if the number is even. fn is_even(&self) -> bool; + /// Test if the number is odd. fn is_odd(&self) -> bool; + /// Mask off the high parts of the number. In particular, it + /// zeros the bits above (len * 64). fn mask(&mut self, len: usize); } diff --git a/src/unsigned/codec.rs b/src/unsigned/codec.rs index 5abe898..c4c53c2 100644 --- a/src/unsigned/codec.rs +++ b/src/unsigned/codec.rs @@ -1,7 +1,9 @@ +/// Conversion from bytes into the numeric type. pub trait Decoder { fn from_bytes(x: &[u8]) -> Self; } +/// Conversion from the numeric types into a byte buffer. pub trait Encoder { fn to_bytes(&self) -> Vec; } diff --git a/src/unsigned/div.rs b/src/unsigned/div.rs index 35c4e49..2426f98 100644 --- a/src/unsigned/div.rs +++ b/src/unsigned/div.rs @@ -1,6 +1,9 @@ +/// Concurrent div/mod operations for a number, so that you don't +/// have to do them separately. pub trait DivMod where Self: Sized { + /// Compute the quotient and remainder of a and b. fn divmod(&self, rhs: &Self) -> (Self, Self); } diff --git a/src/unsigned/mod.rs b/src/unsigned/mod.rs index a24c2c6..f7ff3c1 100644 --- a/src/unsigned/mod.rs +++ b/src/unsigned/mod.rs @@ -1,3 +1,18 @@ +//! This module includes a large number of unsigned integer types for very +//! large integers, designed to try to match good performance with a high +//! assurance threshold. +//! +//! The types provided in this module, and the functions available for each +//! of those types, is derived from standard bit widths for RSA, DSA, and +//! Elliptic Curve encryption schemes. If this library does not include a +//! function you would like for another cryptographic scheme, please reach +//! out to the authors; in many cases, the relevant code can be automatically +//! generated. +//! +//! For performance reasons, we also include support for Barrett reduction, +//! which should improve the speed of modular reduction of large numbers for +//! those cases in which you will be frequently performing modulo operations +//! using the same modulus. #[macro_use] mod add; #[macro_use] diff --git a/src/unsigned/modexp.rs b/src/unsigned/modexp.rs index 67b1322..e437d42 100644 --- a/src/unsigned/modexp.rs +++ b/src/unsigned/modexp.rs @@ -1,4 +1,8 @@ +/// Modular exponentiation for a value. pub trait ModExp { + /// Modular exponentiation using the given modulus type. If it's possible, + /// we suggest using Barrett values, which are much faster than doing + /// modulo with the number types. fn modexp(&self, e: &Self, m: &T) -> Self; } diff --git a/src/unsigned/modmul.rs b/src/unsigned/modmul.rs index 8cdbda4..8f63667 100644 --- a/src/unsigned/modmul.rs +++ b/src/unsigned/modmul.rs @@ -1,4 +1,8 @@ +/// Modular multiplication of the type. pub trait ModMul { + /// Modular multiplication using the given modulus type. If it's possible, + /// we suggest using Barrett values, which are much faster than doing + /// modulo with the number types. fn modmul(&self, x: &Self, m: &T) -> Self; } diff --git a/src/unsigned/modsq.rs b/src/unsigned/modsq.rs index d8cfcba..d1e90ca 100644 --- a/src/unsigned/modsq.rs +++ b/src/unsigned/modsq.rs @@ -1,4 +1,8 @@ +/// Modular squaring pub trait ModSquare { + /// Modular squaring using the given modulus type. If it's possible, + /// we suggest using Barrett values, which are much faster than doing + /// modulo with the number types. fn modsq(&self, m: &T) -> Self; } diff --git a/src/unsigned/square.rs b/src/unsigned/square.rs index 63cca56..06d7215 100644 --- a/src/unsigned/square.rs +++ b/src/unsigned/square.rs @@ -1,3 +1,4 @@ +/// Squaring of large numbers. pub trait Square { fn square(&self) -> Output; }