ec_sig.ml
(** Basic interface for elliptic curves *)
module type BASE = sig
exception Not_on_curve of Bytes.t
(** Represents an element on the curve. In the case of a curve with a
cofactor, the element is not necessarily in the prime subgroup.
*)
type t
(** The size of a point representation, in bytes *)
val size_in_bytes : int
module Scalar : Bls12_381.Ff_sig.PRIME
module Base : Bls12_381.Ff_sig.PRIME
(** Check if a point, represented as a byte array, is on the curve **)
val check_bytes : Bytes.t -> bool
(** Attempt to construct a point from a byte array *)
val of_bytes_opt : Bytes.t -> t option
(** Attempt to construct a point from a byte array.
Raise [Not_on_curve] if the point is not on the curve
*)
val of_bytes_exn : Bytes.t -> t
(** Return a representation in bytes *)
val to_bytes : t -> Bytes.t
(** Zero of the elliptic curve *)
val zero : t
(** A fixed generator of the elliptic curve *)
val one : t
(** Return [true] if the given element is zero *)
val is_zero : t -> bool
(** Generate a random element *)
val random : ?state:Random.State.t -> unit -> t
(** Return the addition of two element *)
val add : t -> t -> t
(** Double the element *)
val double : t -> t
(** Return the opposite of the element *)
val negate : t -> t
(** Return [true] if the two elements are algebraically the same *)
val eq : t -> t -> bool
(** Multiply an element by a scalar *)
val mul : t -> Scalar.t -> t
end
(** Curve in Weierstrass form with a and b. In affine, the curve has the
equation form y² = x³ + ax + b *)
module type WeierstrassT = sig
include BASE
val a : Base.t
val b : Base.t
val cofactor : Z.t
end
module type AffineWeierstrassT = sig
include WeierstrassT
val get_x_coordinate : t -> Base.t
val get_y_coordinate : t -> Base.t
(* val to_montgomery_curve_parameters : unit -> (Base.t * Base.t * Z.t * (Base.t * Base.t)) option
val to_montgomery : t -> (Base.t * Base.t) option *)
(** [is_on_curve ~x ~y] returns [true] if the coordinates [(x, y)] represents
a point on the curve. It does not check the point is in the prime subgroup.
*)
val is_on_curve : x:Base.t -> y:Base.t -> bool
(** [is_in_prime_subgroup ~x ~y] returns [true] if the coordinates [(x, y)]
represents a point in the prime subgroup. The coordinates must be a point
on the curve
*)
val is_in_prime_subgroup : x:Base.t -> y:Base.t -> bool
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, returns [None]
*)
val from_coordinates_opt : x:Base.t -> y:Base.t -> t option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, raise [Not_on_curve].
*)
val from_coordinates_exn : x:Base.t -> y:Base.t -> t
(** Build a point from a compressed representation. It supposes the base field
leaves at least a free bit in the last byte to encode the sign.
Raise [Not_on_curve] if the bytes do not represent a point on the curve
and in the prime subgroup.
*)
val of_compressed_bytes_exn : Bytes.t -> t
(** Same than [of_compressed_bytes_exn] but returns an option instead of
raising an exception
*)
val of_compressed_bytes_opt : Bytes.t -> t option
(** Return the compressed representation of the point *)
val to_compressed_bytes : t -> Bytes.t
end
module type ProjectiveWeierstrassT = sig
include WeierstrassT
(** [is_on_curve ~x ~y ~z] returns [true] if the coordinates [(x, y, z)]
represents a point on the curve. It does not check the point is in the
prime subgroup.
*)
val is_on_curve : x:Base.t -> y:Base.t -> z:Base.t -> bool
(** [is_in_prime_subgroup ~x ~y ~z] returns [true] if the coordinates
[(x, y, z)] represents a point in the prime subgroup. The coordinates must
be a point on the curve.
*)
val is_in_prime_subgroup : x:Base.t -> y:Base.t -> z:Base.t -> bool
val get_x_coordinate : t -> Base.t
val get_y_coordinate : t -> Base.t
val get_z_coordinate : t -> Base.t
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, returns [None]
*)
val from_coordinates_opt : x:Base.t -> y:Base.t -> z:Base.t -> t option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, raise [Not_on_curve].
*)
val from_coordinates_exn : x:Base.t -> y:Base.t -> z:Base.t -> t
val get_affine_x_coordinate : t -> Base.t
val get_affine_y_coordinate : t -> Base.t
val from_affine_coordinates_exn : x:Base.t -> y:Base.t -> t
val from_affine_coordinates_opt : x:Base.t -> y:Base.t -> t
end
module type JacobianWeierstrassT = sig
include WeierstrassT
(** [is_on_curve ~x ~y ~z] returns [true] if the coordinates [(x, y, z)] represents
a point on the curve. It does not check the point is in the prime subgroup.
*)
val is_on_curve : x:Base.t -> y:Base.t -> z:Base.t -> bool
(** [is_in_prime_subgroup ~x ~y ~z] returns [true] if the coordinates [(x, y, z)]
represents a point in the prime subgroup. The coordinates must be a point
on the curve
*)
val is_in_prime_subgroup : x:Base.t -> y:Base.t -> z:Base.t -> bool
val get_x_coordinate : t -> Base.t
val get_y_coordinate : t -> Base.t
val get_z_coordinate : t -> Base.t
(** Build a point from the projective coordinates. If the point is not on the curve
and in the subgroup, returns [None]
*)
val from_coordinates_opt : x:Base.t -> y:Base.t -> z:Base.t -> t option
(** Build a point from the projective coordinates. If the point is not on the curve
and in the subgroup, raise [Not_on_curve].
*)
val from_coordinates_exn : x:Base.t -> y:Base.t -> z:Base.t -> t
val get_affine_x_coordinate : t -> Base.t
val get_affine_y_coordinate : t -> Base.t
val from_affine_coordinates_exn : x:Base.t -> y:Base.t -> t
val from_affine_coordinates_opt : x:Base.t -> y:Base.t -> t
end
module type MontgomeryT = sig
include BASE
val a : Base.t
val b : Base.t
val cofactor : Z.t
end
module type AffineMontgomeryT = sig
(** by^2 = x3 + ax^2 + x with b * (a^2 - 4) != 0*)
include MontgomeryT
(** [is_on_curve ~x ~y] returns [true] if the coordinates [(x, y)] represents
a point on the curve. It does not check the point is in the prime subgroup.
*)
val is_on_curve : x:Base.t -> y:Base.t -> bool
(** [is_in_prime_subgroup ~x ~y] returns [true] if the coordinates [(x, y)]
represents a point in the prime subgroup. The coordinates must be a point
on the curve
*)
val is_in_prime_subgroup : x:Base.t -> y:Base.t -> bool
val get_x_coordinate : t -> Base.t
val get_y_coordinate : t -> Base.t
val to_twisted_curve_parameters :
unit -> (Base.t * Base.t * Z.t * (Base.t * Base.t)) option
val to_twisted : t -> (Base.t * Base.t) option
val to_weierstrass_curve_parameters :
unit -> (Base.t * Base.t * Z.t * (Base.t * Base.t)) option
val to_weierstrass : t -> (Base.t * Base.t) option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, returns [None]
*)
val from_coordinates_opt : x:Base.t -> y:Base.t -> t option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, raise [Not_on_curve].
*)
val from_coordinates_exn : x:Base.t -> y:Base.t -> t
(** Build a point from a compressed representation. It supposes the base field
leaves at least a free bit in the last byte to encode the sign.
Raise [Not_on_curve] if the bytes do not represent a point on the curve
and in the prime subgroup.
*)
val of_compressed_bytes_exn : Bytes.t -> t
(** Same than [of_compressed_bytes_exn] but returns an option instead of
raising an exception
*)
val of_compressed_bytes_opt : Bytes.t -> t option
(** Return the compressed representation of the point *)
val to_compressed_bytes : t -> Bytes.t
end
module type AffineEdwardsT = sig
(** au^2 + v^2 = 1 + du^2v^2 *)
include BASE
(** The parameter [a] of the curve, from the equation a * u^2 + v^2 = 1 + d * u^2 * v^2 *)
val a : Base.t
(** The parameter [d] of the curve, from the equation a * u^2 + v^2 = 1 + d * u^2 * v^2 *)
val d : Base.t
(** The cofactor of the curve. The parameter is used in [is_small_order] and
in the random point generator.
*)
val cofactor : Z.t
(** [is_on_curve ~u ~v] returns [true] if the coordinates [(u, v)] represents
a point on the curve. It does not check the point is in the prime subgroup.
*)
val is_on_curve : u:Base.t -> v:Base.t -> bool
(** [is_in_prime_subgroup ~u ~v] returns [true] if the coordinates [(u, v)]
represents a point in the prime subgroup. The coordinates must be a point
on the curve
*)
val is_in_prime_subgroup : u:Base.t -> v:Base.t -> bool
(** Return the affine coordinate u (such that au^2 + v^2 = 1 + d u^2 v^2 *)
val get_u_coordinate : t -> Base.t
(** Return the affine coordinate u (such that au^2 + v^2 = 1 + d u^2 v^2 *)
val get_v_coordinate : t -> Base.t
val to_montgomery_curve_parameters :
unit -> (Base.t * Base.t * Z.t * (Base.t * Base.t)) option
val to_montgomery : t -> (Base.t * Base.t) option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, returns [None]
*)
val from_coordinates_opt : u:Base.t -> v:Base.t -> t option
(** Build a point from the affine coordinates. If the point is not on the curve
and in the subgroup, raise [Not_on_curve].
*)
val from_coordinates_exn : u:Base.t -> v:Base.t -> t
(** Build a point from the affine coordinates, without verifying the point is
on the curve. Use with precaution.
*)
val unsafe_from_coordinates : u:Base.t -> v:Base.t -> t
end
module type PAIRING = sig
module G1 : BASE
module G2 : BASE
module GT : Bls12_381.Ff_sig.BASE
exception FailToComputeFinalExponentiation of GT.t
val miller_loop : (G1.t * G2.t) list -> GT.t
(** Compute the miller loop on a single tuple of point *)
val miller_loop_simple : G1.t -> G2.t -> GT.t
(** Compute a pairing result of a list of points *)
val pairing : G1.t -> G2.t -> GT.t
(** Compute the final exponentiation of the given point. Returns a [None] if
the point is null *)
val final_exponentiation_opt : GT.t -> GT.t option
(** Compute the final exponentiation of the given point. Raise
[FailToComputeFinalExponentiation] if the point is null *)
val final_exponentiation_exn : GT.t -> GT.t
end
