bcprov/src/main/java/org/bouncycastle/pqc/math/linearalgebra/GF2nElement.java

package org.bouncycastle.pqc.math.linearalgebra;


/**
 * This abstract class implements an element of the finite field <i>GF(2)<sup>n
 * </sup></i> in either <i>optimal normal basis</i> representation (<i>ONB</i>)
 * or in <i>polynomial</i> representation. It is extended by the classes <a
 * href = GF2nONBElement.html><tt> GF2nONBElement</tt></a> and <a href =
 * GF2nPolynomialElement.html> <tt>GF2nPolynomialElement</tt> </a>.
 *
 * @see GF2nPolynomialElement
 * @see GF2nONBElement
 * @see GF2nONBField
 */
public abstract class GF2nElement
    implements GFElement
{

    // /////////////////////////////////////////////////////////////////////
    // member variables
    // /////////////////////////////////////////////////////////////////////

    /**
     * holds a pointer to this element's corresponding field.
     */
    protected GF2nField mField;

    /**
     * holds the extension degree <i>n</i> of this element's corresponding
     * field.
     */
    protected int mDegree;

    // /////////////////////////////////////////////////////////////////////
    // pseudo-constructors
    // /////////////////////////////////////////////////////////////////////

    /**
     * @return a copy of this GF2nElement
     */
    public abstract Object clone();

    // /////////////////////////////////////////////////////////////////////
    // assignments
    // /////////////////////////////////////////////////////////////////////

    /**
     * Assign the value 0 to this element.
     */
    abstract void assignZero();

    /**
     * Assigns the value 1 to this element.
     */
    abstract void assignOne();

    // /////////////////////////////////////////////////////////////////////
    // access
    // /////////////////////////////////////////////////////////////////////

    /**
     * Returns whether the rightmost bit of the bit representation is set. This
     * is needed for data conversion according to 1363.
     *
     * @return true if the rightmost bit of this element is set
     */
    public abstract boolean testRightmostBit();

    /**
     * Checks whether the indexed bit of the bit representation is set
     *
     * @param index the index of the bit to test
     * @return <tt>true</tt> if the indexed bit is set
     */
    abstract boolean testBit(int index);

    /**
     * Returns the field of this element.
     *
     * @return the field of this element
     */
    public final GF2nField getField()
    {
        return mField;
    }

    // /////////////////////////////////////////////////////////////////////
    // arithmetic
    // /////////////////////////////////////////////////////////////////////

    /**
     * Returns <tt>this</tt> element + 1.
     *
     * @return <tt>this</tt> + 1
     */
    public abstract GF2nElement increase();

    /**
     * Increases this element by one.
     */
    public abstract void increaseThis();

    /**
     * Compute the difference of this element and <tt>minuend</tt>.
     *
     * @param minuend the minuend
     * @return <tt>this - minuend</tt> (newly created)
     * @throws DifferentFieldsException if the elements are of different fields.
     */
    public final GFElement subtract(GFElement minuend)
        throws RuntimeException
    {
        return add(minuend);
    }

    /**
     * Compute the difference of this element and <tt>minuend</tt>,
     * overwriting this element.
     *
     * @param minuend the minuend
     * @throws DifferentFieldsException if the elements are of different fields.
     */
    public final void subtractFromThis(GFElement minuend)
    {
        addToThis(minuend);
    }

    /**
     * Returns <tt>this</tt> element to the power of 2.
     *
     * @return <tt>this</tt><sup>2</sup>
     */
    public abstract GF2nElement square();

    /**
     * Squares <tt>this</tt> element.
     */
    public abstract void squareThis();

    /**
     * Compute the square root of this element and return the result in a new
     * {@link GF2nElement}.
     *
     * @return <tt>this<sup>1/2</sup></tt> (newly created)
     */
    public abstract GF2nElement squareRoot();

    /**
     * Compute the square root of this element.
     */
    public abstract void squareRootThis();

    /**
     * Performs a basis transformation of this element to the given GF2nField
     * <tt>basis</tt>.
     *
     * @param basis the GF2nField representation to transform this element to
     * @return this element in the representation of <tt>basis</tt>
     * @throws DifferentFieldsException if <tt>this</tt> cannot be converted according to
     * <tt>basis</tt>.
     */
    public final GF2nElement convert(GF2nField basis)
        throws RuntimeException
    {
        return mField.convert(this, basis);
    }

    /**
     * Returns the trace of this element.
     *
     * @return the trace of this element
     */
    public abstract int trace();

    /**
     * Solves a quadratic equation.<br>
     * Let z<sup>2</sup> + z = <tt>this</tt>. Then this method returns z.
     *
     * @return z with z<sup>2</sup> + z = <tt>this</tt>
     * @throws NoSolutionException if z<sup>2</sup> + z = <tt>this</tt> does not have a
     * solution
     */
    public abstract GF2nElement solveQuadraticEquation()
        throws RuntimeException;

}