package bls12-381-gen

  1. Overview
  2. Docs
include Ff_sig.BASE
exception Not_in_field of Bytes.t
type t
val order : Z.t

The order of the finite field

val size_in_bytes : int

minimal number of bytes required to encode a value of the field.

val check_bytes : Bytes.t -> bool

check_bytes bs returns true if bs is a correct byte representation of a field element

val zero : t

The neutral element for the addition

val one : t

The neutral element for the multiplication

val is_zero : t -> bool

is_zero x returns true if x is the neutral element for the addition

val is_one : t -> bool

is_one x returns true if x is the neutral element for the multiplication

val random : ?state:Random.State.t -> unit -> t

Use carefully! random () returns a random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed

val non_null_random : ?state:Random.State.t -> unit -> t

Use carefully! non_null_random () returns a non null random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed

val add : t -> t -> t

add a b returns a + b mod order

val (+) : t -> t -> t

Infix operator for add

val sub : t -> t -> t

sub a b returns a - b mod order

val mul : t -> t -> t

mul a b returns a * b mod order

val (*) : t -> t -> t

Infix operator for mul

val eq : t -> t -> bool

eq a b returns true if a = b mod order, else false

val (=) : t -> t -> bool

Infix operator for eq

val negate : t -> t

negate x returns -x mod order. Equivalently, negate x returns the unique y such that x + y mod order = 0

val (-) : t -> t

Infix operator for negate

val inverse_exn : t -> t

inverse_exn x returns x^-1 if x is not 0, else raise Division_by_zero

val inverse_opt : t -> t option

inverse_opt x returns x^-1 if x is not 0 as an option, else None

val div_exn : t -> t -> t

div_exn a b returns a * b^-1. Raise Division_by_zero if b = zero

val div_opt : t -> t -> t option

div_opt a b returns a * b^-1 as an option. Return None if b = zero

val (/) : t -> t -> t

Infix operator for div_exn

val square : t -> t

square x returns x^2

val double : t -> t

double x returns 2x

val pow : t -> Z.t -> t

pow x n returns x^n

val (**) : t -> Z.t -> t

Infix operator for pow

val of_bytes_exn : Bytes.t -> t

Construct a value of type t from the bytes representation in little endian of the field element. For non prime fields, the encoding starts with the coefficient of the constant monomial. Raise Not_in_field if the bytes do not represent an element in the field.

val of_bytes_opt : Bytes.t -> t option

From a predefined little endian bytes representation, construct a value of type t. The same representation than of_bytes_exn is used. Return None if the bytes do not represent an element in the field.

val to_bytes : t -> Bytes.t

Convert the value t to a bytes representation. The number of bytes is size_in_bytes and the encoding must be in little endian. For instance, the encoding of 1 in prime fields is always a bytes sequence of size size_in_bytes starting with the byte 0b00000001. For non prime fields, the encoding starts with the coefficient of the constant monomial.

Construct an element of Fq12 based on the following pattern: Fq12 = Fq6 ( Fq2(x: x0, y: x1)) Fq2(x: x2, y: x3)) Fq2(x: x4, y: x5)), Fq6 ( Fq2(x: x6, y: x7)) Fq2(x: x8, y: x9)) Fq2(x: x10, y: x11)) x0, ..., x11 are the parameters of the function. No check is applied.

Example of usage (pairing result of the multiplicative neutre elements): Fq12.of_string "2819105605953691245277803056322684086884703000473961065716485506033588504203831029066448642358042597501014294104502" "1323968232986996742571315206151405965104242542339680722164220900812303524334628370163366153839984196298685227734799" "2987335049721312504428602988447616328830341722376962214011674875969052835043875658579425548512925634040144704192135" "3879723582452552452538684314479081967502111497413076598816163759028842927668327542875108457755966417881797966271311" "261508182517997003171385743374653339186059518494239543139839025878870012614975302676296704930880982238308326681253" "231488992246460459663813598342448669854473942105054381511346786719005883340876032043606739070883099647773793170614" "3993582095516422658773669068931361134188738159766715576187490305611759126554796569868053818105850661142222948198557" "1074773511698422344502264006159859710502164045911412750831641680783012525555872467108249271286757399121183508900634" "2727588299083545686739024317998512740561167011046940249988557419323068809019137624943703910267790601287073339193943" "493643299814437640914745677854369670041080344349607504656543355799077485536288866009245028091988146107059514546594" "734401332196641441839439105942623141234148957972407782257355060229193854324927417865401895596108124443575283868655" "2348330098288556420918672502923664952620152483128593484301759394583320358354186482723629999370241674973832318248497" (* source for the test vectors: https://docs.rs/crate/pairing/0.16.0/source/src/bls12_381/tests/mod.rs *)

Undefined behaviours if the given elements are not in the field or any other representation than decimal is used. Use this function carefully.

See https://docs.rs/crate/pairing/0.16.0/source/src/bls12_381/README.md for more information on the instances used by the library.

FIXME: the function is not memory efficient because the elements are copied multiple times

val of_z : Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> Z.t -> t

Same than of_string, using Z.t elements FIXME: the function is not memory efficient because the elements are copied multiple times