BinaryField (ECCelerate 6.2 API)

java.lang.Object
- java.security.spec.ECFieldF2m
- - iaik.security.ec.math.field.BinaryField

All Implemented Interfaces:

Field, GenericField, ECField
```
public class BinaryField
extends ECFieldF2m
implements Field
```
This class implements arbitrary finite fields of even characteristic. Although it has been optimized for speed there are still more specific (i.e. faster) classes, which are part of the addon.
Note that due to reasons of performance the arithmetical methods of this class do not check, whether the inputs are valid elements of this field.
Also note that (almost) all methods in this class work in-place. So, there is no guarantee that values input to methods in this class will not be overridden. In case of doubt and if values need to be reused, always clone the value, before inputting it to a method.
References:
[1] Darrel Hankerson, Alfred J. Menezes and Scott Vanstone. Guide to Elliptic Curve Cryptography. Springer-Verlag New York, Inc. (2003)
[2] Henri Cohen and Gerhard Frey. Handbook of Elliptic and Hyperelliptic Curve Cryptography. Chapman & Hall/CRC (2005)
[3] J. von zur Gathen and M. Noecker. Polynomial and normal bases for finite fields. J. Cryptology (2005)
[4] Omran Ahmadi and Alfred Menezes. On the Number of Trace-One Elements in Polynomial Bases. In Designs, Codes and Cryptography, Springer Netherlands (2005)

Author:

Christian Hanser

See Also:

PrimeField, BinaryFieldElement, BinaryFieldByIrreducibleFactory, BinaryFieldByBitLengthFactory

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`BINARY_FIELD_OID` Object Identifier for a binary field for ASN.1 encoding.
`static iaik.asn1.ObjectID`	`CHARACTERISTIC_TWO_GN_BASIS_OID` Object Identifiers for the Gaussian normal basis
`static iaik.asn1.ObjectID`	`CHARACTERISTIC_TWO_PP_BASIS_OID` Object Identifiers for the pentamonial basis
`static iaik.asn1.ObjectID`	`CHARACTERISTIC_TWO_TP_BASIS_OID` Object Identifiers for the trinomial basis

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static BinaryFieldElement`	`add(FieldElement a, FieldElement b, boolean preserveB)` Adds two field elements.
`BinaryFieldElement`	`add(GenericFieldElement a, GenericFieldElement b)` Adds `b` to `a`, i.e.
`BinaryFieldElement`	`addOutOfPlace(GenericFieldElement a, GenericFieldElement b)` Adds two elements and returns a new object holding the result.
`BinaryFieldElement`	`divide(GenericFieldElement a, GenericFieldElement b)` Divides `a` by `b`, i.e.
`boolean`	`equals(Object obj)`
`BinaryFieldElement`	`exponentiate(GenericFieldElement a, BigInteger n)` Raises `a` to the power `n`, i.e.
`BinaryFieldElement`	`exponentiate(GenericFieldElement a, int n)` Raises `a` to the power `n`, i.e.
`BinaryFieldElement`	`exponentiateByPowerOf2(GenericFieldElement a, int n)` Raises `a` to the power `2ⁿ`.
`Field`	`getBaseField()` Returns `this`, although base field would be F_2.
`BigInteger`	`getCardinality()` Returns the cardinality of this field.
`static PrecomputationData`	`getExtendedPrecomputationData(BinaryFieldElement b)` Compiles 256 precomputed values for the multiplication algorithm.
`FieldTypes`	`getFieldType()` Returns the field type of the underlying implementation.
`BinaryFieldElement`	`getGenerator()` Returns the generator of this binary field.
`BinaryFieldElement`	`getOne()` Returns the one element.
`static PrecomputationData`	`getPrecomputationData(BinaryFieldElement b)` Compiles 16 precomputed values for the multiplication algorithm.
`int`	`getTrace(BinaryFieldElement a)` Determines the trace of a field element in constant time (see [2, Remarks 11.57 (ii)] and [4]).
`BinaryFieldElement`	`getTraceOneElement()` Returns an element of trace 1.
`BinaryFieldElement`	`getZero()` Returns the zero element.
`int`	`hashCode()`
`BinaryFieldElement`	`invert(GenericFieldElement a)` Inverts `a`, i.e.
`GenericFieldElement[]`	`invertElements(GenericFieldElement[] elements)` Simultaneously inverts an an array of field elements.
`BinaryFieldElement`	`multiply(BinaryFieldElement a, PrecomputationData b)` Multiplies the field element `a` with another element `b`, where the latter is given as precomputation data.
`BinaryFieldElement`	`multiply(GenericFieldElement a, BigInteger b)` Multiplies `a` by `n`, i.e.
`BinaryFieldElement`	`multiply(GenericFieldElement a, GenericFieldElement b)` Multiplies `a` by `b`, i.e.
`BinaryFieldElement`	`multiplyOutOfPlace(BinaryFieldElement a, PrecomputationData b)` Multiplies the field element `a` with another element `b`, where the latter is given as precomputation data, where a new object holding the result is created.
`BinaryFieldElement`	`multiplyOutOfPlace(GenericFieldElement a, BigInteger b)` Multiplies `a` by `n`, i.e.
`BinaryFieldElement`	`multiplyOutOfPlace(GenericFieldElement a, GenericFieldElement b)` Multiplies `a` by `b`, i.e.
`BinaryFieldElement`	`negate(GenericFieldElement a)` Negates `a`, i.e.
`BinaryFieldElement`	`negateOutOfPlace(GenericFieldElement a)` Negates `a`, i.e.
`BinaryFieldElement`	`newElement(BigInteger b)` Creates a new field element from its `BigInteger` representation.
`BinaryFieldElement`	`newElement(byte[] bytes)` Creates a new field element from a `byte[]`.
`BinaryFieldElement[]`	`solveEquation(BinaryFieldElement c)` This method finds a solution to the equation X² + X = c.
`BinaryFieldElement[]`	`solveEquation(BinaryFieldElement a, BinaryFieldElement b)` This method finds solutions to the equation X² + aX = b.
`BinaryFieldElement`	`square(GenericFieldElement a)` Squares `a`, i.e.
`BinaryFieldElement`	`squareOutOfPlace(GenericFieldElement a)` Squares `a`, i.e.
`BinaryFieldElement`	`squareRoot(FieldElement a)` Computes the square root of a field element.
`BinaryFieldElement`	`subtract(GenericFieldElement a, GenericFieldElement b)` Subtracts `b` from `a`, i.e.
`BinaryFieldElement`	`subtractOutOfPlace(GenericFieldElement a, GenericFieldElement b)` Subtract two elements and returns a new object holding the result.
`iaik.asn1.SEQUENCE`	`toASN1Object()` Compiles and returns the ASN.1 representation of this binary field, which is:
`byte[]`	`toByteArray(FieldElement a)` Converts a field element to its raw `byte[]` representation.
`BinaryFieldElement`	`toElement(byte[] bytes)` Create new field element from a `byte`-array.
`String`	`toString()`

Methods inherited from class java.security.spec.ECFieldF2m
getFieldSize, getM, getMidTermsOfReductionPolynomial, getReductionPolynomial

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.security.spec.ECField
getFieldSize

- Field Detail
  - BINARY_FIELD_OID
```
public static final String BINARY_FIELD_OID
```
    Object Identifier for a binary field for ASN.1 encoding.
    
    See Also:
    
    Constant Field Values
  - CHARACTERISTIC_TWO_GN_BASIS_OID
```
public static final iaik.asn1.ObjectID CHARACTERISTIC_TWO_GN_BASIS_OID
```
    Object Identifiers for the Gaussian normal basis
  - CHARACTERISTIC_TWO_TP_BASIS_OID
```
public static final iaik.asn1.ObjectID CHARACTERISTIC_TWO_TP_BASIS_OID
```
    Object Identifiers for the trinomial basis
  - CHARACTERISTIC_TWO_PP_BASIS_OID
```
public static final iaik.asn1.ObjectID CHARACTERISTIC_TWO_PP_BASIS_OID
```
    Object Identifiers for the pentamonial basis
- Method Detail
  - negate
```
public BinaryFieldElement negate(GenericFieldElement a)
```
    Description copied from interface: GenericField
    
    Negates a, i.e. performs the operation b = -b.
    
    Specified by:
    
    negate in interface Field
    
    Specified by:
    
    negate in interface GenericField
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    the negative of a
  - negateOutOfPlace
```
public BinaryFieldElement negateOutOfPlace(GenericFieldElement a)
```
    Description copied from interface: GenericField
    
    Negates a, i.e. performs the operation b = -b, where a new object holding the result is created.
    
    Specified by:
    
    negateOutOfPlace in interface Field
    
    Specified by:
    
    negateOutOfPlace in interface GenericField
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    the negative of a
  - add
```
public BinaryFieldElement add(GenericFieldElement a,
                              GenericFieldElement b)
```
    Description copied from interface: GenericField
    
    Adds b to a, i.e. performs the operation a += b.
    
    Specified by:
    
    add in interface Field
    
    Specified by:
    
    add in interface GenericField
    
    Parameters:
    
    a - the first addend
    
    b - the second addend
    
    Returns:
    
    the sum of a and b
  - addOutOfPlace
```
public BinaryFieldElement addOutOfPlace(GenericFieldElement a,
                                        GenericFieldElement b)
```
    Adds two elements and returns a new object holding the result.
    
    Parameters:
    
    a - the first value
    
    b - the other value
    
    Returns:
    
    the sum
  - add
```
public static BinaryFieldElement add(FieldElement a,
                                     FieldElement b,
                                     boolean preserveB)
```
    Adds two field elements. If preserveB is set to false it overwrites the value of b, if the raw value of b is longer than that of a.
    
    Parameters:
    
    a - the first addend
    
    b - the second addend
    
    preserveB - determines whether b can be overwritten
    
    Returns:
    
    the sum of a and b
  - subtract
```
public BinaryFieldElement subtract(GenericFieldElement a,
                                   GenericFieldElement b)
```
    Description copied from interface: GenericField
    
    Subtracts b from a, i.e. performs the operation a -= b.
    
    Specified by:
    
    subtract in interface Field
    
    Specified by:
    
    subtract in interface GenericField
    
    Parameters:
    
    a - the minuend
    
    b - the subtrahend
    
    Returns:
    
    the difference of a and b
  - subtractOutOfPlace
```
public BinaryFieldElement subtractOutOfPlace(GenericFieldElement a,
                                             GenericFieldElement b)
```
    Subtract two elements and returns a new object holding the result.
    
    Parameters:
    
    a - the first value
    
    b - the other value
    
    Returns:
    
    the difference
  - invert
```
public BinaryFieldElement invert(GenericFieldElement a)
```
    Description copied from interface: GenericField
    
    Inverts a, i.e. performs the operation a = a^(-1).
    
    Specified by:
    
    invert in interface Field
    
    Specified by:
    
    invert in interface GenericField
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    the inverse of a
  - invertElements
```
public GenericFieldElement[] invertElements(GenericFieldElement[] elements)
```
    Description copied from interface: GenericField
    
    Simultaneously inverts an an array of field elements.
    
    Specified by:
    
    invertElements in interface GenericField
    
    Parameters:
    
    elements - the array of field elements
    
    Returns:
    
    the array holding the inverted elements (in the same order as the input elements)
  - divide
```
public BinaryFieldElement divide(GenericFieldElement a,
                                 GenericFieldElement b)
```
    Description copied from interface: GenericField
    
    Divides a by b, i.e. performs the operation a /= b.
    
    Specified by:
    
    divide in interface Field
    
    Specified by:
    
    divide in interface GenericField
    
    Parameters:
    
    a - the dividend
    
    b - the divisor
    
    Returns:
    
    the quotient of a and b
  - multiply
```
public BinaryFieldElement multiply(GenericFieldElement a,
                                   GenericFieldElement b)
```
    Description copied from interface: GenericField
    
    Multiplies a by b, i.e. performs the operation a *= b.
    
    Specified by:
    
    multiply in interface Field
    
    Specified by:
    
    multiply in interface GenericField
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and b
  - multiplyOutOfPlace
```
public BinaryFieldElement multiplyOutOfPlace(GenericFieldElement a,
                                             GenericFieldElement b)
```
    Description copied from interface: GenericField
    
    Multiplies a by b, i.e. performs the operation a *= b, where a new object holding the result is created.
    
    Specified by:
    
    multiplyOutOfPlace in interface Field
    
    Specified by:
    
    multiplyOutOfPlace in interface GenericField
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and b
  - multiply
```
public BinaryFieldElement multiply(GenericFieldElement a,
                                   BigInteger b)
```
    Description copied from interface: GenericField
    
    Multiplies a by n, i.e. performs the operation a *= n.
    
    Specified by:
    
    multiply in interface Field
    
    Specified by:
    
    multiply in interface GenericField
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and n
  - multiplyOutOfPlace
```
public BinaryFieldElement multiplyOutOfPlace(GenericFieldElement a,
                                             BigInteger b)
```
    Description copied from interface: GenericField
    
    Multiplies a by n, i.e. performs the operation a *= n, where a new object holding the result is created.
    
    Specified by:
    
    multiplyOutOfPlace in interface Field
    
    Specified by:
    
    multiplyOutOfPlace in interface GenericField
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and n
  - multiply
```
public BinaryFieldElement multiply(BinaryFieldElement a,
                                   PrecomputationData b)
```
    Multiplies the field element a with another element b, where the latter is given as precomputation data.
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and b
  - multiplyOutOfPlace
```
public BinaryFieldElement multiplyOutOfPlace(BinaryFieldElement a,
                                             PrecomputationData b)
```
    Multiplies the field element a with another element b, where the latter is given as precomputation data, where a new object holding the result is created.
    
    Parameters:
    
    a - the first factor
    
    b - the second factor
    
    Returns:
    
    the product of a and b
  - square
```
public BinaryFieldElement square(GenericFieldElement a)
```
    Description copied from interface: GenericField
    
    Squares a, i.e. performs the operation a *= a.
    
    Specified by:
    
    square in interface Field
    
    Specified by:
    
    square in interface GenericField
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    a field element representing the square of a
  - squareOutOfPlace
```
public BinaryFieldElement squareOutOfPlace(GenericFieldElement a)
```
    Description copied from interface: GenericField
    
    Squares a, i.e. performs the operation a*a, where a new object holding the result is created.
    
    Specified by:
    
    squareOutOfPlace in interface Field
    
    Specified by:
    
    squareOutOfPlace in interface GenericField
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    a field element representing the square of a
  - getExtendedPrecomputationData
```
public static PrecomputationData getExtendedPrecomputationData(BinaryFieldElement b)
```
    Compiles 256 precomputed values for the multiplication algorithm. Note: the raw value of b is referenced inside the precomputation data. Hence, if it is changed afterwards, also the precomputation data changes!!
    
    Parameters:
    
    b - the value for which the precomputation data will be created
    
    Returns:
    
    an object holding the precomputed values
  - getPrecomputationData
```
public static PrecomputationData getPrecomputationData(BinaryFieldElement b)
```
    Compiles 16 precomputed values for the multiplication algorithm. Note: the raw value of b is referenced inside the precomputation data. Hence, if it is changed afterwards, also the precomputation data changes!!
    
    Parameters:
    
    b - the value for which the precomputation data will be created
    
    Returns:
    
    an object holding the precomputed values
  - squareRoot
```
public BinaryFieldElement squareRoot(FieldElement a)
```
    Description copied from interface: Field
    
    Computes the square root of a field element.
    
    Specified by:
    
    squareRoot in interface Field
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    a field element representing the square root of a
  - exponentiate
```
public BinaryFieldElement exponentiate(GenericFieldElement a,
                                       BigInteger n)
```
    Description copied from interface: GenericField
    
    Raises a to the power n, i.e. performs the operation a = a^n.
    
    Specified by:
    
    exponentiate in interface Field
    
    Specified by:
    
    exponentiate in interface GenericField
    
    Parameters:
    
    a - the field element
    
    n - the exponent
    
    Returns:
    
    a field element representing the nth power of a
  - exponentiate
```
public BinaryFieldElement exponentiate(GenericFieldElement a,
                                       int n)
```
    Description copied from interface: GenericField
    
    Raises a to the power n, i.e. performs the operation a = a^n.
    
    Specified by:
    
    exponentiate in interface GenericField
    
    Parameters:
    
    a - the field element
    
    n - the exponent
    
    Returns:
    
    a field element representing the nth power of a
  - exponentiateByPowerOf2
```
public BinaryFieldElement exponentiateByPowerOf2(GenericFieldElement a,
                                                 int n)
```
    Description copied from interface: GenericField
    
    Raises a to the power 2ⁿ.
    
    Specified by:
    
    exponentiateByPowerOf2 in interface Field
    
    Specified by:
    
    exponentiateByPowerOf2 in interface GenericField
    
    Parameters:
    
    a - the field element
    
    n - the exponent
    
    Returns:
    
    the resulting field element
  - newElement
```
public BinaryFieldElement newElement(BigInteger b)
```
    Description copied from interface: Field
    
    Creates a new field element from its BigInteger representation.
    
    Specified by:
    
    newElement in interface Field
    
    Parameters:
    
    b - the BigInteger
    
    Returns:
    
    the field element
  - newElement
```
public final BinaryFieldElement newElement(byte[] bytes)
```
    Description copied from interface: Field
    
    Creates a new field element from a byte[].
    
    Specified by:
    
    newElement in interface Field
    
    Specified by:
    
    newElement in interface GenericField
    
    Parameters:
    
    bytes - the element encoded as byte[] in little-endian order
    
    Returns:
    
    the field element
  - toElement
```
public final BinaryFieldElement toElement(byte[] bytes)
```
    Description copied from interface: GenericField
    
    Create new field element from a byte-array. Unlike GenericField.newElement(byte[]), this method does not assume the input to be a valid encoding of a field element.
    
    Specified by:
    
    toElement in interface GenericField
    
    Parameters:
    
    bytes - a byte[] in little-endian order
    
    Returns:
    
    an object holding the new field element
  - getOne
```
public final BinaryFieldElement getOne()
```
    Description copied from interface: GenericField
    
    Returns the one element.
    
    Specified by:
    
    getOne in interface Field
    
    Specified by:
    
    getOne in interface GenericField
    
    Returns:
    
    an object holding the one element
  - getZero
```
public final BinaryFieldElement getZero()
```
    Description copied from interface: GenericField
    
    Returns the zero element.
    
    Specified by:
    
    getZero in interface Field
    
    Specified by:
    
    getZero in interface GenericField
    
    Returns:
    
    an object holding the zero element
  - getGenerator
```
public final BinaryFieldElement getGenerator()
```
    Returns the generator of this binary field.
    
    Returns:
    
    an object holding the generator
  - getTraceOneElement
```
public final BinaryFieldElement getTraceOneElement()
```
    Returns an element of trace 1.
    
    Returns:
    
    an element of trace 1
  - getTrace
```
public int getTrace(BinaryFieldElement a)
```
    Determines the trace of a field element in constant time (see [2, Remarks 11.57 (ii)] and [4]).
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    the trace t in {0, 1} of a
  - getCardinality
```
public final BigInteger getCardinality()
```
    Description copied from interface: GenericField
    
    Returns the cardinality of this field.
    
    Specified by:
    
    getCardinality in interface GenericField
    
    Returns:
    
    a BigInteger holding the cardinality
  - getFieldType
```
public final FieldTypes getFieldType()
```
    Description copied from interface: GenericField
    
    Returns the field type of the underlying implementation.
    
    Specified by:
    
    getFieldType in interface GenericField
    
    Returns:
    
    the field type
  - getBaseField
```
public final Field getBaseField()
```
    Returns this, although base field would be F_2.
    
    Specified by:
    
    getBaseField in interface GenericField
    
    Returns:
    
    the base field
  - solveEquation
```
public final BinaryFieldElement[] solveEquation(BinaryFieldElement c)
```
    This method finds a solution to the equation X² + X = c.
    
    Parameters:
    
    c - the constant
    
    Returns:
    
    null if there is no solution, otherwise an array holding the two solutions
  - solveEquation
```
public final BinaryFieldElement[] solveEquation(BinaryFieldElement a,
                                                BinaryFieldElement b)
```
    This method finds solutions to the equation X² + aX = b.
    
    Parameters:
    
    a - the coefficient of the linear term
    
    b - the constant
    
    Returns:
    
    null if there is no solution, otherwise an array holding the two solutions
  - toByteArray
```
public byte[] toByteArray(FieldElement a)
```
    Description copied from interface: Field
    
    Converts a field element to its raw byte[] representation.
    
    Specified by:
    
    toByteArray in interface Field
    
    Parameters:
    
    a - the field element
    
    Returns:
    
    a byte[]
  - toASN1Object
```
public iaik.asn1.SEQUENCE toASN1Object()
```
    Compiles and returns the ASN.1 representation of this binary field, which is:
```
  FieldID ::= SEQUENCE {
    fieldType   OBJECT IDENTIFIER,
    parameters  ANY DEFINED BY fieldType
  }
 
```
    Specified by:
    
    toASN1Object in interface Field
    
    Returns:
    
    the ASN.1 representation of this binary field
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
public final boolean equals(Object obj)
```
    Specified by:
    
    equals in interface GenericField
    
    Overrides:
    
    equals in class ECFieldF2m
  - hashCode
```
public final int hashCode()
```
    Specified by:
    
    hashCode in interface GenericField
    
    Overrides:
    
    hashCode in class ECFieldF2m

Class BinaryField

Field Summary

Method Summary

Methods inherited from class java.security.spec.ECFieldF2m

Methods inherited from class java.lang.Object

Methods inherited from interface java.security.spec.ECField

Field Detail

BINARY_FIELD_OID

CHARACTERISTIC_TWO_GN_BASIS_OID

CHARACTERISTIC_TWO_TP_BASIS_OID

CHARACTERISTIC_TWO_PP_BASIS_OID

Method Detail

negate

negateOutOfPlace

add

addOutOfPlace

add

subtract

subtractOutOfPlace

invert

invertElements

divide

multiply

multiplyOutOfPlace

multiply

multiplyOutOfPlace

multiply

multiplyOutOfPlace

square

squareOutOfPlace

getExtendedPrecomputationData

getPrecomputationData

squareRoot

exponentiate

exponentiate

exponentiateByPowerOf2

newElement

newElement

toElement

getOne

getZero

getGenerator

getTraceOneElement

getTrace

getCardinality

getFieldType

getBaseField

solveEquation

solveEquation

toByteArray

toASN1Object

toString

equals

hashCode