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

#include <bls12_381_fields.h>

Public Member Functions

CT::Choice _is_lexicographically_largest () const
FieldElement2 add (const FieldElement2 &x) const
const FieldElement & c0 () const
const FieldElement & c1 () const
void conditional_assign (CT::Choice cnd, const FieldElement2 &other)
FieldElement2 conjugate () const
constexpr FieldElement2 ()=default
constexpr FieldElement2 (const FieldElement &c0, const FieldElement &c1)
FieldElement2 invert () const
CT::Choice is_zero () const
FieldElement2 mul (const FieldElement2 &x) const
FieldElement2 mul_by_nonresidue () const
FieldElement2 negate () const
CT::Choice operator!= (const FieldElement2 &other) const
FieldElement2 & operator*= (const FieldElement2 &x)
FieldElement2 & operator+= (const FieldElement2 &x)
FieldElement2 & operator-= (const FieldElement2 &x)
CT::Choice operator== (const FieldElement2 &other) const
std::array< uint8_t, FieldElement2::BYTES > serialize () const
void serialize_to (std::span< uint8_t, FieldElement2::BYTES > bytes) const
CT::Option< FieldElement2 > sqrt () const
FieldElement2 square () const
void square_n (size_t n)
FieldElement2 sub (const FieldElement2 &x) const

Static Public Member Functions

static constexpr FieldElement2 _unchecked_from_words (std::array< word, FieldElement::N > c0, std::array< word, FieldElement::N > c1)
static std::optional< FieldElement2 > deserialize (std::span< const uint8_t > bytes)
static FieldElement2 one ()
static FieldElement2 zero ()

Static Public Attributes

static constexpr size_t BYTES = 2 * FieldElement::BYTES

Detailed Description

An element of the extension field Fp2 = Fp[u]/(u^2 + 1)

Represented as c0 + c1*u

Definition at line 156 of file bls12_381_fields.h.

Constructor & Destructor Documentation

◆ FieldElement2() [1/2]

Botan::BLS12_381::FieldElement2::FieldElement2 ( )
constexprdefault

◆ FieldElement2() [2/2]

Botan::BLS12_381::FieldElement2::FieldElement2 ( const FieldElement & c0,
const FieldElement & c1 )
inlineconstexpr

Definition at line 163 of file bls12_381_fields.h.

163: m_c0(c0), m_c1(c1) {}
const FieldElement & c0() const
const FieldElement & c1() const

References c0(), and c1().

Member Function Documentation

◆ _is_lexicographically_largest()

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

Set iff this is larger than its negation

The comparison is lexicographic on (c1, c0), matching the ZCash convention: c1 > (p-1)/2, or c1 == 0 and c0 > (p-1)/2.

Definition at line 256 of file bls12_381_fp2.cpp.

256 {
257 return m_c1._is_lexicographically_largest() || (m_c1.is_zero() && m_c0._is_lexicographically_largest());
258}

◆ _unchecked_from_words()

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

The inputs are assumed to be valid and already in Montgomery representation

Definition at line 259 of file bls12_381_fields.h.

260 {
262 }
constexpr FieldElement2()=default
static constexpr FieldElement _unchecked_from_words(std::array< word, FieldElement::N > v)

References Botan::BLS12_381::FieldElement::_unchecked_from_words(), c0(), c1(), and FieldElement2().

Referenced by Botan::BLS12_381::Fp12::frobenius_map(), and Botan::BLS12_381::Fp6::frobenius_map().

◆ add()

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

Definition at line 186 of file bls12_381_fp2.cpp.

186 {
187 return FieldElement2(m_c0 + x.m_c0, m_c1 + x.m_c1);
188}

References FieldElement2().

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

◆ c0()

const FieldElement & Botan::BLS12_381::FieldElement2::c0 ( ) const
inline

Definition at line 183 of file bls12_381_fields.h.

183{ return m_c0; }

Referenced by _unchecked_from_words(), Botan::BLS12_381::Fp12::cyclotomic_square(), deserialize(), and FieldElement2().

◆ c1()

const FieldElement & Botan::BLS12_381::FieldElement2::c1 ( ) const
inline

Definition at line 185 of file bls12_381_fields.h.

185{ return m_c1; }

Referenced by _unchecked_from_words(), deserialize(), and FieldElement2().

◆ conditional_assign()

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

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

Definition at line 251 of file bls12_381_fp2.cpp.

251 {
252 m_c0.conditional_assign(cnd, other.m_c0);
253 m_c1.conditional_assign(cnd, other.m_c1);
254}

References FieldElement2().

◆ conjugate()

FieldElement2 Botan::BLS12_381::FieldElement2::conjugate ( ) const

Return the conjugate c0 - c1*u, which is also the image of this element under the Frobenius endomorphism x -> x^p

Definition at line 223 of file bls12_381_fp2.cpp.

223 {
224 return FieldElement2(m_c0, m_c1.negate());
225}

References FieldElement2().

Referenced by Botan::BLS12_381::pow_p2_minus_9_over_16().

◆ deserialize()

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

Deserialization; the c1 coefficient is encoded first, following the ZCash convention for G2 point encoding

Definition at line 161 of file bls12_381_fp2.cpp.

161 {
162 if(bytes.size() != FieldElement2::BYTES) {
163 return {};
164 }
165
166 // The c1 coefficient is encoded first
167 const auto c1 = FieldElement::deserialize(bytes.first(FieldElement::BYTES));
168 const auto c0 = FieldElement::deserialize(bytes.last(FieldElement::BYTES));
169
170 if(!c0 || !c1) {
171 return {};
172 }
173
174 return FieldElement2(*c0, *c1);
175}
static constexpr size_t BYTES
static constexpr size_t BYTES
static std::optional< FieldElement > deserialize(std::span< const uint8_t > bytes)

References BYTES, Botan::BLS12_381::FieldElement::BYTES, c0(), c1(), Botan::BLS12_381::FieldElement::deserialize(), and FieldElement2().

◆ invert()

FieldElement2 Botan::BLS12_381::FieldElement2::invert ( ) const

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

Definition at line 232 of file bls12_381_fp2.cpp.

232 {
233 /*
234 * We wish to compute the inverse of (a + b*u) where u^2 = -1
235 *
236 * Consider the identity (a + b*u)(a - b*u) = a^2 + b^2. Shifting
237 * the terms implies the inverse of (a + b*u) is (a - b*u)/(a^2 + b^2)
238 */
239
240 // First compute (a^2 + b^2)^-1
241 const auto ninv = (m_c0.square() + m_c1.square()).invert();
242
243 // Apply the inverse then additional negate c1
244 return FieldElement2(m_c0 * ninv, (m_c1 * ninv).negate());
245}

References FieldElement2(), invert(), and negate().

Referenced by invert().

◆ is_zero()

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

Definition at line 182 of file bls12_381_fp2.cpp.

182 {
183 return m_c0.is_zero() && m_c1.is_zero();
184}

◆ mul()

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

Definition at line 194 of file bls12_381_fp2.cpp.

194 {
195 // Karatsuba multiplication using 3 base field multiplications:
196 // (a0 + a1*u)(b0 + b1*u) = (a0*b0 - a1*b1) + ((a0+a1)(b0+b1) - a0*b0 - a1*b1)*u
197 const auto v0 = m_c0 * x.m_c0;
198 const auto v1 = m_c1 * x.m_c1;
199 const auto s = (m_c0 + m_c1) * (x.m_c0 + x.m_c1);
200
201 return FieldElement2(v0 - v1, s - v0 - v1);
202}

References FieldElement2().

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

◆ mul_by_nonresidue()

FieldElement2 Botan::BLS12_381::FieldElement2::mul_by_nonresidue ( ) const

Multiplication by the sextic nonresidue u + 1

Definition at line 227 of file bls12_381_fp2.cpp.

227 {
228 // (a + b*u)(u + 1) = (a - b) + (a + b)*u using u^2 = -1
229 return FieldElement2(m_c0 - m_c1, m_c0 + m_c1);
230}

References FieldElement2().

◆ negate()

FieldElement2 Botan::BLS12_381::FieldElement2::negate ( ) const

Definition at line 219 of file bls12_381_fp2.cpp.

219 {
220 return FieldElement2(m_c0.negate(), m_c1.negate());
221}

References FieldElement2().

Referenced by invert(), and sqrt().

◆ one()

◆ operator!=()

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

Definition at line 246 of file bls12_381_fields.h.

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

References FieldElement2().

◆ operator*=()

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

Definition at line 205 of file bls12_381_fields.h.

205 {
206 (*this) = this->mul(x);
207 return (*this);
208 }
FieldElement2 mul(const FieldElement2 &x) const

References FieldElement2(), and mul().

◆ operator+=()

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

Definition at line 195 of file bls12_381_fields.h.

195 {
196 (*this) = this->add(x);
197 return (*this);
198 }
FieldElement2 add(const FieldElement2 &x) const

References add(), and FieldElement2().

◆ operator-=()

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

Definition at line 200 of file bls12_381_fields.h.

200 {
201 (*this) = this->sub(x);
202 return (*this);
203 }
FieldElement2 sub(const FieldElement2 &x) const

References FieldElement2(), and sub().

◆ operator==()

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

Constant time equality

Definition at line 247 of file bls12_381_fp2.cpp.

247 {
248 return (m_c0 == other.m_c0) && (m_c1 == other.m_c1);
249}

References FieldElement2().

◆ serialize()

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

Definition at line 177 of file bls12_381_fields.h.

177 {
178 std::array<uint8_t, FieldElement2::BYTES> buf{};
179 this->serialize_to(buf);
180 return buf;
181 }
void serialize_to(std::span< uint8_t, FieldElement2::BYTES > bytes) const

References serialize_to().

◆ serialize_to()

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

Definition at line 177 of file bls12_381_fp2.cpp.

177 {
178 m_c1.serialize_to(bytes.first<FieldElement::BYTES>());
179 m_c0.serialize_to(bytes.last<FieldElement::BYTES>());
180}

References Botan::BLS12_381::FieldElement::BYTES.

Referenced by serialize().

◆ sqrt()

CT::Option< FieldElement2 > Botan::BLS12_381::FieldElement2::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 260 of file bls12_381_fp2.cpp.

260 {
261 // Algorithm 9 of https://eprint.iacr.org/2012/685.pdf for q == 3 (mod 4)
262
263 constexpr auto FP2_P = hex_to_words<word>(
264 "1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab");
265
266 // (p-3)/4; since p == 3 (mod 4) this is p >> 2
267 constexpr auto FP2_SQRT_EXP = [FP2_P] {
268 auto x = FP2_P;
270 return x;
271 }();
272
273 // (p-1)/2, ie p >> 1
274 constexpr auto FP2_P_HALF = [FP2_P] {
275 auto x = FP2_P;
277 return x;
278 }();
279
280 // a1 = x^((p-3)/4)
281 const auto a1 = pow_msb(*this, FP2_SQRT_EXP);
282
283 // alpha = a1^2 * x = x^((p-1)/2)
284 const auto alpha = a1.square() * (*this);
285
286 // x0 = a1 * x = x^((p+1)/4)
287 const auto x0 = a1 * (*this);
288
289 // If alpha == -1 the square root is x0 * u; otherwise it is
290 // (1 + alpha)^((p-1)/2) * x0. In the first case 1 + alpha == 0 so the
291 // generic computation yields zero and is overridden in constant time.
292 auto candidate = pow_msb(alpha + FieldElement2::one(), FP2_P_HALF) * x0;
293
294 const auto x0_u = FieldElement2(x0.c1().negate(), x0.c0());
295 const auto alpha_is_neg_one = (alpha == FieldElement2::one().negate());
296 candidate.conditional_assign(alpha_is_neg_one, x0_u);
297
298 return CT::Option<FieldElement2>(candidate, candidate.square() == (*this));
299}
FE pow_msb(const FE &x, const std::array< word, N > &exp)
constexpr auto hex_to_words(const char(&s)[N])
Definition mp_core.h:921
constexpr W shift_right(std::array< W, N > &x)
Definition mp_core.h:904

References FieldElement2(), Botan::hex_to_words(), negate(), one(), Botan::BLS12_381::pow_msb(), and Botan::shift_right().

◆ square()

FieldElement2 Botan::BLS12_381::FieldElement2::square ( ) const

Definition at line 204 of file bls12_381_fp2.cpp.

204 {
205 // Complex squaring using 2 base field multiplications:
206 // (a + b*u)^2 = (a+b)(a-b) + (2ab)*u
207 const auto t0 = (m_c0 + m_c1) * (m_c0 - m_c1);
208 const auto t1 = m_c0 * m_c1;
209
210 return FieldElement2(t0, t1 + t1);
211}

References FieldElement2().

Referenced by Botan::BLS12_381::Fp12::cyclotomic_square(), Botan::BLS12_381::pow_p2_minus_9_over_16(), and square_n().

◆ square_n()

void Botan::BLS12_381::FieldElement2::square_n ( size_t n)

Definition at line 213 of file bls12_381_fp2.cpp.

213 {
214 for(size_t i = 0; i != n; ++i) {
215 (*this) = this->square();
216 }
217}

References square().

◆ sub()

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

Definition at line 190 of file bls12_381_fp2.cpp.

190 {
191 return FieldElement2(m_c0 - x.m_c0, m_c1 - x.m_c1);
192}

References FieldElement2().

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

◆ zero()

FieldElement2 Botan::BLS12_381::FieldElement2::zero ( )
inlinestatic

Definition at line 165 of file bls12_381_fields.h.

165{ return FieldElement2(); }

References FieldElement2().

Referenced by Botan::BLS12_381::G2Affine::identity(), and Botan::BLS12_381::Fp6::one().

Member Data Documentation

◆ BYTES

size_t Botan::BLS12_381::FieldElement2::BYTES = 2 * FieldElement::BYTES
staticconstexpr

Definition at line 158 of file bls12_381_fields.h.

Referenced by deserialize().


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