com.fitbur.bouncycastle.pqc.math.linearalgebra.GF2nElement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of external-docker-java Show documentation
There is a newer version: 1.0.0
package com.fitbur.bouncycastle.pqc.math.linearalgebra;


/**
 * This abstract class implements an element of the finite field GF(2)^{n
 *} in either optimal normal basis representation (ONB)
 * or in polynomial representation. It is extended by the classes  GF2nONBElement and  GF2nPolynomialElement .
 *
 * @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 com.fitburgree n 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 true 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 this element + 1.
     *
     * @return this + 1
     */
    public abstract GF2nElement increase();

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

    /**
     * Compute the difference of this element and minuend.
     *
     * @param minuend the minuend
     * @return this - minuend (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 minuend,
     * 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 this element to the power of 2.
     *
     * @return this²
     */
    public abstract GF2nElement square();

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

    /**
     * Compute the square root of this element and return the result in a new
     * {@link GF2nElement}.
     *
     * @return this^1/2 (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
     * basis.
     *
     * @param basis the GF2nField representation to transform this element to
     * @return this element in the representation of basis
     * @throws DifferentFieldsException if this cannot be converted according to
     * basis.
     */
    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.

     * Let z² + z = this. Then this method returns z.
     *
     * @return z with z² + z = this
     * @throws NoSolutionException if z² + z = this does not have a
     * solution
     */
    public abstract GF2nElement solveQuadraticEquation()
        throws RuntimeException;

}