RELIC Bignums

class petrelic.bn.Bn(num=0)

abs()

binary()

A byte array representing the absolute value

A byte array representation of the absolute value in Big-Endian format (with 8 bit atomic elements). You are responsible for extracting the sign bit separately.

Example:

>>> from binascii import hexlify

>>> bin = Bn(66051).binary()
>>> hexlify(bin) == b'010203'
True

>>> bin = Bn(1337).binary()
>>> hexlify(bin) == b'0539'
True

bn

bool()

Turn Bn into boolean. False if zero, True otherwise.

Examples:

>>> bool(Bn(0))
False
>>> bool(Bn(1337))
True

copy()

Returns a copy of the Bn object.

divmod(other)

Returns the integer division and remainder of this number by another.

Example:

>>> Bn(13).divmod(Bn(9))
(Bn(1), Bn(4))

static from_binary(sbin)

Restore number given its Big-endian representation.

Creates a Big Number from a byte sequence representing the number in Big-endian 8 byte atoms. Only positive values can be represented as byte sequence, and the library user should store the sign bit separately.

Args:

sbin (string): a byte sequence.

Example:

>>> from binascii import unhexlify
>>> byte_seq = unhexlify(b"010203")
>>> Bn.from_binary(byte_seq)
Bn(66051)
>>> (1 * 256**2) + (2 * 256) + 3
66051

static from_decimal(sdec)

Creates a Big Number from a decimal string.

Args:

sdec (string): numeric string possibly starting with minus.

See Also:

str() produces a decimal string from a big number.

Example:

>>> hundred = Bn.from_decimal("100")
>>> str(hundred)
'100'

static from_hex(shex)

Creates a Big Number from a hexadecimal string.

Args:

shex (string): hex (0-F) string possibly starting with minus.

See Also:

hex() produces a hexadecimal representation of a big number.

Example:

>>> Bn.from_hex("FF")
Bn(255)

static from_num(num)

static get_prime(bits, safe=1)

Builds a prime Big Number of length bits.

Args:

bits (int) – the number of bits. safe (int) – 1 for a safe prime, otherwise 0.

static get_random(bits)

Generates a random number of the given number of bits

Args:

bits (int) – The number of bits

Examples:

>>> n = Bn.get_random(10)
>>> n.num_bits() <= 10
True

hex()

The representation of the string in hexadecimal. Synonym for hex(n).

int()

A native python integer representation of the Big Number. Synonym for int(bn).

int_add(other)

Returns the sum of this number with another. Synonym for self + other.

Example:

>>> one100 = Bn(100)
>>> two100 = Bn(200)
>>> two100.int_add(one100) # Function syntax
Bn(300)
>>> two100 + one100        # Operator syntax
Bn(300)

int_div(other)

Returns the integer division of this number by another. Synonym of self / other.

Example:

>>> one100 = Bn(100)
>>> two100 = Bn(200)
>>> two100.int_div(one100) # Function syntax
Bn(2)
>>> two100 // one100        # Operator syntax
Bn(2)

int_mul(other)

Returns the product of this number with another. Synonym for self * other.

Example:

>>> one100 = Bn(100)
>>> two100 = Bn(200)
>>> one100.int_mul(two100) # Function syntax
Bn(20000)
>>> one100 * two100        # Operator syntax
Bn(20000)

int_neg()

Returns the negative of this number. Synonym with -self.

Example:

>>> one100 = Bn(100)
>>> one100.int_neg()
Bn(-100)
>>> -one100
Bn(-100)

int_sub(other)

Returns the difference between this number and another. Synonym for self - other.

Example:

>>> one100 = Bn(100)
>>> two100 = Bn(200)
>>> two100.int_sub(one100) # Function syntax
Bn(100)
>>> two100 - one100        # Operator syntax
Bn(100)

is_bit_set(n)

Returns True if the nth bit is set

Examples:

>>> a = Bn(17) # in binary 10001
>>> a.is_bit_set(0)
True
>>> a.is_bit_set(1)
False
>>> a.is_bit_set(4)
True

is_even()

Returns True if the number is even.

Examples:

>>> Bn(2).is_even()
True
>>> Bn(1337).is_even()
False

is_odd()

Returns True if the number is odd.

Examples:

>>> Bn(2).is_odd()
False
>>> Bn(1337).is_odd()
True

is_prime()

Returns True if the number is prime, with negligible prob. of error.

Examples:

>>> Bn(37).is_prime()
True
>>> Bn(10).is_prime()
False

mod(other)

Returns the remainder of this number modulo another. Synonym for self % other.

Example:

>>> one100 = Bn(100)
>>> two100 = Bn(200)
>>> two100.mod(one100) # Function syntax
Bn(0)
>>> two100 % one100        # Operator syntax
Bn(0)

mod_add(other, m)

Returns the sum of self and other modulo m.

Example:

>>> Bn(10).mod_add(2, 11)
Bn(1)
>>> Bn(10).mod_add(Bn(2), Bn(11))
Bn(1)

mod_inverse(m)

Compute the inverse mod m, such that self * res == 1 mod m.

Example:

>>> Bn(10).mod_inverse(m = Bn(11))
Bn(10)
>>> Bn(10).mod_mul(Bn(10), m = Bn(11)) == Bn(1)
True

mod_mul(other, m)

Return the product of self and other modulo m.

Example:

>>> Bn(10).mod_mul(Bn(2), Bn(11))
Bn(9)

mod_pow(other, m, ctx=None)

Performs the modular exponentiation of self ** other % m.

This function is _not_ constant time.

Example:

>>> one100 = Bn(100)
>>> one100.mod_pow(2, 3)   # Modular exponentiation
Bn(1)

mod_sub(other, m)

Returns the difference of self and other modulo m.

Example:

>>> Bn(10).mod_sub(Bn(2), Bn(11))
Bn(8)

num_bits()

Returns the number of bits representing this Big Number

pow(other, modulo=None)

Returns the number raised to the power other optionally modulo a third number. Synonym with pow(self, other, modulo).

Example:

>>> one100 = Bn(100)
>>> one100.pow(2)      # Function syntax
Bn(10000)
>>> one100 ** 2        # Operator syntax
Bn(10000)
>>> one100.pow(2, 3)   # Modular exponentiation
Bn(1)

random()

Returns a random number 0 < rand < self

TODO: currently it excludes 0, update to include 0

Example:

#>>> r = Bn(100).random() #>>> 0 <= r && r < 100 True

repr()

repr_in_base(radix)

Represent number as string in given base

Args:

radix (int): The number of unique digits (2 <= radix <= 62)

Examples:

>>> Bn(42).repr_in_base(16)
'2A'
>>> Bn(-1024).repr_in_base(2)
'-10000000000'

test()

>>> b = Bn()
>>> b.repr_in_base(2)
'0'