org.spongycastle.pqc.math.linearalgebra

Class GF2nPolynomialElement

java.lang.Object

org.spongycastle.pqc.math.linearalgebra.GF2nElement

org.spongycastle.pqc.math.linearalgebra.GF2nPolynomialElement

All Implemented Interfaces:

GFElement

public class GF2nPolynomialElement
extends GF2nElement

This class implements elements of finite binary fields GF(2ⁿ) 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.spongycastle.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

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.spongycastle.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:

java.lang.RuntimeException

addToThis

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

Compute this + addend (overwrite this).

Parameters:

addend - the addend

Throws:

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:

java.lang.RuntimeException

multiplyThisBy

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

Compute this * factor (overwrite this).

Parameters:

factor - the factor

Throws:

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:

this² (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:

this² (newly created)

See Also:

GF2Polynomial.vectorMult(org.spongycastle.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.spongycastle.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:

this² (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:

this² (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:

this^1/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 z² + 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 z² + z = this

Throws:

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"