You'll need Sage to run this code. In addition, you'll need a reasonably modern version of make (GNU make works well).
-
make
--- This preprocesses the sage files. If you don't do this, you'll get an error message telling you to do it. -
make test
--- runs all tests. This takes several minutes. -
Alternatively, most files will self-test if executed with sage, e.g.,
sage suite_p256.sage
. -
make vectors
--- generates all test vectors.
This section gives the correspondence between sections of draft-irtf-cfrg-hash-to-curve-05 and the code in this directory.
common.sage
implements CMOV, sgn0, and sqrt functions described in the document.
It also provides helpers for creating domain separation tags used in the test vectors.
curves.sage
implements 'native' Montgomery and Edwards curve objects similar to
(but less full-featured than) the Sage EllipticCurve() object (which only supports
curves in Weierstrass form). These are intended only for testing---they're slow!
hash_to_field.py
implements OS2IP and I2OSP.
hash_to_field.py
implements the hash_to_field function. The arguments are as follows:
msg
andcount
are the arguments to hash_to_field of the same name.dst
is the domain separation tag.modulus
is p, the characteristic of the target field F.degree
is m, the extension degree of the target field F.blen
is L, the length in bytes of the values that are reduced modulo p.expand_fn
is eitherexpand_message_xof
orexpand_message_xmd
, which are also defined inhash_to_field.py
.hash_fn
is a hash function or XOF from Python's hashlib, e.g.,hashlib.sha256
orhashlib.shake_128
.security_param
is k, the target security level in bits (e.g., 128).
The following files implement the deterministic mappings:
-
Shallue-van de Woestijne:
svdw_generic.sage
-
Simplified SWU:
sswu_generic.sage
-
Elligator 2:
ell2_generic.sage
-
Elligator 2 for Twisted Edwards curves:
ell2edw_generic.sage
All of these have the same interface: they define a class (e.g., GenericSvdW
for
the Shallue-van de Woestijne map) that takes as arguments the field F
(constructed
using Sage's GF()
constructor) and the elliptic curve coefficients A
and B
(or a
and d
, etc.). The return value is an object with a map_to_curve
method
that takes u
in F
as its sole argument.
Cofactor clearing is implemented via scalar multiplication in the hash-to-curve suite framework (see immediately below).
h2c_suite.sage
implements a generic framework for constructing hash-to-curve suites
given the suite parameters. The following files demonstrate how this framework can
be used, and implement all of the suites defined in the draft:
-
suite_p256.sage
,suite_p384.sage
, andsuite_p521.sage
implement the NIST curves. -
suite_25519.sage
andsuite_448.sage
implement the suites to the Edwards and Montgomery curves from RFC 7748. -
suite_secp256k1.sage
implements the suites to the secp256k1 curve. -
suite_bls12381g1.sage
andsuite_bls12381g2.sage
implement the suites to the BLS12-381 curves.
map_check.sage
implements and verifies all rational maps given in this section.
iso_values.sage
constructs the isogenies defined in this section.
sswu_opt.sage
, ell2_25519_opt.sage
, and ell2_448_opt.sage
implement the
optimized mappings given in this section.
z_selection.sage
implements the parameter generation scripts give in this section.
z_values.sage
prints out the Z values for all curves given in Suites.