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

#include <bls12_381_fields.h>

Public Member Functions

CT::Choice _is_lexicographically_largest () const
constexpr const std::array< word, N > & _words () const
FieldElement add (const FieldElement &x) const
void conditional_assign (CT::Choice cnd, const FieldElement &other)
constexpr FieldElement ()
FieldElement invert () const
CT::Choice is_zero () const
FieldElement mul (const FieldElement &x) const
FieldElement negate () const
CT::Choice operator!= (const FieldElement &other) const
FieldElement & operator*= (const FieldElement &x)
FieldElement & operator+= (const FieldElement &x)
FieldElement & operator-= (const FieldElement &x)
CT::Choice operator== (const FieldElement &other) const
std::array< uint8_t, FieldElement::BYTES > serialize () const
void serialize_to (std::span< uint8_t, FieldElement::BYTES > bytes) const
CT::Option< FieldElement > sqrt () const
FieldElement square () const
FieldElement sub (const FieldElement &x) const

Static Public Member Functions

static constexpr FieldElement _unchecked_from_words (std::array< word, FieldElement::N > v)
static std::optional< FieldElement > deserialize (std::span< const uint8_t > bytes)
static FieldElement from_bytes_wide (std::span< const uint8_t, 96 > bytes)
static FieldElement from_u32 (uint32_t v)
static FieldElement one ()
static FieldElement zero ()

Static Public Attributes

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

Detailed Description

A BLS12-381 field element

Integer modulo 0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab

Definition at line 24 of file bls12_381_fields.h.

Constructor & Destructor Documentation

◆ FieldElement()

Botan::BLS12_381::FieldElement::FieldElement ( )
inlineconstexpr

Member Function Documentation

◆ _is_lexicographically_largest()

CT::Choice Botan::BLS12_381::FieldElement::_is_lexicographically_largest ( ) const

Set iff this is larger than its negation

Ie set if this is > (p-1)/2

Definition at line 186 of file bls12_381_fe.cpp.

186 {
187 const auto v = fe_from_rep(m_val);
188 return !bigint_ct_is_lt(v.data(), N, FE_P_HALF.data(), N, true).as_choice();
189}
static constexpr size_t N
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::bigint_ct_is_lt(), and N.

◆ _unchecked_from_words()

constexpr FieldElement Botan::BLS12_381::FieldElement::_unchecked_from_words ( std::array< word, FieldElement::N > v)
inlinestaticconstexpr

The input is assumed to be valid and already in Montgomery representation

Definition at line 110 of file bls12_381_fields.h.

110 {
111 return FieldElement(v);
112 }

References FieldElement().

Referenced by Botan::BLS12_381::FieldElement2::_unchecked_from_words().

◆ _words()

const std::array< word, N > & Botan::BLS12_381::FieldElement::_words ( ) const
inlineconstexpr

The Montgomery representation words

Definition at line 117 of file bls12_381_fields.h.

117{ return m_val; }

◆ add()

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

Definition at line 125 of file bls12_381_fe.cpp.

125 {
126 std::array<word, FieldElement::N> t{};
127 word carry = 0;
128 for(size_t i = 0; i != FieldElement::N; ++i) {
129 t[i] = word_add(m_val[i], other.m_val[i], &carry);
130 }
131
132 std::array<word, FieldElement::N> r{};
133 bigint_monty_maybe_sub<FieldElement::N>(r.data(), carry, t.data(), FE_P.data());
134 return FieldElement(r);
135}
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(), FieldElement(), N, and Botan::word_add().

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

◆ conditional_assign()

void Botan::BLS12_381::FieldElement::conditional_assign ( CT::Choice cnd,
const FieldElement & other )

If cnd is set assign other to this, in constant time

Definition at line 196 of file bls12_381_fe.cpp.

196 {
197 CT::conditional_assign_mem(cnd, m_val.data(), other.m_val.data(), N);
198}
constexpr Mask< T > conditional_assign_mem(T cnd, T *dest, const T *src, size_t elems)
Definition ct_utils.h:754

References Botan::CT::conditional_assign_mem(), FieldElement(), and N.

◆ deserialize()

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

Definition at line 101 of file bls12_381_fe.cpp.

101 {
102 if(bytes.size() != FieldElement::BYTES) {
103 return {};
104 }
105
106 const auto words = bytes_to_words<word, N, BYTES>(bytes.first<FieldElement::BYTES>());
107
108 if(!bigint_ct_is_lt(words.data(), N, FE_P.data(), N).as_bool()) {
109 return {};
110 }
111
112 return FieldElement::from_words(words);
113}
static constexpr size_t BYTES
constexpr auto bytes_to_words(std::span< const uint8_t, L > bytes)
Definition mp_core.h:1255

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

Referenced by Botan::BLS12_381::FieldElement2::deserialize().

◆ from_bytes_wide()

FieldElement Botan::BLS12_381::FieldElement::from_bytes_wide ( std::span< const uint8_t, 96 > bytes)
static

Definition at line 115 of file bls12_381_fe.cpp.

115 {
116 return FieldElement(fe_wide_to_rep(bytes_to_words<word, 2 * N, 2 * BYTES>(bytes)));
117}

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

◆ from_u32()

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

Definition at line 90 of file bls12_381_fe.cpp.

90 {
91 std::array<word, FieldElement::N> w{};
92 w[0] = v;
93 return FieldElement::from_words(w);
94}

References FieldElement().

◆ invert()

FieldElement Botan::BLS12_381::FieldElement::invert ( ) const

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

Definition at line 206 of file bls12_381_fe.cpp.

206 {
207 // Addition chain for exponentiation to p - 2
208 // Found using https://github.com/mmcloughlin/addchain
209 auto z = (*this).square();
210 auto t3 = z.square();
211 auto t10 = t3.square();
212 auto t6 = t10 * (*this);
213 auto t8 = t6 * z;
214 auto t5 = t8 * z;
215 auto t24 = t3 * t5;
216 auto t1 = t6 * t8;
217 auto t17 = t10 * t24;
218 auto t9 = t17 * (*this);
219 auto t12 = t9.square();
220 auto t4 = t12 * z;
221 auto t2 = t4 * (*this);
222 auto t22 = t12 * t17;
223 auto t14 = t22 * z;
224 auto t0 = t10 * t22;
225 auto t20 = t0 * t10;
226 auto t11 = t22 * t9;
227 auto t19 = t11 * z;
228 auto t16 = t20 * t9;
229 auto t7 = t16 * t3;
230 t12 *= t0;
231 t9 *= t7;
232 auto t15 = t9 * z;
233 z = t1 * t9;
234 auto t21 = t10 * z;
235 t4 *= t12;
236 t10 = t3 * t4;
237 t5 *= t10;
238 auto t18 = t1 * t10;
239 auto t13 = t24 * t5;
240 auto t23 = t13 * t3;
241 t3 = t1 * t18;
242 t5 = t1 * t13;
243 t1 *= t3;
244 auto t25 = t13 * t4;
245 t25.square_n(8);
246 t24 *= t25;
247 t24.square_n(11);
248 t24 *= t5;
249 t24.square_n(11);
250 t23 *= t24;
251 t23.square_n(8);
252 t23 *= t1;
253 t23.square_n(7);
254 t22 *= t23;
255 t22.square_n(9);
256 t22 *= t19;
257 t22.square_n(10);
258 t21 *= t22;
259 t21.square_n(7);
260 t20 *= t21;
261 t20.square_n(9);
262 t20 *= t7;
263 t20.square_n(6);
264 t20 *= t17;
265 t20.square_n(11);
266 t19 *= t20;
267 t19.square_n(9);
268 t19 *= t3;
269 t19.square_n(10);
270 t18 *= t19;
271 t18.square_n(6);
272 t17 *= t18;
273 t17.square_n(10);
274 t16 *= t17;
275 t16.square_n(9);
276 t15 *= t16;
277 t15.square_n(11);
278 t14 *= t15;
279 t14.square_n(10);
280 t13 *= t14;
281 t13.square_n(9);
282 t12 *= t13;
283 t12.square_n(9);
284 t12 *= t4;
285 t12.square_n(8);
286 t11 *= t12;
287 t11.square_n(10);
288 t10 *= t11;
289 t10.square_n(9);
290 t9 *= t10;
291 t9.square_n(12);
292 t9 *= t7;
293 t9.square_n(5);
294 t8 *= t9;
295 t8.square_n(11);
296 t7 *= t8;
297 t7.square_n(7);
298 t6 *= t7;
299 t6.square_n(13);
300 t5 *= t6;
301 t5.square_n(9);
302 t4 *= t5;
303 t4.square_n(8);
304 t4 *= t1;
305 t4.square_n(8);
306 t3 *= t4;
307 t3.square_n(11);
308 t3 *= z;
309 t3.square_n(8);
310 t3 *= t1;
311 t3.square_n(8);
312 t3 *= t1;
313 t3.square_n(6);
314 t2 *= t3;
315 t2.square_n(10);
316 t2 *= t1;
317 t2.square_n(9);
318 t2 *= t1;
319 t2.square_n(8);
320 t2 *= t1;
321 t2.square_n(8);
322 t2 *= t1;
323 t2.square_n(8);
324 t1 *= t2;
325 t1.square_n(7);
326 t0 *= t1;
327 t0.square_n(9);
328 z *= t0;
329 return z;
330}

References FieldElement(), and square().

◆ is_zero()

CT::Choice Botan::BLS12_381::FieldElement::is_zero ( ) const

Definition at line 182 of file bls12_381_fe.cpp.

182 {
183 return CT::all_zeros(this->data(), N).as_choice();
184}
constexpr CT::Mask< T > all_zeros(const T elem[], size_t len)
Definition ct_utils.h:790

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

◆ mul()

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

Definition at line 153 of file bls12_381_fe.cpp.

153 {
154 std::array<word, 2 * FieldElement::N> z{};
155 comba_mul<FieldElement::N>(z.data(), data(), other.data());
156 return FieldElement(fe_redc(z));
157}
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 FieldElement().

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

◆ negate()

FieldElement Botan::BLS12_381::FieldElement::negate ( ) const

Definition at line 173 of file bls12_381_fe.cpp.

173 {
174 auto v_is_zero = CT::all_zeros(this->data(), N);
175
176 std::array<word, N> r{};
177 bigint_sub3(r.data(), FE_P.data(), N, this->data(), N);
178 v_is_zero.if_set_zero_out(r.data(), N);
179 return FieldElement(r);
180}
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(), FieldElement(), and N.

◆ one()

◆ operator!=()

CT::Choice Botan::BLS12_381::FieldElement::operator!= ( const FieldElement & other) const
inline

Definition at line 98 of file bls12_381_fields.h.

98{ return !(*this == other); }

References FieldElement().

◆ operator*=()

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

Definition at line 71 of file bls12_381_fields.h.

71 {
72 (*this) = this->mul(x);
73 return (*this);
74 }
FieldElement mul(const FieldElement &x) const

References FieldElement(), and mul().

◆ operator+=()

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

Definition at line 61 of file bls12_381_fields.h.

61 {
62 (*this) = this->add(x);
63 return (*this);
64 }
FieldElement add(const FieldElement &x) const

References add(), and FieldElement().

◆ operator-=()

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

Definition at line 66 of file bls12_381_fields.h.

66 {
67 (*this) = this->sub(x);
68 return (*this);
69 }
FieldElement sub(const FieldElement &x) const

References FieldElement(), and sub().

◆ operator==()

CT::Choice Botan::BLS12_381::FieldElement::operator== ( const FieldElement & other) const

Constant time equality

Definition at line 191 of file bls12_381_fe.cpp.

191 {
192 // The Montgomery representation of a reduced element is unique
193 return CT::is_equal(this->data(), other.data(), N).as_choice();
194}
constexpr CT::Mask< T > is_equal(const T x[], const T y[], size_t len)
Definition ct_utils.h:803

References FieldElement(), Botan::CT::is_equal(), and N.

◆ serialize()

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

Definition at line 49 of file bls12_381_fields.h.

49 {
50 std::array<uint8_t, FieldElement::BYTES> buf{};
51 this->serialize_to(buf);
52 return buf;
53 }
void serialize_to(std::span< uint8_t, FieldElement::BYTES > bytes) const

References serialize_to().

◆ serialize_to()

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

Definition at line 119 of file bls12_381_fe.cpp.

119 {
120 auto v = fe_from_rep(m_val);
121 std::reverse(v.begin(), v.end());
122 store_be(bytes, v);
123}
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::store_be().

Referenced by serialize().

◆ sqrt()

CT::Option< FieldElement > Botan::BLS12_381::FieldElement::sqrt ( ) const

Return the square root of this element, if one exists

If x and -x are both square roots, which of the two is returned is unspecified.

Definition at line 200 of file bls12_381_fe.cpp.

200 {
201 // Since p == 3 (mod 4) any square root must be x^((p+1)/4)
202 const auto r = pow_msb(*this, FE_SQRT_EXP);
203 return CT::Option<FieldElement>(r, r.square() == (*this));
204}
FE pow_msb(const FE &x, const std::array< word, N > &exp)

References Botan::BLS12_381::pow_msb().

◆ square()

FieldElement Botan::BLS12_381::FieldElement::square ( ) const

Definition at line 159 of file bls12_381_fe.cpp.

159 {
160 std::array<word, 2 * FieldElement::N> z{};
161 comba_sqr<FieldElement::N>(z.data(), data());
162 return FieldElement(fe_redc(z));
163}
constexpr void comba_sqr(W z[2 *N], const W x[N])
Definition mp_core.h:1017

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

Referenced by invert().

◆ sub()

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

Definition at line 137 of file bls12_381_fe.cpp.

137 {
138 std::array<word, FieldElement::N> r; // NOLINT(*-member-init)
139 word borrow = 0;
140 for(size_t i = 0; i != FieldElement::N; ++i) {
141 r[i] = word_sub(m_val[i], other.m_val[i], &borrow);
142 }
143
144 const word mask = CT::Mask<word>::expand(borrow).value();
145 word carry = 0;
146 for(size_t i = 0; i != FieldElement::N; ++i) {
147 r[i] = word_add(r[i], FE_P[i] & mask, &carry);
148 }
149
150 return FieldElement(r);
151}
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(), FieldElement(), N, Botan::word_add(), and Botan::word_sub().

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

◆ zero()

FieldElement Botan::BLS12_381::FieldElement::zero ( )
inlinestatic

Definition at line 37 of file bls12_381_fields.h.

37{ return FieldElement(); }

References FieldElement().

Referenced by Botan::BLS12_381::G1Affine::identity(), and Botan::BLS12_381::FieldElement2::one().

Member Data Documentation

◆ BITS

size_t Botan::BLS12_381::FieldElement::BITS = 381
staticconstexpr

Definition at line 26 of file bls12_381_fields.h.

◆ BYTES

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

◆ N

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

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