Expand description
Big integers for cryptography, in three kinds, each unsigned and signed:
FixedBigUintandFixedBigIntholdNlimbs on the stack, and need no allocator.PaddedBigUintandPaddedBigInthold a width chosen when they are built, on the heap.BigUintandBigInthold as many limbs as their value takes.
The heap types are behind the alloc feature.
N counts limbs, and a limb holds one Word, 64 bits on 64-bit
targets and 32 otherwise, so a width in bits divides by Word::BITS:
use tc_bigint::{FixedBigUint, Word};
type U256 = FixedBigUint<{ 256 / Word::BITS as usize }>;
let x = U256::from(u128::MAX);
let y = &x * &x + 7u32;
assert_eq!(y.div_rem(&x), (x, U256::from(7u8)));
assert_eq!(y.bits(), 256);§Timing
The fixed-width and padded types work in constant time: their running time follows their widths, which are public, and not their values. The big types are variable time, as their length follows their value, and are only for public values. Every method says which it is, and where a public operand, such as a shift or an exponent, decides how far it runs.
§Wiping
The constant-time types wipe, through volatile writes, the working
values an operation of theirs makes and then gives up: the remainder a
division does not return, the power a square takes the place of, the
buffer a padded value outgrows. The values they hand back, and those
they are given, are the caller’s to wipe, through Zeroize or
Zeroizing. What the compiler copies on its own is beyond reach: a value
moved on the stack may leave a copy behind, and a register or a spill may
keep a word of it. The big types wipe nothing of the kind, as they only
hold public values.
Structs§
- BigInt
- Arbitrary-precision signed integer, in two’s complement, kept in as many
limbs as its value takes. Its operations are variable time, as that
length follows the value: only for public values; secret ones go through
PaddedBigInt, whose width does not. - BigUint
- Arbitrary-precision unsigned integer, kept in as many limbs as its value
takes. Its operations are variable time, as that length follows the
value: only for public values; secret ones go through
PaddedBigUint, whose width does not. - Fixed
BigInt - Signed integer of
Nlimbs. - Fixed
BigUint - Unsigned integer of
Nlimbs, on the stack. - Limb
- One storage word.
- Limb
Array Nlimbs, least significant first.- Padded
BigInt - Signed integer whose width is fixed when built.
- Padded
BigUint - Unsigned integer whose width is fixed when built.
Enums§
- Conversion
Error - Error returned by fixed-width conversions.
- Parse
BigInt Error - Error returned while parsing a textual integer.
Traits§
- Array
Encoding - Conversion between integers and slices of
T, such asu8,u32oru64. - BitOps
- Inspecting, counting and changing single bits, which Bouncy Castle names
bit_length,test_bit,set_bit,clear_bit,flip_bitandlowest_set_bit. - Gcd
- The greatest common divisor, which is never negative. Each implementation states whether it is constant time.
- Random
Bits - Random values below a power of two. Each implementation states whether it is constant time.
- Random
Range - Random values in a range. Each implementation states whether it is constant time.