Add BLS12-381

[randombit]

The implementation basically follows the pcurves structure, but simplified, since we are only supporting just the single curve (or rather pair of curves).

G1 and G2 use the Renes-Costello-Batina complete addition and doubling formulas, since those are quite efficient for curves with a = 0.

[Copilot]

Pull request overview

Adds a new BLS12-381 math module to Botan, including scalar arithmetic, G1/G2 group operations, pairings, and RFC 9380 hash-to-curve support. This expands Botan’s low-level primitives for pairing-based protocols (e.g., BLS signatures) and integrates KATs, documentation, examples, and performance benchmarks.

Changes:

• Introduce the Botan::BLS12_381 API (Scalar, G1/G2, Gt) plus the underlying field/tower arithmetic and pairing implementation.
• Add extensive test vectors + tests for point (de)serialization, hash-to-curve, hash-to-scalar, pairing, and multi-pairing.
• Implement RFC 9380 oversize DST handling in expand_message_xmd and add corresponding vectors.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/lib/math/bls12_381/info.txt	Registers the new BLS12-381 module and its dependencies/headers.
src/lib/math/bls12_381/bls12_381.h	Public API for scalars, G1/G2, and pairing target group (Gt).
src/lib/math/bls12_381/bls12_381_fields.h	Internal base-field and Fp2 types used throughout the implementation.
src/lib/math/bls12_381/bls12_381_fe.cpp	Base-field arithmetic, serialization, sqrt, inversion, etc.
src/lib/math/bls12_381/bls12_381_fp2.cpp	Fp2 arithmetic and sqrt used by G2 and the tower.
src/lib/math/bls12_381/bls12_381_tower.h	Internal Fp6/Fp12 tower types needed for pairing and Gt serialization.
src/lib/math/bls12_381/bls12_381_fp6.cpp	Fp6 arithmetic implementation.
src/lib/math/bls12_381/bls12_381_fp12.cpp	Fp12 arithmetic, Frobenius map, cyclotomic squaring, serialization.
src/lib/math/bls12_381/bls12_381_scalar.cpp	Scalar field arithmetic (Montgomery form), serialization, inversion, hashing support.
src/lib/math/bls12_381/bls12_381_point_mul.h	Shared scalar multiplication (CT fixed-window) and MSM (vartime Pippenger).
src/lib/math/bls12_381/bls12_381_g1.cpp	G1 (de)serialization, subgroup check, group operations, scalar mul wiring.
src/lib/math/bls12_381/bls12_381_g2.cpp	G2 (de)serialization, subgroup check, group operations, cofactor clearing hooks.
src/lib/math/bls12_381/bls12_381_pairing.cpp	Optimal ate pairing + shared final exponentiation for (multi-)pairing.
src/lib/math/bls12_381/bls12_381_h2c.cpp	RFC 9380 hash-to-curve for G1/G2 and hash-to-scalar using XMD(SHA-256).
src/lib/math/mp/mp_core.h	Moves/hosts bytes_to_words utility used by pcurves and BLS12-381.
src/lib/math/pcurves/pcurves_impl/pcurves_util.h	Removes bytes_to_words from pcurves utility header (now in mp_core).
src/lib/kdf/xmd/xmd.cpp	Implements RFC 9380 “H2C-OVERSIZE-DST” handling for XMD expand.
src/tests/test_bls12_381.cpp	Adds unit tests + KAT runners for BLS12-381 operations.
src/tests/data/bls12_381/pairing.vec	KAT vectors for single pairing results.
src/tests/data/bls12_381/multi_pairing.vec	KAT vectors for product-of-pairings results.
src/tests/data/bls12_381/h2c_g1.vec	RFC 9380 hash-to-curve vectors for G1.
src/tests/data/bls12_381/h2c_g2.vec	RFC 9380 hash-to-curve vectors for G2.
src/tests/data/bls12_381/h2scalar.vec	RFC 9380 hash-to-scalar vectors (including long DST cases).
src/tests/data/bls12_381/g1_deser.vec	Valid/invalid compressed-point deserialization vectors for G1.
src/tests/data/bls12_381/g2_deser.vec	Valid/invalid compressed-point deserialization vectors for G2.
src/tests/data/pubkey/ec_h2c_xmd.vec	Adds long-DST XMD vectors (RFC 9380) to exercise oversize DST behavior.
doc/api_ref/contents.rst	Adds BLS12-381 to the API reference contents list.
doc/api_ref/bls12_381.rst	New API reference documentation for the BLS12-381 module.
src/examples/bls_signature.cpp	Example implementation of BLS signatures using the new low-level API.
src/cli/perf_bls12_381.cpp	Adds CLI perf benchmarks for scalar mul, deserialization, H2C, and pairings.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.