iaik.security.ec.math.curve

Class EllipticCurve

java.lang.Object

iaik.security.ec.math.curve.EllipticCurve

public abstract class EllipticCurve
extends Object

Abstract class that implements the additive group defined over elliptic curves.

It offers the (arithmetical) functionality that is required to perform operations on points of an elliptic curve. The curve-specific code is implemented by subclasses, which are not visible. Use the factories to BinaryWeierstrassCurveFactory to obtain binary Weierstrass-type curves and PrimeWeierstrassCurveFactory to obtain prime Weierstrass-type curves.

The different coordinate systems that are supported are listed in BinaryCurveCoordinateTypes for binary curves and PrimeCurveCoordinateTypes for prime curves.

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.

Author:

Christian Hanser

See Also:

ECPoint, BinaryWeierstrassCurveFactory, PrimeWeierstrassCurveFactory, BinaryCurveCoordinateTypes, PrimeCurveCoordinateTypes

Method Summary

Modifier and Type	Method and Description
abstract ECPoint	addPoint(ECPoint a, ECPoint b) Computes a += b.
boolean	containsPoint(ECPoint p) Returns true, iff p satisfies the curve equation.
ECPoint	decodePoint(byte[] encodedPoint) Decodes an encoded point.
abstract ECPoint	decodePoint(byte[] encodedPoint, int length) Decodes an encoded point.
abstract ECPoint	doublePoint(ECPoint a) Computes a *= 2.
byte[]	encodePoint(ECPoint p) Encodes a point, i.e.
abstract byte[]	encodePoint(ECPoint p, PointEncoders encoder) Encodes a point, i.e.
abstract boolean	equals(Object obj)
GenericField	getField() Returns the underlying finite field of this.
ECPoint	getGenerator() Returns the generator of the elliptic curve (sub-)group.
ECPoint	getNeutralPoint() Returns the curve's neutral element.
BigInteger	getOrder() Returns the curve order of this, i.e.
abstract ECPoint	getPoint(GenericFieldElement x) Returns a point on the curve corresponding to x, if x is a valid x-coordinate.
abstract ECPoint	getPoint(GenericFieldElement x, int yBit) Returns a point on the curve corresponding to x and yBit (which uniquely determines the y-coordinate), if x is a valid x-coordinate.
abstract int	hashCode()
ECPoint	hashToPoint(byte[] message) Hash message to a point on a curve.
ECPoint	hashToPoint(String message) Hash message to a point on a curve.
abstract boolean	isNeutralPoint(ECPoint p) Returns true, iff p is the neutral element.
static boolean	isRegular(Field field, BigInteger a, BigInteger b) Determines whether a curve over field field with parameters a, b is regular.
abstract ECPoint	mixedAddPoint(ECPoint a, ECPoint b) Computes a += b, where b is scaled.
ECPoint	mixedSubtractPoint(ECPoint a, ECPoint b) Computes a -= b, where b is scaled.
ECPoint	multiplyPoint(ECPoint a, BigInteger k) Scalar multiplication of a point and an integer a *= k.
ECPoint	multiplyPrecomputedPoint(BigInteger k) Scalar multiplication of the point a set for precomputation and an integer a *= k using precomputation.
ECPoint	multiplySimultaneously(BigInteger[] scalars, ECPoint[] points) This method multiplies multiple points simultaneously.
ECPoint	multiplySimultaneously(ECPoint a, BigInteger k, ECPoint b, BigInteger l) This method multiplies two points simultaneously.
ECPoint	multiplySimultaneouslyWithPrecomputedPoint(BigInteger k, ECPoint b, BigInteger l) This method multiplies two points simultaneously.
abstract ECPoint	negatePoint(ECPoint a) Negates the specified point on the curve.
ECPoint	newPoint(ECPoint p) Creates an ECPoint from a JDK ECPoint that is associated with this curve.
abstract ECPoint	newPoint(GenericFieldElement x, GenericFieldElement y) Returns a point on the curve corresponding to (x,y), if (x,y) is a point on the curve.
void	precompute(ECPoint a) Computes the precomputation data for point a and stores it internally.
abstract ECPoint	scaledAddPoint(ECPoint a, ECPoint b) Computes a += b, where a and b are both scaled.
abstract ECPoint	scaledDoublePoint(ECPoint a) Computes a *= 2, where a is scaled.
ECPoint	scaledSubtractPoint(ECPoint a, ECPoint b) Computes a -= b, where a and b are both scaled.
abstract ECPoint	scalePoint(ECPoint a) Scales the specified point, i.e.
ECPoint[]	scalePoints(ECPoint[] points) Simultaneously scales the specified points, i.e.
ECPoint	subtractPoint(ECPoint a, ECPoint b) Computes a -= b.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getField

public GenericField getField()

Returns the underlying finite field of this.

Returns:

the finite field

isRegular

public static boolean isRegular(Field field,
                                BigInteger a,
                                BigInteger b)

Determines whether a curve over field field with parameters a, b is regular.

Parameters:

field - the underyling field

a - the first curve coefficient

b - the second curve coefficient

Returns:

true if the curve is regular, false if it is singular

getOrder

public final BigInteger getOrder()

Returns the curve order of this, i.e. the number of points on the elliptic curve including the neutral element.

Returns:

the curve order, or null if unknown

getGenerator

public final ECPoint getGenerator()

Returns the generator of the elliptic curve (sub-)group.

Returns:

a point representing the generator

addPoint

public abstract ECPoint addPoint(ECPoint a,
                                 ECPoint b)

Computes a += b. The points must be elements of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point a, to which b will be added

b - the point b, which is added to a.

Returns:

the sum

mixedAddPoint

public abstract ECPoint mixedAddPoint(ECPoint a,
                                      ECPoint b)

Computes a += b, where b is scaled. The points must be elements of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point a, to which b will be added

b - the point b, which is added to a.

Returns:

this instance holding the result

scaledAddPoint

public abstract ECPoint scaledAddPoint(ECPoint a,
                                       ECPoint b)

Computes a += b, where a and b are both scaled. The points must be elements of the group (must lie on the curve). Subclasses do not need check this.

Parameters:

a - the point a, to which b will be added

b - the point b, which is added to a.

Returns:

this instance holding the result

subtractPoint

public ECPoint subtractPoint(ECPoint a,
                             ECPoint b)

Computes a -= b. The points must be elements of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point a, from which b will be subtracted

b - the point b, which is subtracted from a.

Returns:

this instance holding the result

mixedSubtractPoint

public ECPoint mixedSubtractPoint(ECPoint a,
                                  ECPoint b)

Computes a -= b, where b is scaled. The points must be elements of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point a, from which b will be subtracted

b - the point b, which is subtracted from a.

Returns:

the difference

scaledSubtractPoint

public ECPoint scaledSubtractPoint(ECPoint a,
                                   ECPoint b)

Computes a -= b, where a and b are both scaled. The points must be elements of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point a, from which b will be subtracted

b - the point b, which is subtracted from a.

Returns:

the difference

doublePoint

public abstract ECPoint doublePoint(ECPoint a)

Computes a *= 2. The point must be an element of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point on this curve

Returns:

the double

scaledDoublePoint

public abstract ECPoint scaledDoublePoint(ECPoint a)

Computes a *= 2, where a is scaled. The point must be element of the group (must lie on the curve). Subclasses do not need to check this.

Parameters:

a - the point on this curve

Returns:

this instance holding the result

negatePoint

public abstract ECPoint negatePoint(ECPoint a)

Negates the specified point on the curve.

Parameters:

a - the point to be inverted.

Returns:

the inverse

scalePoint

public abstract ECPoint scalePoint(ECPoint a)

Scales the specified point, i.e. returns the according point with Z=1.

Parameters:

a - the point to be scaled.

Returns:

the scaled point

scalePoints

public ECPoint[] scalePoints(ECPoint[] points)

Simultaneously scales the specified points, i.e. returns the according points with Z=1. Note: this operation is beneficial as it makes use of simultaneous inversion.

Parameters:

points - the points to be scaled.

Returns:

an array holding the scaled points

multiplyPoint

public ECPoint multiplyPoint(ECPoint a,
                             BigInteger k)

Scalar multiplication of a point and an integer a *= k. It is assumed that k is a scalar modulo the order of the curve group.

Parameters:

a - the point and result

k - the factor

Returns:

the multiple of a

precompute

public void precompute(ECPoint a)

Computes the precomputation data for point a and stores it internally.

Parameters:

a - the point a

multiplyPrecomputedPoint

public ECPoint multiplyPrecomputedPoint(BigInteger k)

Scalar multiplication of the point a set for precomputation and an integer a *= k using precomputation. It is assumed that k is a scalar modulo the order of the curve group.

Parameters:

k - the factor

Returns:

the multiple of a

multiplySimultaneouslyWithPrecomputedPoint

public ECPoint multiplySimultaneouslyWithPrecomputedPoint(BigInteger k,
                                                          ECPoint b,
                                                          BigInteger l)

This method multiplies two points simultaneously. This means it computes k * a + l * b, where a has been used with precompute(ECPoint) before. It is assumed that k, l are scalars modulo the order of the curve group.

Parameters:

k - the first scalar

b - the second point

l - the second scalar

Returns:

a point representing k * a + l * b

multiplySimultaneously

public ECPoint multiplySimultaneously(ECPoint a,
                                      BigInteger k,
                                      ECPoint b,
                                      BigInteger l)

This method multiplies two points simultaneously. This means it computes k * a + l * b. It is assumed that k, l are scalars modulo the order of the curve group.

Parameters:

a - the first point

k - the first scalar

b - the second point

l - the second scalar

Returns:

a point representing k * a + l * b

multiplySimultaneously

public ECPoint multiplySimultaneously(BigInteger[] scalars,
                                      ECPoint[] points)

This method multiplies multiple points simultaneously. This means it computes k_1 * a_1 + k_2 * a_2 + ... + k_n * a_n. It is assumed that k_1, ..., k_n are scalars modulo the order of the curve group.

Parameters:

scalars - the scalars k_i

points - the points a_i

Returns:

a point representing k_1 * a_1 + k_2 * a_2 + ... + k_n * a_n

getNeutralPoint

public final ECPoint getNeutralPoint()

Returns the curve's neutral element.

Returns:

the neutral element

isNeutralPoint

public abstract boolean isNeutralPoint(ECPoint p)

Returns true, iff p is the neutral element.

Parameters:

p - a point on the curve

Returns:

true, iff p is the neutral element

containsPoint

public final boolean containsPoint(ECPoint p)

Returns true, iff p satisfies the curve equation.

Parameters:

p - the JDK ECPoint

Returns:

true, iff p satisfies the curve equation

newPoint

public final ECPoint newPoint(ECPoint p)

Creates an ECPoint from a JDK ECPoint that is associated with this curve.

Parameters:

p - the JDK ECPoint

Returns:

an ECPoint on this curve

newPoint

public abstract ECPoint newPoint(GenericFieldElement x,
                                 GenericFieldElement y)

Returns a point on the curve corresponding to (x,y), if (x,y) is a point on the curve.

Parameters:

x - the x-coordinate

y - the y-coordinate

Returns:

either null if x is not a valid x-coordinate, or a point corresponding to x and y.

encodePoint

public abstract byte[] encodePoint(ECPoint p,
                                   PointEncoders encoder)

Encodes a point, i.e. converts it to a byte[]. The user can choose between point compression and non-compressed encoding.

Parameters:

p - the point to be encoded

encoder - the point encoding algorithm to be used

Returns:

a byte[] holding the encoded point

encodePoint

public byte[] encodePoint(ECPoint p)

Encodes a point, i.e. converts it to a byte[]. The user can choose between point compression and non-compressed encoding.

Parameters:

p - the point to be encoded

Returns:

a byte[] holding the encoded point

decodePoint

public abstract ECPoint decodePoint(byte[] encodedPoint,
                                    int length)
                             throws DecodingException

Decodes an encoded point.

Parameters:

encodedPoint - the octet string to be converted into a point (either compressed or uncompressed), including the PC byte.

length - the length of the sub-array to be considered

Returns:

the decoded point

Throws:

DecodingException - if the point could not be decoded

decodePoint

public ECPoint decodePoint(byte[] encodedPoint)
                    throws DecodingException

Decodes an encoded point.

Parameters:

encodedPoint - the octet string to be converted into a point (either compressed or uncompressed), including the PC byte.

Returns:

the decoded point

Throws:

DecodingException - if the point could not be decoded

getPoint

public abstract ECPoint getPoint(GenericFieldElement x)

Returns a point on the curve corresponding to x, if x is a valid x-coordinate.

Parameters:

x - the x-coordinate

Returns:

either null if x is not a valid x-coordinate, or a point corresponding to x.

getPoint

public abstract ECPoint getPoint(GenericFieldElement x,
                                 int yBit)

Returns a point on the curve corresponding to x and yBit (which uniquely determines the y-coordinate), if x is a valid x-coordinate.

Parameters:

x - the x-coordinate

yBit - determines which y-coordinate will be chosen

Returns:

either null if x is not a valid x-coordinate, or a point corresponding to x.

hashToPoint

public final ECPoint hashToPoint(byte[] message)
                          throws UnsupportedOperationException

Hash message to a point on a curve.

Parameters:

message - message to hash

Returns:

instance of the hashed point or null if no hasher is available

Throws:

UnsupportedOperationException - if hashing to this curve is not supported.

hashToPoint

public final ECPoint hashToPoint(String message)
                          throws UnsupportedOperationException

Hash message to a point on a curve. This is the same as first applying Util.toByteArray(String) on the message and then calling {hashToPoint(byte[]).

Parameters:

message - message to hash

Returns:

instance of the hashed point or null if no hasher is available

Throws:

UnsupportedOperationException - if hashing to this curve is not supported.

See Also:

Util.toByteArray(String), hashToPoint(byte[])

equals

public abstract boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public abstract int hashCode()

Overrides:

hashCode in class Object