Module ECP

Elliptic Curve Point Arithmetic (ECP)

Base arithmetical operations on elliptic curve point coordinates.

ECP arithmetic operations are provided to implement existing and new encryption schemes: they are elliptic curve cryptographic primitives and work the same across different curves.

It is possible to create ECP points instances using the new method. The values of each coordinate can be imported using BIG methods BIG.hex() or BIG.base64().

Once ECP numbers are created in this way, the arithmetic operations of addition, subtraction and multiplication can be executed normally using overloaded operators (+ - *).

Info:

  • Copyright: Dyne.org foundation 2017-2019
  • License: AGPLv3
  • Author: Denis "Jaromil" Roio

Functions

new (coordinates) Create a new ECP point from an OCTET argument containing its coordinates.
generator () Return the generator of the curve: an ECP point that is multiplied by any BIG number to obtain a correspondent point on the curve.
infinity () Return a new ECP infinity point that is definitely not on the curve.
order () Give the order of the curve, a BIG number contained in an octet.
mapit (OCTET) Map an OCTET of exactly 64 bytes length to a point on the curve: the OCTET should be the output of an hash function.
validate (OCTET) Verify that an OCTET really corresponds to an ECP point on the curve.
prime () This function allows to obatain the prime number q used to define an elliptic curve over a finite filed GF(q).
from_zcash (y) This function transforms a serial number in octet notation in a point of an elliptic curve, if associated to.
rhs (x) Allow to calculate the right side of the equation Y^2 = X^3 + 4, the elliptic curve BSL381, as a BIG number.

Class ECP

ecp:affine () Make an existing ECP point affine with its curve
ecp:isinf () Check if a given elliptic curve point is the point at infinity.
ecp:add (num) Add an ECP point to another (commutative and associative operation).
ecp:sub (num) Subtract an ECP point from another (commutative and associative operation).
ecp:negative () Transforms an ECP point into its equivalent negative point on the elliptic curve.
ecp:double () This method transforms an ECP point into the double of its value, multiplying it by two.
ecp:mul (number) Multiply an ECP point by a BIG number.
ecp:eq (point) Compares two ECP objects and returns true if they indicate the same point on the curve (they are equal) or false otherwise.
ecp:octet () Return an octet containing the coordinate of an ECP point on the curve.
ecp:x () Give the X coordinate of the ECP point as a single BIG number.
ecp:y () Give the Y coordinate of the ECP point as a single BIG number.
ecp:__tostring () Allow to change the notation of point of an ellipitc curve from octet in a common used hexadecimal notation.
ecp:to_zcash () It allows to convert a point from an elliptic curve in a serial number used in the context of the cryptocurrency Zcash.


Functions

new (coordinates)
Create a new ECP point from an OCTET argument containing its coordinates.

Parameters:

  • coordinates of the point on the elliptic curve

Returns:

    a new ECP point on the curve

See also:

generator ()
Return the generator of the curve: an ECP point that is multiplied by any BIG number to obtain a correspondent point on the curve.

Returns:

    ECP point of the curve's generator

Usage:

    -- Print the generator of ECP BLS381 in hexadecimal notation
gen = ECP.G():octet():hex()			--.G() is the same of .generator()
print(gen)
-- Output: 0317f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb
infinity ()
Return a new ECP infinity point that is definitely not on the curve.

Returns:

    ECP point to infinity (out of the curve).

Usage:

    --Print the infinity point of ECP BLS381 in hexadecimal notation
inf = ECP.infinity():octet():hex()
print(inf)
-- Output: 7f7f
order ()
Give the order of the curve, a BIG number contained in an octet.

Returns:

    a BIG number containing the curve's order

Usage:

    --Print the order of in hexadecimal notation
ord = ECP.order():octet():hex()
print(ord)
-- Output: 73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001
mapit (OCTET)
Map an OCTET of exactly 64 bytes length to a point on the curve: the OCTET should be the output of an hash function.

Parameters:

  • OCTET resulting from an hash function

Returns:

    an ECP that is univocally linked to the input OCTET

Usage:

    oct = OCTET.new(5)          -- generate an octet oct of length 5 bytes
h = hash.new("sha512")      -- call the hash function SHA512
hash_oct = h:process(oct)   -- applie the hash to the octet oct
EC = ECP.mapit(hash_oct)    -- define the ellipitic curve associated to the octet
validate (OCTET)
Verify that an OCTET really corresponds to an ECP point on the curve.

Parameters:

  • OCTET point to be validated

Returns:

    boolean value: true if valid, false if invalid

Usage:

    oct = OCTET.new(64)         -- generate an octet oct of length 64 bytes
bool = ECP.validate(oct)
if boll then
   	print("true")
else
   	print("false")
end
prime ()
This function allows to obatain the prime number q used to define an elliptic curve over a finite filed GF(q).

Returns:

    the prime number q

Usage:

    --In this case the curve is BLS381
q = ECP.prime() 	--returned as @BIG number
print(q:decimal()) 	--printed as integer
--Output: 4002409555221667393417789825735904156556882819939007885332058136124031650490837864442687629129015664037894272559787
from_zcash (y)
This function transforms a serial number in octet notation in a point of an elliptic curve, if associated to.

Parameters:

  • y an octet

Returns:

    a point on an elliptic curve in octet notation

Usage:

    gen = ECP.generator()
y = gen:to_zcash() --serial number associated to the point gen
point = ECP.from_zcash(y):octet() --point associated to the previous serial number
print(point:hex()) -- the point printed in hexadecimal notation
--Output: 0317f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb
-- It can be checked the previous one is the hexadecimal notation fo the point gen
rhs (x)
Allow to calculate the right side of the equation Y^2 = X^3 + 4, the elliptic curve BSL381, as a BIG number.

Parameters:

  • x as BIG number

Returns:

    Y^2 from the previous equation

Usage:

    x = BIG.from_decimal("2")
y_square = ECP.rhs(x) -- Y^2 from Y^2 = X^3 + 4
print(y_square:decimal())
--Output: 12

Class ECP

Object Methods
ecp:affine ()
Make an existing ECP point affine with its curve

Returns:

    ECP point made affine
ecp:isinf ()
Check if a given elliptic curve point is the point at infinity.

Returns:

    true if it is the point at infinity, false otherwise
ecp:add (num)
Add an ECP point to another (commutative and associative operation).
Can be made using the overloaded operator + between two ECP objects just like the would be numbers.

Parameters:

  • num number to be summed

Returns:

    sum resulting from the addition

Usage:

    gen = ECP.generator()
inf = ECP.infinity()
sum =gen:add(inf)
if sum == gen then print("true")
else print("false")
end
-- Output: true
ecp:sub (num)
Subtract an ECP point from another (commutative and associative operation). Can be made using the overloaded operator - between two ECP objects just like the would be numbers.

Parameters:

  • num number to subtract

Returns:

    new ECP point resulting from the subtraction
ecp:negative ()
Transforms an ECP point into its equivalent negative point on the elliptic curve.

Returns:

    the equivalent negative point

Usage:

    gen = ECP.generator()
inf = ECP.infinity()
inv = gen:negative()
if gen:add(inv) == inf then print("true")
else print("false")
end
--Output: true
ecp:double ()
This method transforms an ECP point into the double of its value, multiplying it by two.

Usage:

    sum = gen:add(gen)	--adding a point (the generator in this case) itself
double = gen:double()	--doubling the value of gen
if sum == double then print("true")
else print("false")
end
--Output: true
ecp:mul (number)
Multiply an ECP point by a BIG number. Can be made using the overloaded operator *

Parameters:

  • number indicating how many times it should be multiplied

Returns:

    new ecp point resulting from the multiplication

Usage:

    gen = ECP.generator()
num = BIG.from_decimal("5")
mult = gen:mul(num)
sum = gen:add(inf)
for i = 1,4,1 do
   	sum = sum:add(gen)
end
if sum == mult then print("true")
else print("false")
end
ecp:eq (point)
Compares two ECP objects and returns true if they indicate the same point on the curve (they are equal) or false otherwise. It can also be executed by using the == overloaded operator.

Parameters:

  • point ecp point to be compared

Returns:

    bool value: true if equal, false if not equal
ecp:octet ()
Return an octet containing the coordinate of an ECP point on the curve.
It can be used to export the value of an ECP point into a string, using OCTET:hex or OCTET:base64 encapsulation. It can be decoded back to an ECP point using ECP:new.

Returns:

    the ECP point as an OCTET sequence

Usage:

    num = BIG.from_decimal("3")
mult = gen:mul(num)
sum = gen:add(inf)
to_octet = mult:octet():hex()
-- returns the hexadecimal notation of mult after having been trasmormed it in an octet
ecp:x ()
Give the X coordinate of the ECP point as a single BIG number.

Returns:

    a BIG number indicating the X coordinate of the point on curve.

Usage:

    --In the following, the method decimal() is used to transfomr in integert the x coordinate of gen
gen = ECP.generator()
x = gen:x()
print(x:decimal())
--Output: 3685416753713387016781088315183077757961620795782546409894578378688607592378376318836054947676345821548104185464507
ecp:y ()
Give the Y coordinate of the ECP point as a single BIG number.

Returns:

    a BIG number indicating the Y coordinate of the point on curve.

Usage:

    Equal to the previous one
ecp:__tostring ()
Allow to change the notation of point of an ellipitc curve from octet in a common used hexadecimal notation.
If one tries to convert a point does not belong to the elliptic curve (as the point at infinity), the method returns nothing.

Returns:

    a string or nothing

Usage:

    gen = ECP.generator()
y = gen:__tostring()
print(y)
--Output: 0317f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb
--The hexadecimal notation of gen
ecp:to_zcash ()
It allows to convert a point from an elliptic curve in a serial number used in the context of the cryptocurrency Zcash.

Returns:

    an octet associated to the point

Usage:

    gen = ECP.generator()
y = gen:to_zcash()
print(y:hex())				--printed the serial number in hexadecimal notation
--Output: 97f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb
generated by LDoc 1.5.0 Last updated 2025-03-25 10:43:18