Crate crypto_bigint[][src]

Expand description

RustCrypto: Cryptographic Big Integers

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Pure Rust implementation of a big integer library which has been designed from the ground-up for use in cryptographic applications.

Provides constant-time, no_std-friendly implementations of modern formulas using const generics.

Documentation

Goals

  • No heap allocations. no_std-friendly.
  • Constant-time by default. Variable-time functions are explicitly marked as such.
  • Leverage what is possible today with const generics on stable rust.
  • Support const fn as much as possible, including decoding big integers from bytes/hex and performing arithmetic operations on them, with the goal of being able to compute values at compile-time.

Minimum Supported Rust Version

Rust 1.56 at a minimum.

License

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

This crate defines a UInt type which is const generic around an inner Limb array, where a Limb is a newtype for a word-sized integer. Thus large integers are represented as a arrays of smaller integers which are sized appropriately for the CPU, giving us some assurances of how arithmetic operations over those smaller integers will behave.

To obtain appropriately sized integers regardless of what a given CPU’s word size happens to be, a number of portable type aliases are provided for integer sizes commonly used in cryptography, for example: U128, U384, U256, U2048, U3072, U4096.

const fn usage

The UInt type provides a number of const fn inherent methods which can be used for initializing and performing arithmetic on big integers in const contexts:

use crypto_bigint::U256;

// Parse a constant from a big endian hexadecimal string.
pub const MODULUS: U256 =
    U256::from_be_hex("ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");

// Compute `MODULUS` shifted right by 1 at compile time
pub const MODULUS_SHR1: U256 = MODULUS.shr_vartime(1);

Trait-based usage

The UInt type itself does not implement the standard arithmetic traits such as Add, Sub, Mul, and Div.

To use these traits you must first pick a wrapper type which determines overflow behavior: Wrapping or Checked.

Wrapping arithmetic
use crypto_bigint::{U256, Wrapping};

let a = Wrapping(U256::MAX);
let b = Wrapping(U256::ONE);
let c = a + b;

// `MAX` + 1 wraps back around to zero
assert_eq!(c.0, U256::ZERO);
Checked arithmetic
use crypto_bigint::{U256, Checked};

let a = Checked::new(U256::ONE);
let b = Checked::new(U256::from(2u8));
let c = a + b;
assert_eq!(c.0.unwrap(), U256::from(3u8))

Modular arithmetic

This library has initial support for modular arithmetic in the form of the AddMod, SubMod, NegMod, and MulMod traits, as well as the support for the Rem trait when used with a NonZero operand.

use crypto_bigint::{AddMod, U256};

// mod 3
let modulus = U256::from(3u8);

// 1 + 1 mod 3 = 2
let a = U256::ONE.add_mod(&U256::ONE, &modulus);
assert_eq!(a, U256::from(2u8));

// 2 + 1 mod 3 = 0
let b = a.add_mod(&U256::ONE, &modulus);
assert_eq!(b, U256::ZERO);

Random number generation

When the rand_core or rand features of this crate are enabled, it’s possible to generate random numbers using any CryptoRng by using the Random trait:

use crypto_bigint::{Random, U256, rand_core::OsRng};

let n = U256::random(&mut OsRng);
Modular random number generation

The RandomMod trait supports generating random numbers with a uniform distribution around a given NonZero modulus.

use crypto_bigint::{NonZero, RandomMod, U256, rand_core::OsRng};

let modulus = NonZero::new(U256::from(3u8)).unwrap();
let n = U256::random_mod(&mut OsRng, &modulus);

Re-exports

pub use subtle;
pub use generic_array;
pub use rand_core;
pub use rlp;
pub use zeroize;

Modules

Type aliases for many constants.

Import prelude for this crate: includes important traits.

Macros

Calculate the number of limbs required to represent the given number of bits.

Structs

Provides intentionally-checked arithmetic on T.

Big integers are represented as an array of smaller CPU word-size integers called “limbs”.

Wrapper type for non-zero integers.

Big unsigned integer.

Provides intentionally-wrapped arithmetic on T.

Traits

Compute self + rhs mod p.

ArrayDecodinggeneric-array

Support for decoding a GenericArray as a big integer.

ArrayEncodinggeneric-array

Support for encoding a big integer as a GenericArray.

Checked addition.

Checked multiplication.

Checked substraction.

Concatenate two numbers into a “wide” twice-width value, using the rhs value as the least significant value.

Encoding support.

Integer type.

Compute self * rhs mod p.

Compute -self mod p.

Randomrand_core

Random number generation support.

RandomModrand_core

Modular random number generation support.

Split a number in half, returning the most significant half followed by the least significant.

Compute self - rhs mod p.

Zero values.

Type Definitions

ByteArraygeneric-array

Alias for a byte array whose size is defined by ArrayEncoding::ByteSize.

Inner integer type that the Limb newtype wraps.

64-bit unsigned big integer

128-bit unsigned big integer

192-bit unsigned big integer

256-bit unsigned big integer

384-bit unsigned big integer

448-bit unsigned big integer

512-bit unsigned big integer

768-bit unsigned big integer

896-bit unsigned big integer

1024-bit unsigned big integer

1536-bit unsigned big integer

1792-bit unsigned big integer

2048-bit unsigned big integer

3072-bit unsigned big integer

3584-bit unsigned big integer

4096-bit unsigned big integer

6144-bit unsigned big integer

8192-bit unsigned big integer

Unsigned wide integer type: double the width of LimbUInt.