Botan 3.14.1
Crypto and TLS for C&
bls12_381.h
Go to the documentation of this file.
1/*
2* (C) 2024,2025,2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_BLS12_381_H_
8#define BOTAN_BLS12_381_H_
9
10#include <botan/types.h>
11#include <array>
12#include <optional>
13#include <span>
14#include <vector>
15
17
18// The field element and extension tower types are internal; functions
19// naming these types are reserved for internal use and not covered by SemVer
20class FieldElement;
21class FieldElement2;
22class Fp12;
23
24/**
25* A BLS12-381 scalar
26*
27* Integer modulo 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001
28*/
29class BOTAN_PUBLIC_API(3, 14) Scalar final {
30 public:
31 /** The bit length of the group order r */
32 static constexpr size_t BITS = 255;
33
34 /** The byte length of the canonical scalar encoding */
35 static constexpr size_t BYTES = (BITS + 7) / 8;
36
37 /** The word length of the internal representation */
38 static constexpr size_t N = (BYTES + sizeof(word) - 1) / sizeof(word);
39
40 static_assert(BYTES == N * sizeof(word));
41
42 /** Default constructed as zero */
43 constexpr Scalar() : m_val({}) {}
44
45 /** Copy constructor */
46 Scalar(const Scalar& other) = default;
47
48 /** Copy assignment */
49 Scalar& operator=(const Scalar& other) = default;
50
51 /**
52 * Scalars are commonly secrets, so they are zeroized on
53 * destruction, and moving from a Scalar zeroizes the source
54 */
55 Scalar(Scalar&& other) noexcept : m_val(other.m_val) { other.wipe(); }
56
57 /** Move assignment; the moved-from scalar is zeroized */
58 Scalar& operator=(Scalar&& other) noexcept {
59 if(this != &other) {
60 m_val = other.m_val;
61 other.wipe();
62 }
63 return *this;
64 }
65
66 ~Scalar() { this->wipe(); }
67
68 /** Return the scalar equal to the small integer v */
69 static Scalar from_u32(uint32_t v);
70
71 /** Return the zero scalar */
72 static Scalar zero() { return Scalar(); }
73
74 /** Return the scalar one */
75 static Scalar one();
76
77 /**
78 * Deserialize a scalar from a 32-byte long big-endian encoding
79 *
80 * Returns nullopt unless the encoding is a canonical integer in the
81 * range [1, r). In particular the zero scalar is rejected, since a zero
82 * scalar is almost always a mistake; this matches EC_Scalar::deserialize.
83 *
84 * @note that some implementations of BLS12-381 use little-endian scalar encodings
85 */
86 static std::optional<Scalar> deserialize(std::span<const uint8_t> bytes);
87
88 /**
89 * Reduce a 64 byte big-endian integer modulo r
90 *
91 * Suitable for deriving a uniformly distributed scalar from an
92 * RNG or hash output
93 */
94 static Scalar from_bytes_wide(std::span<const uint8_t, 64> bytes);
95
96 /**
97 * Hash an input to a scalar
98 *
99 * Uses the hash_to_field construction of RFC 9380, namely expand_message_xmd with
100 * SHA-256 followed by wide reduction. The distribution of the result is uniform
101 * (negligibly biased). The domain separation tag dst distinguishes different uses
102 * of the hash; see RFC 9380 section 3.1 for the requirements.
103 *
104 * Throws Invalid_Argument if dst is empty.
105 */
106 static Scalar hash(std::span<const uint8_t> input, std::span<const uint8_t> dst);
107
108 /** Serialize to a 32 byte big-endian encoding */
109 void serialize_to(std::span<uint8_t, Scalar::BYTES> bytes) const;
110
111 /** Return the 32 byte big-endian encoding */
112 std::array<uint8_t, Scalar::BYTES> serialize() const {
113 std::array<uint8_t, Scalar::BYTES> buf{};
114 this->serialize_to(buf);
115 return buf;
116 }
117
118 /** Addition modulo r */
119 Scalar add(const Scalar& x) const;
120
121 /** Subtraction modulo r */
122 Scalar sub(const Scalar& x) const;
123
124 /** Multiplication modulo r */
125 Scalar mul(const Scalar& x) const;
126
127 /** Addition modulo r */
129 (*this) = this->add(x);
130 return (*this);
131 }
132
133 /** Subtraction modulo r */
135 (*this) = this->sub(x);
136 return (*this);
137 }
138
139 /** Multiplication modulo r */
141 (*this) = this->mul(x);
142 return (*this);
143 }
144
145 /** Return the negation of this scalar */
146 Scalar negate() const;
147
148 /** Return the multiplicative inverse of this scalar, or zero for zero */
149 Scalar invert() const;
150
151 /** Return the square of this scalar */
152 Scalar square() const;
153
154 private:
155 // Squaring in place
156 void square_n(size_t n);
157
158 void wipe();
159
160 constexpr const std::array<word, N>& value() const { return m_val; }
161
162 constexpr const word* data() const { return m_val.data(); }
163
164 static Scalar from_words(std::array<word, Scalar::N> v);
165
166 explicit constexpr Scalar(std::array<word, Scalar::N> v) : m_val(v) {}
167
168 std::array<word, Scalar::N> m_val;
169};
170
171/** Addition modulo r */
172inline Scalar operator+(const Scalar& a, const Scalar& b) {
173 return a.add(b);
174}
175
176/** Subtraction modulo r */
177inline Scalar operator-(const Scalar& a, const Scalar& b) {
178 return a.sub(b);
179}
180
181/** Multiplication modulo r */
182inline Scalar operator*(const Scalar& a, const Scalar& b) {
183 return a.mul(b);
184}
185
186/**
187* An element of the group G1, in affine form
188*
189* Group arithmetic is performed on G1Projective; the affine form is
190* used for serialization, pairings, and mixed addition
191*/
192class BOTAN_PUBLIC_API(3, 14) G1Affine final {
193 public:
194 /** The byte length of the compressed point encoding */
195 static constexpr size_t BYTES = 48;
196
197 /**
198 * Return the G1 identity element
199 */
200 static G1Affine identity();
201
202 /**
203 * Return the G1 standard group generator
204 */
205 static G1Affine generator();
206
207 /**
208 * Point deserialization
209 *
210 * Only compressed point encoding is supported.
211 *
212 * This rejects points not in the prime order subgroup. The canonical
213 * encoding of the identity element is accepted; callers for which the
214 * identity is not a legal value (such as BLS public keys) must check
215 * is_identity() themselves.
216 */
217 static std::optional<G1Affine> deserialize(std::span<const uint8_t> bytes);
218
219 /**
220 * Point serialization
221 *
222 * Only compressed point encoding is supported.
223 */
224 std::array<uint8_t, G1Affine::BYTES> serialize() const;
225
226 /**
227 * Check if this point is the identity element
228 */
229 bool is_identity() const;
230
231 /**
232 * Access the coordinates directly; the values are meaningless if
233 * the point is the identity element.
234 *
235 * Reserved for internal use, not covered by SemVer.
236 */
237 FieldElement _x() const;
238 FieldElement _y() const;
239
240 private:
241 friend class G1Projective;
242
243 template <typename Group>
244 friend class GroupOps;
245
246 G1Affine(const FieldElement& x, const FieldElement& y, uint32_t infinity);
247
248 static constexpr size_t FE_WORDS = 48 / sizeof(word);
249
250 std::array<word, FE_WORDS> m_x;
251 std::array<word, FE_WORDS> m_y;
252 uint32_t m_infinity;
253};
254
255/**
256* An element of the group G1, in projective form
257*/
258class BOTAN_PUBLIC_API(3, 14) G1Projective final {
259 public:
260 /**
261 * Default constructed as the identity element
262 */
263 G1Projective();
264
265 /** Convert an affine point to projective form */
266 static G1Projective from_affine(const G1Affine& affine);
267
268 /** Return the G1 identity element */
269 static G1Projective identity() { return G1Projective(); }
270
271 /** Return the G1 standard group generator */
272 static G1Projective generator();
273
274 /** Convert to affine form, at the cost of a field inversion */
275 G1Affine to_affine() const;
276
277 /** Return the negation of this point */
278 G1Projective negate() const;
279
280 /** Return the sum of this point and other */
281 G1Projective add(const G1Projective& other) const;
282
283 /** Return the sum of this point and an affine point */
284 G1Projective add_mixed(const G1Affine& other) const;
285
286 /**
287 * Scalar multiplication
288 *
289 * Constant time; safe for secret scalars
290 */
291 G1Projective mul(const Scalar& scalar) const;
292
293 /**
294 * Compute a*p + b*q in constant time
295 *
296 * Faster than composing mul() and add(), and safe for secret
297 * scalars, as arise for example in Pedersen commitments.
298 */
299 static G1Projective mul2(const G1Projective& p, const Scalar& a, const G1Projective& q, const Scalar& b);
300
301 /**
302 * Compute a*p + b*q
303 *
304 * Warning: this function runs in variable time and must be used
305 * only with public inputs, such as signature verification. Use
306 * mul2() with secret scalars.
307 */
308 static G1Projective mul2_vartime(const G1Projective& p, const Scalar& a, const G1Projective& q, const Scalar& b);
309
310 /**
311 * Check if this point is the identity element
312 */
313 bool is_identity() const;
314
315 /**
316 * Hash to curve (RFC 9380), suite BLS12381G1_XMD:SHA-256_SSWU_RO_
317 *
318 * Throws Invalid_Argument if dst is empty.
319 */
320 static G1Projective hash_to_curve_ro(std::span<const uint8_t> input, std::span<const uint8_t> dst);
321
322 /**
323 * Nonuniform encoding to curve (RFC 9380 encode_to_curve),
324 * suite BLS12381G1_XMD:SHA-256_SSWU_NU_
325 *
326 * Throws Invalid_Argument if dst is empty.
327 */
328 static G1Projective hash_to_curve_nu(std::span<const uint8_t> input, std::span<const uint8_t> dst);
329
330 /**
331 * Multiscalar multiplication, the sum of scalars[i]*points[i]
332 *
333 * The empty sum is the identity element. Throws Invalid_Argument
334 * if the spans are of unequal length.
335 *
336 * Warning: this function runs in variable time and must be used
337 * only with public inputs, such as signature verification. Use
338 * mul() with secret scalars.
339 */
340 static G1Projective msm_vartime(std::span<const G1Affine> points, std::span<const Scalar> scalars);
341
342 /**
343 * Convert a batch of points to affine
344 *
345 * Equivalent to calling to_affine on each point, but much faster,
346 * since a single field inversion is shared across the batch.
347 */
348 static std::vector<G1Affine> to_affine_batch(std::span<const G1Projective> points);
349
350 /**
351 * The input is assumed to be a point on the curve, though possibly
352 * outside the prime order subgroup.
353 *
354 * Reserved for internal use, not covered by SemVer.
355 */
356 static G1Projective _unchecked_from_affine_coords(const FieldElement& x, const FieldElement& y);
357
358 private:
359 G1Projective(const FieldElement& x, const FieldElement& y, const FieldElement& z);
360
361 G1Projective dbl() const;
362 G1Projective add_mixed(const G1Affine& other, bool negate_other) const;
363
364 void conditional_negate(uint32_t negate);
365
366 friend class G1Affine;
367
368 template <typename Pt>
369 friend class PointMul;
370
371 template <typename Group>
372 friend class GroupOps;
373
374 static constexpr size_t FE_WORDS = 48 / sizeof(word);
375
376 std::array<word, FE_WORDS> m_x;
377 std::array<word, FE_WORDS> m_y;
378 std::array<word, FE_WORDS> m_z;
379};
380
381/**
382* An element of the group G2, in affine form
383*
384* Group arithmetic is performed on G2Projective; the affine form is
385* used for serialization, pairings, and mixed addition
386*/
387class BOTAN_PUBLIC_API(3, 14) G2Affine final {
388 public:
389 /** The byte length of the compressed point encoding */
390 static constexpr size_t BYTES = 96;
391
392 /**
393 * Return the G2 identity element
394 */
395 static G2Affine identity();
396
397 /**
398 * Return the G2 standard group generator
399 */
400 static G2Affine generator();
401
402 /**
403 * Point deserialization
404 *
405 * Only compressed point encoding is supported.
406 *
407 * This rejects points not in the prime order subgroup. The canonical
408 * encoding of the identity element is accepted; callers for which the
409 * identity is not a legal value (such as BLS signatures) must check
410 * is_identity() themselves.
411 */
412 static std::optional<G2Affine> deserialize(std::span<const uint8_t> bytes);
413
414 /**
415 * Point serialization
416 *
417 * Only compressed point encoding is supported.
418 */
419 std::array<uint8_t, G2Affine::BYTES> serialize() const;
420
421 /**
422 * Check if this point is the identity element
423 */
424 bool is_identity() const;
425
426 /**
427 * Access the coordinates directly; the values are meaningless if
428 * the point is the identity element.
429 *
430 * Reserved for internal use, not covered by SemVer.
431 */
432 FieldElement2 _x() const;
433 FieldElement2 _y() const;
434
435 private:
436 friend class G2Projective;
437
438 template <typename Group>
439 friend class GroupOps;
440
441 G2Affine(const FieldElement2& x, const FieldElement2& y, uint32_t infinity);
442
443 static constexpr size_t FE2_WORDS = 96 / sizeof(word);
444
445 std::array<word, FE2_WORDS> m_x;
446 std::array<word, FE2_WORDS> m_y;
447 uint32_t m_infinity;
448};
449
450/**
451* An element of the group G2, in projective form
452*/
453class BOTAN_PUBLIC_API(3, 14) G2Projective final {
454 public:
455 /**
456 * Default constructed as the identity element
457 */
458 G2Projective();
459
460 /** Convert an affine point to projective form */
461 static G2Projective from_affine(const G2Affine& affine);
462
463 /** Return the G2 identity element */
464 static G2Projective identity() { return G2Projective(); }
465
466 /** Return the G2 standard group generator */
467 static G2Projective generator();
468
469 /** Convert to affine form, at the cost of a field inversion */
470 G2Affine to_affine() const;
471
472 /** Return the negation of this point */
473 G2Projective negate() const;
474
475 /** Return the sum of this point and other */
476 G2Projective add(const G2Projective& other) const;
477
478 /** Return the sum of this point and an affine point */
479 G2Projective add_mixed(const G2Affine& other) const;
480
481 /**
482 * Scalar multiplication
483 *
484 * Constant time; safe for secret scalars
485 */
486 G2Projective mul(const Scalar& scalar) const;
487
488 /**
489 * Compute a*p + b*q in constant time
490 *
491 * Faster than composing mul() and add(), and safe for secret
492 * scalars, as arise for example in Pedersen commitments.
493 */
494 static G2Projective mul2(const G2Projective& p, const Scalar& a, const G2Projective& q, const Scalar& b);
495
496 /**
497 * Compute a*p + b*q
498 *
499 * Warning: this function runs in variable time and must be used
500 * only with public inputs, such as signature verification. Use
501 * mul2() with secret scalars.
502 */
503 static G2Projective mul2_vartime(const G2Projective& p, const Scalar& a, const G2Projective& q, const Scalar& b);
504
505 /**
506 * Check if this point is the identity element
507 */
508 bool is_identity() const;
509
510 /**
511 * Hash to curve (RFC 9380), suite BLS12381G2_XMD:SHA-256_SSWU_RO_
512 *
513 * Throws Invalid_Argument if dst is empty.
514 */
515 static G2Projective hash_to_curve_ro(std::span<const uint8_t> input, std::span<const uint8_t> dst);
516
517 /**
518 * Nonuniform encoding to curve (RFC 9380 encode_to_curve),
519 * suite BLS12381G2_XMD:SHA-256_SSWU_NU_
520 *
521 * Throws Invalid_Argument if dst is empty.
522 */
523 static G2Projective hash_to_curve_nu(std::span<const uint8_t> input, std::span<const uint8_t> dst);
524
525 /**
526 * Multiscalar multiplication, the sum of scalars[i]*points[i]
527 *
528 * The empty sum is the identity element. Throws Invalid_Argument
529 * if the spans are of unequal length.
530 *
531 * Warning: this function runs in variable time and must be used
532 * only with public inputs, such as signature verification. Use
533 * mul() with secret scalars.
534 */
535 static G2Projective msm_vartime(std::span<const G2Affine> points, std::span<const Scalar> scalars);
536
537 /**
538 * Convert a batch of points to affine
539 *
540 * Equivalent to calling to_affine on each point, but much faster,
541 * since a single field inversion is shared across the batch.
542 */
543 static std::vector<G2Affine> to_affine_batch(std::span<const G2Projective> points);
544
545 /**
546 * The input is assumed to be a point on the curve, though possibly
547 * outside the prime order subgroup.
548 *
549 * Reserved for internal use, not covered by SemVer.
550 */
551 static G2Projective _unchecked_from_affine_coords(const FieldElement2& x, const FieldElement2& y);
552
553 private:
554 G2Projective(const FieldElement2& x, const FieldElement2& y, const FieldElement2& z);
555
556 G2Projective dbl() const;
557 G2Projective add_mixed(const G2Affine& other, bool negate_other) const;
558
559 void conditional_negate(uint32_t negate);
560
561 /**
562 * The untwist-Frobenius-twist endomorphism, and its square
563 */
564 G2Projective psi() const;
565 G2Projective psi2() const;
566
567 /**
568 * Cofactor clearing for hash to curve
569 */
570 G2Projective clear_cofactor() const;
571
572 friend class G2Affine;
573
574 template <typename Pt>
575 friend class PointMul;
576
577 template <typename Group>
578 friend class GroupOps;
579
580 static constexpr size_t FE2_WORDS = 96 / sizeof(word);
581
582 std::array<word, FE2_WORDS> m_x;
583 std::array<word, FE2_WORDS> m_y;
584 std::array<word, FE2_WORDS> m_z;
585};
586
587/**
588* An element of the pairing target group, a subgroup of Fp12*
589*
590* Elements are members of the prime order subgroup by construction;
591* there is no deserialization.
592*/
593class BOTAN_PUBLIC_API(3, 14) Gt final {
594 public:
595 /** The byte length of the Gt serialization */
596 static constexpr size_t BYTES = 576;
597
598 /**
599 * Compute the optimal ate pairing e(p, q)
600 */
601 static Gt pairing(const G1Affine& p, const G2Affine& q);
602
603 /**
604 * Compute the product of pairings prod_i e(p[i], q[i])
605 *
606 * More efficient than computing each pairing individually, since the
607 * final exponentiation is shared. The empty product yields the identity.
608 *
609 * Throws Invalid_Argument if the spans are of unequal length.
610 */
611 static Gt multi_pairing(std::span<const G1Affine> p, std::span<const G2Affine> q);
612
613 /**
614 * Return the Gt identity element
615 */
616 static Gt identity();
617
618 /**
619 * Check if this element is the identity
620 */
621 bool is_identity() const;
622
623 /**
624 * Constant time equality
625 */
626 bool operator==(const Gt& other) const;
627
628 /**
629 * Serialization of the underlying Fp12 element; the coefficients
630 * are encoded in the order c0.c0.c0, c0.c0.c1, ..., c1.c2.c1 with
631 * each Fp coefficient as 48 big-endian bytes
632 */
633 std::array<uint8_t, BYTES> serialize() const;
634
635 private:
636 explicit Gt(const Fp12& v);
637
638 Fp12 _to_fp12() const;
639
640 static constexpr size_t WORDS = 12 * (48 / sizeof(word));
641
642 std::array<word, WORDS> m_coeffs;
643};
644
645} // namespace Botan::BLS12_381
646
647#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
static G1Affine identity()
static std::optional< G1Affine > deserialize(std::span< const uint8_t > bytes)
FieldElement _y() const
FieldElement _x() const
std::array< uint8_t, G1Affine::BYTES > serialize() const
static G1Affine generator()
static constexpr size_t BYTES
Definition bls12_381.h:195
static G1Projective identity()
Definition bls12_381.h:269
static G1Projective from_affine(const G1Affine &affine)
static G2Affine generator()
static constexpr size_t BYTES
Definition bls12_381.h:390
FieldElement2 _x() const
std::array< uint8_t, G2Affine::BYTES > serialize() const
static std::optional< G2Affine > deserialize(std::span< const uint8_t > bytes)
FieldElement2 _y() const
static G2Projective identity()
Definition bls12_381.h:464
static G2Projective from_affine(const G2Affine &affine)
std::array< uint8_t, BYTES > serialize() const
static Gt pairing(const G1Affine &p, const G2Affine &q)
static Gt multi_pairing(std::span< const G1Affine > p, std::span< const G2Affine > q)
bool operator==(const Gt &other) const
static constexpr size_t BYTES
Definition bls12_381.h:596
Scalar(const Scalar &other)=default
static constexpr size_t BITS
Definition bls12_381.h:32
static constexpr size_t N
Definition bls12_381.h:38
Scalar & operator-=(const Scalar &x)
Definition bls12_381.h:134
Scalar & operator+=(const Scalar &x)
Definition bls12_381.h:128
Scalar mul(const Scalar &x) const
void serialize_to(std::span< uint8_t, Scalar::BYTES > bytes) const
static Scalar zero()
Definition bls12_381.h:72
Scalar(Scalar &&other) noexcept
Definition bls12_381.h:55
static constexpr size_t BYTES
Definition bls12_381.h:35
Scalar & operator*=(const Scalar &x)
Definition bls12_381.h:140
Scalar & operator=(Scalar &&other) noexcept
Definition bls12_381.h:58
std::array< uint8_t, Scalar::BYTES > serialize() const
Definition bls12_381.h:112
Scalar sub(const Scalar &x) const
Scalar & operator=(const Scalar &other)=default
Scalar add(const Scalar &x) const
Scalar operator-(const Scalar &a, const Scalar &b)
Definition bls12_381.h:177
Scalar operator+(const Scalar &a, const Scalar &b)
Definition bls12_381.h:172
Scalar operator*(const Scalar &a, const Scalar &b)
Definition bls12_381.h:182
BigInt square(const BigInt &x)
Definition numthry.cpp:184
auto to_affine_batch(std::span< const typename C::ProjectivePoint > projective)
constexpr auto to_affine(const typename C::ProjectivePoint &pt)
std::conditional_t< HasNative64BitRegisters, std::uint64_t, uint32_t > word
The native machine word, used as the limb type for multiprecision integers.
Definition types.h:131