org.bouncycastle.crypto.bls

## Class Fp2Element

- java.lang.Object
- - org.bouncycastle.crypto.bls.Fp2Element

-     public final class Fp2Element
      extends java.lang.Object

  Immutable element of `Fp^2 = Fp[I] / (I^2 + 1)`, used as the base field of BLS12-381 G2.

  All operations reduce modulo p eagerly. Internally the two Fp components are stored as plain `BigInteger` values.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Fp2Element` | `ONE` The Fp^2 one element (1 + 0*I).
    `static java.math.BigInteger` | `P` Field characteristic, identical to the BLS12-381 base field p.
    `static Fp2Element` | `ZERO` The Fp^2 zero element.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Fp2Element` | `add(Fp2Element other)`
    `java.math.BigInteger` | `c0()`
    `java.math.BigInteger` | `c1()`
    `boolean` | `equals(java.lang.Object other)`
    `Fp2Element` | `frobenius()` Frobenius: (c0 + c1*I)^p = c0 - c1*I when p ≡ 3 (mod 4), which holds for the BLS12-381 base field.
    `static Fp2Element` | `fromFp(java.math.BigInteger c0)`
    `int` | `hashCode()`
    `Fp2Element` | `inverse()` Modular inverse: (c0 + c1*I)^-1 = (c0 - c1*I) / (c0^2 + c1^2).
    `boolean` | `isSquare()`
    `boolean` | `isZero()`
    `Fp2Element` | `modPow(java.math.BigInteger exponent)` Modular exponentiation in Fp^2 by a non-negative integer exponent.
    `Fp2Element` | `mul(Fp2Element other)` (a + b*I)(c + d*I) = (ac - bd) + (ad + bc)*I.
    `Fp2Element` | `mulFp(java.math.BigInteger fp)` Multiply by a Fp scalar.
    `Fp2Element` | `neg()`
    `static Fp2Element` | `of(java.math.BigInteger c0, java.math.BigInteger c1)`
    `static Fp2Element` | `of(long c0, long c1)`
    `int` | `sgn0()` RFC 9380 sec. 4.1 sgn0 for m = 2.
    `Fp2Element` | `sqrtOrNull()` Tries to compute a square root of `this` in Fp^2, using the Wahby-Boneh algorithm specialised to p ≡ 3 (mod 4) ("Fast and simple constant-time hashing to the BLS12-381 elliptic curve", Algorithm 1).
    `Fp2Element` | `square()` (a + b*I)^2 = (a-b)(a+b) + 2ab*I.
    `Fp2Element` | `sub(Fp2Element other)`
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### P

          public static final java.math.BigInteger P

      Field characteristic, identical to the BLS12-381 base field p.

    - #### ZERO

          public static final Fp2Element ZERO

      The Fp^2 zero element.

    - #### ONE

          public static final Fp2Element ONE

      The Fp^2 one element (1 + 0*I).

  - ### Method Detail

    - #### of

          public static Fp2Element of(java.math.BigInteger c0,
                                      java.math.BigInteger c1)

    - #### of

          public static Fp2Element of(long c0,
                                      long c1)

    - #### fromFp

          public static Fp2Element fromFp(java.math.BigInteger c0)

    - #### c0

          public java.math.BigInteger c0()

      Returns:
        real component (the c0 in c0 + c1*I).

    - #### c1

          public java.math.BigInteger c1()

      Returns:
        imaginary component (the c1 in c0 + c1*I).

    - #### isZero

          public boolean isZero()

    - #### add

          public Fp2Element add(Fp2Element other)

    - #### sub

          public Fp2Element sub(Fp2Element other)

    - #### neg

          public Fp2Element neg()

    - #### mul

          public Fp2Element mul(Fp2Element other)

      (a + b*I)(c + d*I) = (ac - bd) + (ad + bc)*I.

    - #### mulFp

          public Fp2Element mulFp(java.math.BigInteger fp)

      Multiply by a Fp scalar.

    - #### square

          public Fp2Element square()

      (a + b*I)^2 = (a-b)(a+b) + 2ab*I.

    - #### frobenius

          public Fp2Element frobenius()

      Frobenius: (c0 + c1*I)^p = c0 - c1*I when p ≡ 3 (mod 4), which holds for the BLS12-381 base field.

    - #### inverse

          public Fp2Element inverse()

      Modular inverse: (c0 + c1*I)^-1 = (c0 - c1*I) / (c0^2 + c1^2).

    - #### modPow

          public Fp2Element modPow(java.math.BigInteger exponent)

      Modular exponentiation in Fp^2 by a non-negative integer exponent.

    - #### sgn0

          public int sgn0()

      RFC 9380 sec. 4.1 sgn0 for m = 2.

             sign_0 = c0 mod 2
             zero_0 = (c0 == 0)
             sign_1 = c1 mod 2
             return sign_0 OR (zero_0 AND sign_1)

    - #### sqrtOrNull

          public Fp2Element sqrtOrNull()

      Tries to compute a square root of `this` in Fp^2, using the Wahby-Boneh algorithm specialised to p ≡ 3 (mod 4) ("Fast and simple constant-time hashing to the BLS12-381 elliptic curve", Algorithm 1).
      Returns:
        a square root, or `null` if `this` is not a square.

    - #### isSquare

          public boolean isSquare()

    - #### equals

          public boolean equals(java.lang.Object other)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`