GF2nPolynomialElement (Bouncy Castle Library 1.52 API Specification)
Date: 2015-03-01

org.bouncycastle.pqc.math.linearalgebra

## Class GF2nPolynomialElement

- java.lang.Object
- - org.bouncycastle.pqc.math.linearalgebra.GF2nElement
  - - org.bouncycastle.pqc.math.linearalgebra.GF2nPolynomialElement

- All Implemented Interfaces:
    GFElement

      public class GF2nPolynomialElement
      extends GF2nElement

  This class implements elements of finite binary fields GF(2n) using polynomial representation. For more information on the arithmetic see for example IEEE Standard 1363 or Certicom online-tutorial.
  See Also:
    "GF2nField", `GF2nPolynomialField`, `GF2nONBElement`, `GF2Polynomial`

- - ### Field Summary

    - ### Fields inherited from class org.bouncycastle.pqc.math.linearalgebra.GF2nElement

      `mDegree, mField`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GF2nPolynomialElement(GF2nPolynomialElement other)` Creates a new GF2nPolynomialElement by cloning the given GF2nPolynomialElement b.
    `GF2nPolynomialElement(GF2nPolynomialField f, byte[] os)` Creates a new GF2nPolynomialElement using the given field f and byte[] os as value.
    `GF2nPolynomialElement(GF2nPolynomialField f, GF2Polynomial bs)` Creates a new GF2nPolynomialElement using the given field and Bitstring.
    `GF2nPolynomialElement(GF2nPolynomialField f, int[] is)` Creates a new GF2nPolynomialElement using the given field f and int[] is as value.
    `GF2nPolynomialElement(GF2nPolynomialField f, java.util.Random rand)` Create a new random GF2nPolynomialElement using the given field and source of randomness.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `GFElement` | `add(GFElement addend)` Compute the sum of this element and `addend`.
    `void` | `addToThis(GFElement addend)` Compute `this + addend` (overwrite `this`).
    `java.lang.Object` | `clone()` Creates a new GF2nPolynomialElement by cloning this GF2nPolynomialElement.
    `boolean` | `equals(java.lang.Object other)` Compare this element with another object.
    `int` | `hashCode()`
    `GF2nElement` | `increase()` Returns `this` element + 'one".
    `void` | `increaseThis()` Increases this element by 'one'.
    `GFElement` | `invert()` Compute the multiplicative inverse of this element.
    `GF2nPolynomialElement` | `invertEEA()` Calculates the multiplicative inverse of this and returns the result in a new GF2nPolynomialElement.
    `GF2nPolynomialElement` | `invertMAIA()` Calculates the multiplicative inverse of this using the modified almost inverse algorithm and returns the result in a new GF2nPolynomialElement.
    `GF2nPolynomialElement` | `invertSquare()` Calculates the multiplicative inverse of this and returns the result in a new GF2nPolynomialElement.
    `boolean` | `isOne()` Tests if the GF2nPolynomialElement has 'one' as value.
    `boolean` | `isZero()` Checks whether this element is zero.
    `GFElement` | `multiply(GFElement factor)` Compute the product of this element and `factor`.
    `void` | `multiplyThisBy(GFElement factor)` Compute `this * factor` (overwrite `this`).
    `static GF2nPolynomialElement` | `ONE(GF2nPolynomialField f)` Create the one element.
    `GF2nPolynomialElement` | `power(int k)` Calculates this to the power of k and returns the result in a new GF2nPolynomialElement.
    `GF2nElement` | `solveQuadraticEquation()` Solves the quadratic equation `z2 + z = this` if such a solution exists.
    `GF2nElement` | `square()` This method is used internally to map the square()-calls within GF2nPolynomialElement to one of the possible squaring methods.
    `GF2nPolynomialElement` | `squareBitwise()` Squares this GF2nPolynomialElement by shifting left its Bitstring and reducing.
    `GF2nPolynomialElement` | `squareMatrix()` Squares this GF2nPolynomialElement using GF2nField's squaring matrix.
    `GF2nPolynomialElement` | `squarePreCalc()` Squares this GF2nPolynomialElement by using precalculated values and reducing.
    `GF2nElement` | `squareRoot()` Compute the square root of this element and return the result in a new `GF2nPolynomialElement`.
    `void` | `squareRootThis()` Compute the square root of this element.
    `void` | `squareThis()` This method is used internally to map the square()-calls within GF2nPolynomialElement to one of the possible squaring methods.
    `void` | `squareThisBitwise()` Squares this GF2nPolynomialElement by shifting left its Bitstring and reducing.
    `void` | `squareThisMatrix()` Squares this GF2nPolynomialElement using GF2nFields squaring matrix.
    `void` | `squareThisPreCalc()` Squares this GF2nPolynomialElement by using precalculated values and reducing.
    `boolean` | `testRightmostBit()` Returns whether the rightmost bit of the bit representation is set.
    `byte[]` | `toByteArray()` Converts this GF2nPolynomialElement to a byte[] according to 1363.
    `java.math.BigInteger` | `toFlexiBigInt()` Converts this GF2nPolynomialElement to an integer according to 1363.
    `java.lang.String` | `toString()` Returns a string representing this Bitstrings value using hexadecimal radix in MSB-first order.
    `java.lang.String` | `toString(int radix)` Returns a string representing this Bitstrings value using hexadecimal or binary radix in MSB-first order.
    `int` | `trace()` Returns the trace of this GF2nPolynomialElement.
    `static GF2nPolynomialElement` | `ZERO(GF2nPolynomialField f)` Create the zero element.

    - ### Methods inherited from class org.bouncycastle.pqc.math.linearalgebra.GF2nElement

      `convert, getField, subtract, subtractFromThis`

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

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

- - ### Constructor Detail

    - #### GF2nPolynomialElement

          public GF2nPolynomialElement(GF2nPolynomialField f,
                               java.util.Random rand)

      Create a new random GF2nPolynomialElement using the given field and source of randomness.
      Parameters:
        `f` - the GF2nField to use
        `rand` - the source of randomness

    - #### GF2nPolynomialElement

          public GF2nPolynomialElement(GF2nPolynomialField f,
                               GF2Polynomial bs)

      Creates a new GF2nPolynomialElement using the given field and Bitstring.
      Parameters:
        `f` - the GF2nPolynomialField to use
        `bs` - the desired value as Bitstring

    - #### GF2nPolynomialElement

          public GF2nPolynomialElement(GF2nPolynomialField f,
                               byte[] os)

      Creates a new GF2nPolynomialElement using the given field f and byte[] os as value. The conversion is done according to 1363.
      Parameters:
        `f` - the GF2nField to use
        `os` - the octet string to assign to this GF2nPolynomialElement
      See Also:
        "P1363 5.5.5 p23, OS2FEP/OS2BSP"

    - #### GF2nPolynomialElement

          public GF2nPolynomialElement(GF2nPolynomialField f,
                               int[] is)

      Creates a new GF2nPolynomialElement using the given field f and int[] is as value.
      Parameters:
        `f` - the GF2nField to use
        `is` - the integer string to assign to this GF2nPolynomialElement

    - #### GF2nPolynomialElement

          public GF2nPolynomialElement(GF2nPolynomialElement other)

      Creates a new GF2nPolynomialElement by cloning the given GF2nPolynomialElement b.
      Parameters:
        `other` - the GF2nPolynomialElement to clone

  - ### Method Detail

    - #### clone

          public java.lang.Object clone()

      Creates a new GF2nPolynomialElement by cloning this GF2nPolynomialElement.
      Specified by:
        `clone` in interface `GFElement`
      Specified by:
        `clone` in class `GF2nElement`
      Returns:
        a copy of this element

    - #### ZERO

          public static GF2nPolynomialElement ZERO(GF2nPolynomialField f)

      Create the zero element.
      Parameters:
        `f` - the finite field
      Returns:
        the zero element in the given finite field

    - #### ONE

          public static GF2nPolynomialElement ONE(GF2nPolynomialField f)

      Create the one element.
      Parameters:
        `f` - the finite field
      Returns:
        the one element in the given finite field

    - #### isZero

          public boolean isZero()

      Checks whether this element is zero.
      Returns:
        `true` if `this` is the zero element

    - #### isOne

          public boolean isOne()

      Tests if the GF2nPolynomialElement has 'one' as value.
      Returns:
        true if this equals one (this == 1)

    - #### equals

          public boolean equals(java.lang.Object other)

      Compare this element with another object.
      Specified by:
        `equals` in interface `GFElement`
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - the other object
      Returns:
        `true` if the two objects are equal, `false` otherwise

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `GFElement`
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code of this element

    - #### testRightmostBit

          public boolean testRightmostBit()

      Returns whether the rightmost bit of the bit representation is set. This is needed for data conversion according to 1363.
      Specified by:
        `testRightmostBit` in class `GF2nElement`
      Returns:
        true if the rightmost bit of this element is set

    - #### add

          public GFElement add(GFElement addend)
                        throws java.lang.RuntimeException

      Compute the sum of this element and `addend`.
      Parameters:
        `addend` - the addend
      Returns:
        `this + other` (newly created)
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.
        `java.lang.RuntimeException`

    - #### addToThis

          public void addToThis(GFElement addend)
                         throws java.lang.RuntimeException

      Compute `this + addend` (overwrite `this`).
      Parameters:
        `addend` - the addend
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.
        `java.lang.RuntimeException`

    - #### increase

          public GF2nElement increase()

      Returns `this` element + 'one".
      Specified by:
        `increase` in class `GF2nElement`
      Returns:
        `this` + 'one'

    - #### increaseThis

          public void increaseThis()

      Increases this element by 'one'.
      Specified by:
        `increaseThis` in class `GF2nElement`

    - #### multiply

          public GFElement multiply(GFElement factor)
                             throws java.lang.RuntimeException

      Compute the product of this element and `factor`.
      Parameters:
        `factor` - the factor
      Returns:
        `this * factor` (newly created)
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.
        `java.lang.RuntimeException`

    - #### multiplyThisBy

          public void multiplyThisBy(GFElement factor)
                              throws java.lang.RuntimeException

      Compute `this * factor` (overwrite `this`).
      Parameters:
        `factor` - the factor
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.
        `java.lang.RuntimeException`

    - #### invert

          public GFElement invert()
                           throws java.lang.ArithmeticException

      Compute the multiplicative inverse of this element.
      Returns:
        `this-1` (newly created)
      Throws:
        `java.lang.ArithmeticException` - if `this` is the zero element.
      See Also:
        `invertMAIA()`, `invertEEA()`, `invertSquare()`

    - #### invertEEA

          public GF2nPolynomialElement invertEEA()
                                          throws java.lang.ArithmeticException

      Calculates the multiplicative inverse of this and returns the result in a new GF2nPolynomialElement.
      Returns:
        this^(-1)
      Throws:
        `java.lang.ArithmeticException` - if this equals zero

    - #### invertSquare

          public GF2nPolynomialElement invertSquare()
                                             throws java.lang.ArithmeticException

      Calculates the multiplicative inverse of this and returns the result in a new GF2nPolynomialElement.
      Returns:
        this^(-1)
      Throws:
        `java.lang.ArithmeticException` - if this equals zero

    - #### invertMAIA

          public GF2nPolynomialElement invertMAIA()
                                           throws java.lang.ArithmeticException

      Calculates the multiplicative inverse of this using the modified almost inverse algorithm and returns the result in a new GF2nPolynomialElement.
      Returns:
        this^(-1)
      Throws:
        `java.lang.ArithmeticException` - if this equals zero

    - #### square

          public GF2nElement square()

      This method is used internally to map the square()-calls within GF2nPolynomialElement to one of the possible squaring methods.
      Specified by:
        `square` in class `GF2nElement`
      Returns:
        `this2` (newly created)
      See Also:
        `squarePreCalc()`

    - #### squareThis

          public void squareThis()

      This method is used internally to map the square()-calls within GF2nPolynomialElement to one of the possible squaring methods.
      Specified by:
        `squareThis` in class `GF2nElement`

    - #### squareMatrix

          public GF2nPolynomialElement squareMatrix()

      Squares this GF2nPolynomialElement using GF2nField's squaring matrix. This is supposed to be fast when using a polynomial (no tri- or pentanomial) as fieldpolynomial. Use squarePreCalc when using a tri- or pentanomial as fieldpolynomial instead.
      Returns:
        `this2` (newly created)
      See Also:
        `GF2Polynomial.vectorMult(org.bouncycastle.pqc.math.linearalgebra.GF2Polynomial)`, `squarePreCalc()`, `squareBitwise()`

    - #### squareThisMatrix

          public void squareThisMatrix()

      Squares this GF2nPolynomialElement using GF2nFields squaring matrix. This is supposed to be fast when using a polynomial (no tri- or pentanomial) as fieldpolynomial. Use squarePreCalc when using a tri- or pentanomial as fieldpolynomial instead.
      See Also:
        `GF2Polynomial.vectorMult(org.bouncycastle.pqc.math.linearalgebra.GF2Polynomial)`, `squarePreCalc()`, `squareBitwise()`

    - #### squareBitwise

          public GF2nPolynomialElement squareBitwise()

      Squares this GF2nPolynomialElement by shifting left its Bitstring and reducing. This is supposed to be the slowest method. Use squarePreCalc or squareMatrix instead.
      Returns:
        `this2` (newly created)
      See Also:
        `squareMatrix()`, `squarePreCalc()`, `GF2Polynomial.squareThisBitwise()`

    - #### squareThisBitwise

          public void squareThisBitwise()

      Squares this GF2nPolynomialElement by shifting left its Bitstring and reducing. This is supposed to be the slowest method. Use squarePreCalc or squareMatrix instead.
      See Also:
        `squareMatrix()`, `squarePreCalc()`, `GF2Polynomial.squareThisBitwise()`

    - #### squarePreCalc

          public GF2nPolynomialElement squarePreCalc()

      Squares this GF2nPolynomialElement by using precalculated values and reducing. This is supposed to de fastest when using a trinomial or pentanomial as field polynomial. Use squareMatrix when using a ordinary polynomial as field polynomial.
      Returns:
        `this2` (newly created)
      See Also:
        `squareMatrix()`, `GF2Polynomial.squareThisPreCalc()`

    - #### squareThisPreCalc

          public void squareThisPreCalc()

      Squares this GF2nPolynomialElement by using precalculated values and reducing. This is supposed to de fastest when using a tri- or pentanomial as fieldpolynomial. Use squareMatrix when using a ordinary polynomial as fieldpolynomial.
      See Also:
        `squareMatrix()`, `GF2Polynomial.squareThisPreCalc()`

    - #### power

          public GF2nPolynomialElement power(int k)

      Calculates this to the power of k and returns the result in a new GF2nPolynomialElement.
      Parameters:
        `k` - the power
      Returns:
        this^k in a new GF2nPolynomialElement

    - #### squareRoot

          public GF2nElement squareRoot()

      Compute the square root of this element and return the result in a new `GF2nPolynomialElement`.
      Specified by:
        `squareRoot` in class `GF2nElement`
      Returns:
        `this1/2` (newly created)

    - #### squareRootThis

          public void squareRootThis()

      Compute the square root of this element.
      Specified by:
        `squareRootThis` in class `GF2nElement`

    - #### solveQuadraticEquation

          public GF2nElement solveQuadraticEquation()
                                             throws java.lang.RuntimeException

      Solves the quadratic equation `z2 + z = this` if such a solution exists. This method returns one of the two possible solutions. The other solution is `z + 1`. Use z.increase() to compute this solution.
      Specified by:
        `solveQuadraticEquation` in class `GF2nElement`
      Returns:
        a GF2nPolynomialElement representing one z satisfying the equation `z2 + z = this`
      Throws:
        `NoSolutionException` - if no solution exists
        `java.lang.RuntimeException`
      See Also:
        "IEEE 1363, Annex A.4.7"

    - #### trace

          public int trace()

      Returns the trace of this GF2nPolynomialElement.
      Specified by:
        `trace` in class `GF2nElement`
      Returns:
        the trace of this GF2nPolynomialElement

    - #### toString

          public java.lang.String toString()

      Returns a string representing this Bitstrings value using hexadecimal radix in MSB-first order.
      Specified by:
        `toString` in interface `GFElement`
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a String representing this Bitstrings value.

    - #### toString

          public java.lang.String toString(int radix)

      Returns a string representing this Bitstrings value using hexadecimal or binary radix in MSB-first order.
      Parameters:
        `radix` - the radix to use (2 or 16, otherwise 2 is used)
      Returns:
        a String representing this Bitstrings value.

    - #### toByteArray

          public byte[] toByteArray()

      Converts this GF2nPolynomialElement to a byte[] according to 1363.
      Returns:
        a byte[] representing the value of this GF2nPolynomialElement
      See Also:
        "P1363 5.5.2 p22f BS2OSP, FE2OSP"

    - #### toFlexiBigInt

          public java.math.BigInteger toFlexiBigInt()

      Converts this GF2nPolynomialElement to an integer according to 1363.
      Returns:
        a BigInteger representing the value of this GF2nPolynomialElement
      See Also:
        "P1363 5.5.1 p22 BS2IP"