Add sage script for BN and BLS12 curve families

.gitignore

@@ -9,3 +9,6 @@ build/
 *.la
 *.exe
 *.dll
+
+# Sage
+*.sage.py

constantine/config/curves.nim

@@ -63,6 +63,7 @@ declareCurves:
     bitsize: 254
     modulus: "0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47"
     # Equation: Y^2 = X^3 + 3
+    # u: -(2^62 + 2^55 + 1)
   curve Curve25519: # Bernstein curve
     bitsize: 255
     modulus: "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffed"
@@ -82,6 +83,7 @@ declareCurves:
     bitsize: 381
     modulus: "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab"
     # Equation: y^2 = x^3 + 4
+    # u: -(2^63 + 2^62 + 2^60 + 2^57 + 2^48 + 2^16)
   curve BN446:
     bitsize: 446
     modulus: "0x2400000000000000002400000002d00000000d800000021c0000001800000000870000000b0400000057c00000015c000000132000000067"
@@ -125,7 +127,7 @@ declareCurves:
     # https://hal.archives-ouvertes.fr/hal-01534101/file/main.pdf
     bitsize: 462
     modulus: "0x240480360120023ffffffffff6ff0cf6b7d9bfca0000000000d812908f41c8020ffffffffff6ff66fc6ff687f640000000002401b00840138013"
-    # u = 2^114 + 2^101 − 2^14 − 1
+    # u = 2^114 + 2^101 - 2^14 - 1
 
 # ############################################################
 #

sage/README.md

@@ -0,0 +1,7 @@
+# Sage scripts
+
+This folder holds sage scripts:
+- either for automating curve configuration
+  for example for computing the prime and order of BN or BLS curve families,
+  for irreducible polynomials for extension fields.
+- for test vectors against a reference implementation.

sage/curve_family_bls12.sage

@@ -0,0 +1,25 @@
+def compute_curve_characteristic(u_str):
+  u = sage_eval(u_str)
+  p = (u - 1)^2 * (u^4 - u^2 + 1)//3 + u
+  r = u^4 - u^2 + 1
+
+  print(f'BLS12 family - {p.nbits()} bits')
+  print('  Prime modulus:     0x' + p.hex())
+  print('  Curve order:       0x' + r.hex())
+  print('  Parameter u:       ' + u_str)
+  if u < 0:
+      print('  Parameter u (hex): -0x' + (-u).hex())
+  else:
+      print('  Parameter u (hex):  0x' + u.hex())
+
+if __name__ == "__main__":
+  # Usage
+  # sage '-(2^63 + 2^62 + 2^60 + 2^57 + 2^48 + 2^16)'
+
+  from argparse import ArgumentParser
+
+  parser = ArgumentParser()
+  parser.add_argument("curve_param",nargs="+")
+  args = parser.parse_args()
+
+  compute_curve_characteristic(args.curve_param[0])

sage/curve_family_bn.sage

@@ -0,0 +1,25 @@
+def compute_curve_characteristic(u_str):
+  u = sage_eval(u_str)
+  p = 36*u^4 + 36*u^3 + 24*u^2 + 6*u + 1
+  r = 36*u^4 + 36*u^3 + 18*u^2 + 6*u + 1
+
+  print(f'BN family - {p.nbits()} bits')
+  print('  Prime modulus:     0x' + p.hex())
+  print('  Curve order:       0x' + r.hex())
+  print('  Parameter u:       ' + u_str)
+  if u < 0:
+      print('  Parameter u (hex): -0x' + (-u).hex())
+  else:
+      print('  Parameter u (hex):  0x' + u.hex())
+
+if __name__ == "__main__":
+  # Usage
+  # sage sage/curve_family_bn.sage '-(2^62 + 2^55 + 1)'
+
+  from argparse import ArgumentParser
+
+  parser = ArgumentParser()
+  parser.add_argument("curve_param",nargs="+")
+  args = parser.parse_args()
+
+  compute_curve_characteristic(args.curve_param[0])

tests/generators/README.md

@@ -1,7 +0,0 @@
-# Test vectors generators
-
-Generators for complex tests.
-
-The generators can be written in any language
-and should be from industrial grade libraries (GMP, OpenSSL, ...)
-or cryptography standards (IETF specs, ...)