Botan 3.14.1
Crypto and TLS for C&
Botan::BLS12_381::Scalar Class Referencefinal

#include <bls12_381.h>

Public Member Functions

Scalar add (const Scalar &x) const
Scalar invert () const
Scalar mul (const Scalar &x) const
Scalar negate () const
Scalar & operator*= (const Scalar &x)
Scalar & operator+= (const Scalar &x)
Scalar & operator-= (const Scalar &x)
Scalar & operator= (const Scalar &other)=default
Scalar & operator= (Scalar &&other) noexcept
constexpr Scalar ()
 Scalar (const Scalar &other)=default
 Scalar (Scalar &&other) noexcept
std::array< uint8_t, Scalar::BYTES > serialize () const
void serialize_to (std::span< uint8_t, Scalar::BYTES > bytes) const
Scalar square () const
Scalar sub (const Scalar &x) const
 ~Scalar ()

Static Public Member Functions

static std::optional< Scalar > deserialize (std::span< const uint8_t > bytes)
static Scalar from_bytes_wide (std::span< const uint8_t, 64 > bytes)
static Scalar from_u32 (uint32_t v)
static Scalar hash (std::span< const uint8_t > input, std::span< const uint8_t > dst)
static Scalar one ()
static Scalar zero ()

Static Public Attributes

static constexpr size_t BITS = 255
static constexpr size_t BYTES = (BITS + 7) / 8
static constexpr size_t N = (BYTES + sizeof(word) - 1) / sizeof(word)

Detailed Description

A BLS12-381 scalar

Integer modulo 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001

Definition at line 29 of file bls12_381.h.

Constructor & Destructor Documentation

◆ Scalar() [1/3]

Botan::BLS12_381::Scalar::Scalar ( )
inlineconstexpr

Default constructed as zero

Definition at line 43 of file bls12_381.h.

43: m_val({}) {}

Referenced by add(), from_bytes_wide(), from_u32(), hash(), invert(), mul(), negate(), one(), operator*=(), operator+=(), operator-=(), operator=(), operator=(), Scalar(), Scalar(), square(), sub(), and zero().

◆ Scalar() [2/3]

Botan::BLS12_381::Scalar::Scalar ( const Scalar & other)
default

Copy constructor

References Scalar().

◆ Scalar() [3/3]

Botan::BLS12_381::Scalar::Scalar ( Scalar && other)
inlinenoexcept

Scalars are commonly secrets, so they are zeroized on destruction, and moving from a Scalar zeroizes the source

Definition at line 55 of file bls12_381.h.

55: m_val(other.m_val) { other.wipe(); }

References Scalar().

◆ ~Scalar()

Botan::BLS12_381::Scalar::~Scalar ( )
inline

Definition at line 66 of file bls12_381.h.

66{ this->wipe(); }

Member Function Documentation

◆ add()

Scalar Botan::BLS12_381::Scalar::add ( const Scalar & x) const

Addition modulo r

Definition at line 112 of file bls12_381_scalar.cpp.

112 {
113 std::array<word, Scalar::N> t{};
114 word carry = 0;
115 for(size_t i = 0; i != Scalar::N; ++i) {
116 t[i] = word_add(m_val[i], other.m_val[i], &carry);
117 }
118
119 std::array<word, Scalar::N> r{};
120 bigint_monty_maybe_sub<Scalar::N>(r.data(), carry, t.data(), SCALAR_P.data());
121 return Scalar(r);
122}
static constexpr size_t N
Definition bls12_381.h:38
constexpr auto word_add(W x, W y, W *carry) -> W
Definition mp_asmi.h:260
constexpr void bigint_monty_maybe_sub(size_t N, W z[], W x0, const W x[], const W p[])
Definition mp_core.h:229
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

References Botan::bigint_monty_maybe_sub(), N, Scalar(), and Botan::word_add().

Referenced by Botan::BLS12_381::operator+(), and operator+=().

◆ deserialize()

std::optional< Scalar > Botan::BLS12_381::Scalar::deserialize ( std::span< const uint8_t > bytes)
static

Deserialize a scalar from a 32-byte long big-endian encoding

Returns nullopt unless the encoding is a canonical integer in the range [1, r). In particular the zero scalar is rejected, since a zero scalar is almost always a mistake; this matches EC_Scalar::deserialize.

Note
that some implementations of BLS12-381 use little-endian scalar encodings

Definition at line 80 of file bls12_381_scalar.cpp.

80 {
81 if(bytes.size() != Scalar::BYTES) {
82 return {};
83 }
84
85 const auto words = bytes_to_words<word, N, BYTES>(bytes.first<Scalar::BYTES>());
86
87 if(!bigint_ct_is_lt(words.data(), N, SCALAR_P.data(), N).as_bool()) {
88 return {};
89 }
90
91 // Reject the zero scalar; a zero secret key, challenge, or nonce is
92 // essentially always a mistake. This matches EC_Scalar::deserialize.
93 if(CT::all_zeros(words.data(), N).as_bool()) {
94 return {};
95 }
96
97 return Scalar::from_words(words);
98}
static constexpr size_t BYTES
Definition bls12_381.h:35
constexpr CT::Mask< T > all_zeros(const T elem[], size_t len)
Definition ct_utils.h:790
constexpr auto bytes_to_words(std::span< const uint8_t, L > bytes)
Definition mp_core.h:1255
constexpr auto bigint_ct_is_lt(const W x[], size_t x_size, const W y[], size_t y_size, bool lt_or_equal=false) -> CT::Mask< W >
Definition mp_core.h:510

References Botan::CT::all_zeros(), Botan::bigint_ct_is_lt(), BYTES, Botan::bytes_to_words(), and N.

◆ from_bytes_wide()

Scalar Botan::BLS12_381::Scalar::from_bytes_wide ( std::span< const uint8_t, 64 > bytes)
static

Reduce a 64 byte big-endian integer modulo r

Suitable for deriving a uniformly distributed scalar from an RNG or hash output

Definition at line 100 of file bls12_381_scalar.cpp.

100 {
101 return Scalar(scalar_wide_to_rep(bytes_to_words<word, 2 * N, 2 * BYTES>(bytes)));
102}

References Botan::bytes_to_words(), and Scalar().

Referenced by hash().

◆ from_u32()

Scalar Botan::BLS12_381::Scalar::from_u32 ( uint32_t v)
static

Return the scalar equal to the small integer v

Definition at line 69 of file bls12_381_scalar.cpp.

69 {
70 std::array<word, Scalar::N> w{};
71 w[0] = v;
72 return Scalar::from_words(w);
73}

References Scalar().

◆ hash()

Scalar Botan::BLS12_381::Scalar::hash ( std::span< const uint8_t > input,
std::span< const uint8_t > dst )
static

Hash an input to a scalar

Uses the hash_to_field construction of RFC 9380, namely expand_message_xmd with SHA-256 followed by wide reduction. The distribution of the result is uniform (negligibly biased). The domain separation tag dst distinguishes different uses of the hash; see RFC 9380 section 3.1 for the requirements.

Throws Invalid_Argument if dst is empty.

Definition at line 484 of file bls12_381_h2c.cpp.

484 {
485 // Applying the L formula of RFC 9380 5.1 to GF(r) with k = 128 gives L = 48
486 auto uniform = bls_expand_message<48>(input, dst);
487 CT::poison(uniform);
488
489 std::array<uint8_t, 64> padded{};
490 copy_mem(padded.data() + padded.size() - uniform.size(), uniform.data(), uniform.size());
491 const auto s = Scalar::from_bytes_wide(padded);
492
493 // The result may be a secret (eg a key derived from a seed)
494 secure_scrub_memory(uniform);
495 secure_scrub_memory(padded);
496 CT::unpoison_all(uniform, padded, s.m_val);
497
498 return s;
499}
static Scalar from_bytes_wide(std::span< const uint8_t, 64 > bytes)
constexpr void unpoison_all(const Ts &... ts)
Definition ct_utils.h:207
constexpr void poison(const T *p, size_t n)
Definition ct_utils.h:56
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144
void secure_scrub_memory(void *ptr, size_t n)
Definition mem_utils.cpp:24

References Botan::copy_mem(), from_bytes_wide(), Botan::CT::poison(), Scalar(), Botan::secure_scrub_memory(), and Botan::CT::unpoison_all().

◆ invert()

Scalar Botan::BLS12_381::Scalar::invert ( ) const

Return the multiplicative inverse of this scalar, or zero for zero

Definition at line 169 of file bls12_381_scalar.cpp.

169 {
170 // Addition chain for exponentiation to p - 2
171 // Found using https://github.com/mmcloughlin/addchain
172 auto t3 = this->square();
173 auto z = t3 * (*this);
174 auto t14 = (*this) * z;
175 auto t2 = t14 * t3;
176 auto t4 = t2.square();
177 auto t8 = t2 * t4;
178 auto t5 = t8 * (*this);
179 auto t11 = t5 * z;
180 auto t0 = t11 * t3;
181 auto t9 = t0 * t3;
182 auto t1 = t11 * t4;
183 auto t10 = t1 * t5;
184 auto t6 = t10 * t2;
185 t2 = t10 * t11;
186 auto t7 = t2 * t3;
187 t5 = t6 * t9;
188 t8 *= t5;
189 t3 *= t8;
190 t9 *= t3;
191 auto t12 = t11 * t9;
192 auto t13 = t12 * t14;
193 t1 *= t13;
194 t11 = t0 * t1;
195 t14 *= t11;
196 auto t15 = t14 * t4;
197 t4 = t0 * t11;
198 t0 *= t15;
199 t15.square_n(8);
200 t14 *= t15;
201 t14.square_n(9);
202 t13 *= t14;
203 t13.square_n(9);
204 t13 *= t12;
205 t13.square_n(9);
206 t12 *= t13;
207 t12.square_n(8);
208 t11 *= t12;
209 t11.square_n(6);
210 t10 *= t11;
211 t10.square_n(10);
212 t9 *= t10;
213 t9.square_n(9);
214 t8 *= t9;
215 t8.square_n(8);
216 t8 *= t6;
217 t8.square_n(8);
218 t8 *= (*this);
219 t8.square_n(14);
220 t7 *= t8;
221 t7.square_n(10);
222 t6 *= t7;
223 t6.square_n(15);
224 t5 *= t6;
225 t5.square_n(10);
226 t4 *= t5;
227 t4.square_n(8);
228 t3 *= t4;
229 t3.square_n(16);
230 t3 *= t1;
231 t3.square_n(8);
232 t3 *= t0;
233 t3.square_n(7);
234 t2 *= t3;
235 t2.square_n(9);
236 t2 *= t0;
237 t2.square_n(8);
238 t2 *= t1;
239 t2.square_n(8);
240 t2 *= t0;
241 t2.square_n(8);
242 t2 *= t0;
243 t2.square_n(8);
244 t2 *= t0;
245 t2.square_n(8);
246 t1 *= t2;
247 t1.square_n(8);
248 t1 *= t0;
249 t1.square_n(8);
250 t1 *= t0;
251 t1.square_n(8);
252 t0 *= t1;
253 t0.square_n(2);
254 z *= t0;
255 return z;
256}

References Scalar(), and square().

◆ mul()

Scalar Botan::BLS12_381::Scalar::mul ( const Scalar & x) const

Multiplication modulo r

Definition at line 140 of file bls12_381_scalar.cpp.

140 {
141 std::array<word, 2 * Scalar::N> z{};
142 comba_mul<Scalar::N>(z.data(), data(), other.data());
143 return Scalar(scalar_redc(z));
144}
constexpr void comba_mul(W z[2 *N], const W x[N], const W y[N])
Definition mp_core.h:981

References Botan::comba_mul(), and Scalar().

Referenced by Botan::BLS12_381::operator*(), and operator*=().

◆ negate()

Scalar Botan::BLS12_381::Scalar::negate ( ) const

Return the negation of this scalar

Definition at line 160 of file bls12_381_scalar.cpp.

160 {
161 auto v_is_zero = CT::all_zeros(this->data(), N);
162
163 std::array<word, N> r{};
164 bigint_sub3(r.data(), SCALAR_P.data(), N, this->data(), N);
165 v_is_zero.if_set_zero_out(r.data(), N);
166 return Scalar(r);
167}
constexpr auto bigint_sub3(W z[], const W x[], size_t x_size, const W y[], size_t y_size) -> W
Definition mp_core.h:196

References Botan::CT::all_zeros(), Botan::bigint_sub3(), N, and Scalar().

◆ one()

Scalar Botan::BLS12_381::Scalar::one ( )
static

Return the scalar one

Definition at line 76 of file bls12_381_scalar.cpp.

76 {
77 return Scalar(SCALAR_R1);
78}

References Scalar().

◆ operator*=()

Scalar & Botan::BLS12_381::Scalar::operator*= ( const Scalar & x)
inline

Multiplication modulo r

Definition at line 140 of file bls12_381.h.

140 {
141 (*this) = this->mul(x);
142 return (*this);
143 }
Scalar mul(const Scalar &x) const

References mul(), and Scalar().

◆ operator+=()

Scalar & Botan::BLS12_381::Scalar::operator+= ( const Scalar & x)
inline

Addition modulo r

Definition at line 128 of file bls12_381.h.

128 {
129 (*this) = this->add(x);
130 return (*this);
131 }
Scalar add(const Scalar &x) const

References add(), and Scalar().

◆ operator-=()

Scalar & Botan::BLS12_381::Scalar::operator-= ( const Scalar & x)
inline

Subtraction modulo r

Definition at line 134 of file bls12_381.h.

134 {
135 (*this) = this->sub(x);
136 return (*this);
137 }
Scalar sub(const Scalar &x) const

References Scalar(), and sub().

◆ operator=() [1/2]

Scalar & Botan::BLS12_381::Scalar::operator= ( const Scalar & other)
default

Copy assignment

References Scalar().

◆ operator=() [2/2]

Scalar & Botan::BLS12_381::Scalar::operator= ( Scalar && other)
inlinenoexcept

Move assignment; the moved-from scalar is zeroized

Definition at line 58 of file bls12_381.h.

58 {
59 if(this != &other) {
60 m_val = other.m_val;
61 other.wipe();
62 }
63 return *this;
64 }

References Scalar().

◆ serialize()

std::array< uint8_t, Scalar::BYTES > Botan::BLS12_381::Scalar::serialize ( ) const
inline

Return the 32 byte big-endian encoding

Definition at line 112 of file bls12_381.h.

112 {
113 std::array<uint8_t, Scalar::BYTES> buf{};
114 this->serialize_to(buf);
115 return buf;
116 }
void serialize_to(std::span< uint8_t, Scalar::BYTES > bytes) const

References serialize_to().

Referenced by Botan::BLS12_381::PointMul< Pt >::mul(), Botan::BLS12_381::PointMul< Pt >::mul2(), Botan::BLS12_381::PointMul< Pt >::mul2_vartime(), and Botan::BLS12_381::PointMul< Pt >::mul_vartime().

◆ serialize_to()

void Botan::BLS12_381::Scalar::serialize_to ( std::span< uint8_t, Scalar::BYTES > bytes) const

Serialize to a 32 byte big-endian encoding

Definition at line 104 of file bls12_381_scalar.cpp.

104 {
105 auto v = scalar_from_rep(m_val);
106 std::reverse(v.begin(), v.end());
107 store_be(bytes, v);
108 // The scalar may be a secret; don't leave an extra copy on the stack
110}
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::secure_scrub_memory(), and Botan::store_be().

Referenced by serialize().

◆ square()

Scalar Botan::BLS12_381::Scalar::square ( ) const

Return the square of this scalar

Definition at line 146 of file bls12_381_scalar.cpp.

146 {
147 std::array<word, 2 * Scalar::N> z{};
148 comba_sqr<Scalar::N>(z.data(), data());
149 return Scalar(scalar_redc(z));
150}
constexpr void comba_sqr(W z[2 *N], const W x[N])
Definition mp_core.h:1017

References Botan::comba_sqr(), and Scalar().

Referenced by invert().

◆ sub()

Scalar Botan::BLS12_381::Scalar::sub ( const Scalar & x) const

Subtraction modulo r

Definition at line 124 of file bls12_381_scalar.cpp.

124 {
125 std::array<word, Scalar::N> r; // NOLINT(*-member-init)
126 word borrow = 0;
127 for(size_t i = 0; i != Scalar::N; ++i) {
128 r[i] = word_sub(m_val[i], other.m_val[i], &borrow);
129 }
130
131 const word mask = CT::Mask<word>::expand(borrow).value();
132 word carry = 0;
133 for(size_t i = 0; i != Scalar::N; ++i) {
134 r[i] = word_add(r[i], SCALAR_P[i] & mask, &carry);
135 }
136
137 return Scalar(r);
138}
static constexpr Mask< T > expand(T v)
Definition ct_utils.h:397
constexpr auto word_sub(W x, W y, W *carry) -> W
Definition mp_asmi.h:355

References Botan::CT::Mask< T >::expand(), N, Scalar(), Botan::word_add(), and Botan::word_sub().

Referenced by Botan::BLS12_381::operator-(), and operator-=().

◆ zero()

Scalar Botan::BLS12_381::Scalar::zero ( )
inlinestatic

Return the zero scalar

Definition at line 72 of file bls12_381.h.

72{ return Scalar(); }

References Scalar().

Member Data Documentation

◆ BITS

◆ BYTES

size_t Botan::BLS12_381::Scalar::BYTES = (BITS + 7) / 8
staticconstexpr

The byte length of the canonical scalar encoding

Definition at line 35 of file bls12_381.h.

Referenced by deserialize(), Botan::BLS12_381::PointMul< Pt >::msm_vartime(), and Botan::BLS12_381::scalar_window_at().

◆ N

size_t Botan::BLS12_381::Scalar::N = (BYTES + sizeof(word) - 1) / sizeof(word)
staticconstexpr

The word length of the internal representation

Definition at line 38 of file bls12_381.h.

Referenced by add(), deserialize(), negate(), and sub().


The documentation for this class was generated from the following files: