iaik.security.ec.common

Class EllipticCurve

java.lang.Object

java.security.spec.EllipticCurve

iaik.security.ec.common.EllipticCurve

All Implemented Interfaces:

Cloneable

public final class EllipticCurve
extends EllipticCurve
implements Cloneable

This class implements an elliptic curve (EC) and its arithmetic necessary for elliptic curve cryptography, i.e. for algorithms such as ECDSA and ECDH. Internally it uses another object of type EllipticCurve. Take a look at the latter for a comprehensive support of EC arithmetic.

Either use one of the getCurve(java.security.spec.EllipticCurve), getCurve(java.security.spec.EllipticCurve, AlgorithmID), getCurve(Field, BigInteger, BigInteger, BigInteger), getCurve(Field, BigInteger, BigInteger, BigInteger, byte[]), and getCurve(Field, BigInteger, BigInteger, BigInteger, MessageDigest, byte[]) methods to obtain a custom elliptic curve object or ECStandardizedParameterFactory in order to obtain standardized curves.

References:

[1] ANSI X9.62-2005, "American National Standard for Financial Services - The Elliptic Curve Digital Signature Algorithm (ECDSA)", ASC X9, November 2005.

Author:

Christian Hanser, Sebastian Ramacher

See Also:

ECStandardizedParameterFactory

Method Summary

Modifier and Type	Method and Description
ECPoint	addPoint(ECPoint p, ECPoint q) Adds two points.
EllipticCurve	clone()
boolean	containsPoint(ECPoint p) Returns true, iff p satisfies the curve equation.
ECPoint	decodePoint(byte[] encodedPoint) Decodes an encoded point.
ECPoint	decodePoint(byte[] encodedPoint, int length) Decodes an encoded point.
byte[]	encodePoint(ECPoint p) Encodes a point, i.e.
byte[]	encodePoint(ECPoint p, PointEncoders encoder) Encodes a point, i.e.
boolean	equals(Object obj)
static EllipticCurve	getCurve(EllipticCurve curve) Constructs a new wrapped curve from a JDK curve.
static EllipticCurve	getCurve(EllipticCurve curve, iaik.asn1.structures.AlgorithmID hashAlgorithm) Constructs a new wrapped curve from a JDK curve.
static EllipticCurve	getCurve(Field field, BigInteger a, BigInteger b, BigInteger order) Constructs a new curve.
static EllipticCurve	getCurve(Field field, BigInteger a, BigInteger b, BigInteger order, byte[] seed) Constructs a new curve.
static EllipticCurve	getCurve(Field field, BigInteger a, BigInteger b, BigInteger order, MessageDigest md, byte[] seed) Constructs a new curve.
CurveTypes	getCurveType() Return the curve type of the curve, i.e.
Field	getField()
EllipticCurve	getIAIKCurve() Returns the internally used elliptic curve implementation.
int	hashCode()
ECPoint	multiplyGenerator(BigInteger n) Performs the scalar multiplication n * g, where g is the generator of the curve group.
ECPoint	multiplyPoint(ECPoint p, BigInteger n) Performs the scalar multiplication n * p employing precomputation.
ECPoint	multiplyPointSimultaneouslyWithGenerator(BigInteger k, ECPoint q, BigInteger l) Performs the simultaneous scalar multiplication k * g + l * q, where g is the generator.
ECPoint	negatePoint(ECPoint p) Negates a point.
ECPoint	secureMultiplyGenerator(BigInteger n) Securely performs the scalar multiplication n * g by using blinding, where g is the generator of the curve group.
ECPoint	secureMultiplyGenerator(BigInteger n, SecureRandom random) Securely performs the scalar multiplication n * g by using blinding, where g is the generator of the curve group.
ECPoint	secureMultiplyPoint(ECPoint p, BigInteger n) Performs the scalar multiplication n * p employing precomputation and blinding of n.
ECPoint	secureMultiplyPoint(ECPoint p, BigInteger n, SecureRandom random) Performs the scalar multiplication n * p employing precomputation and blinding of n.
void	setGenerator(ECPoint g) Sets the curve's generator and performs precomputation to speed up scalar multiplications that involve the generator.
ECPoint	subtractPoint(ECPoint p, ECPoint q) Subtracts two points.
iaik.asn1.SEQUENCE	toASN1Object() Converts a curve to the following ASN.1 structure: Curve ::= SEQUENCE { a FieldElement, -- Elliptic curve coefficient a b FieldElement, -- Elliptic curve coefficient b seed BIT STRING OPTIONAL -- The seed that was used to generate this curve }
iaik.asn1.OCTET_STRING	toASN1Object(ECPoint p) The ASN.1 representation of the given point p as defined in [1].
ECPoint	toIAIKECPoint(ECPoint p) Converts a JDK ECPoint object into an IAIK ECPoint.
String	toString() Returns a String representation of this curve.

Methods inherited from class java.security.spec.EllipticCurve

getA, getB, getSeed

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getCurve

public static EllipticCurve getCurve(EllipticCurve curve)
                              throws InvalidCurveException

Constructs a new wrapped curve from a JDK curve.

Parameters:

curve - a JDK elliptic curve

Returns:

an EllipticCurve instance

Throws:

InvalidCurveException - in case that the curve validation failed

getCurve

public static EllipticCurve getCurve(EllipticCurve curve,
                                     iaik.asn1.structures.AlgorithmID hashAlgorithm)
                              throws InvalidCurveException

Constructs a new wrapped curve from a JDK curve.

Parameters:

curve - a JDK elliptic curve

hashAlgorithm - the approved hash algorithm that was used to generate the curve; if it is null, but the seed is given, then SHA-1 will be used to validate the curve

Returns:

an EllipticCurve instance

Throws:

InvalidCurveException - in case that the curve validation failed

getCurve

public static EllipticCurve getCurve(Field field,
                                     BigInteger a,
                                     BigInteger b,
                                     BigInteger order,
                                     MessageDigest md,
                                     byte[] seed)
                              throws InvalidCurveException

Constructs a new curve.

Parameters:

field - the underlying binary field

a - a positive value representing the curve parameter a

b - a positive value representing the curve parameter b

order - the order of the associated curve group

md - the approved hash algorithm that was used to generate the curve; if it is null, but the seed is given, then SHA-1 will be used to validate the curve

seed - the seed that was used to generate this curve

Returns:

an EllipticCurve instance

Throws:

InvalidCurveException - in case that the curve validation failed

getCurve

public static EllipticCurve getCurve(Field field,
                                     BigInteger a,
                                     BigInteger b,
                                     BigInteger order,
                                     byte[] seed)
                              throws InvalidCurveException

Constructs a new curve. Note: SHA-1 will be used to validate the curve.

Parameters:

field - the underlying binary field

a - a positive value representing the curve parameter a

b - a positive value representing the curve parameter b

order - the order of the associated curve group

seed - the seed that was used to generate this curve

Returns:

an EllipticCurve instance

Throws:

InvalidCurveException - in case that the curve validation failed

getCurve

public static EllipticCurve getCurve(Field field,
                                     BigInteger a,
                                     BigInteger b,
                                     BigInteger order)
                              throws InvalidCurveException

Constructs a new curve.

Parameters:

field - the underlying binary field

a - a positive value representing the curve parameter a

b - a positive value representing the curve parameter b

order - the order of the associated curve group

Returns:

an EllipticCurve instance

Throws:

InvalidCurveException - in case that the curve validation failed

getIAIKCurve

public EllipticCurve getIAIKCurve()

Returns the internally used elliptic curve implementation.

Returns:

the corresponding IAIK elliptic curve

multiplyPoint

public ECPoint multiplyPoint(ECPoint p,
                             BigInteger n)

Performs the scalar multiplication n * p employing precomputation.

Parameters:

p - a point on the curve

n - the scalar

Returns:

the multiple of p

secureMultiplyPoint

public ECPoint secureMultiplyPoint(ECPoint p,
                                   BigInteger n)

Performs the scalar multiplication n * p employing precomputation and blinding of n.

Parameters:

p - a point on the curve

n - the scalar

Returns:

the multiple of p

secureMultiplyPoint

public ECPoint secureMultiplyPoint(ECPoint p,
                                   BigInteger n,
                                   SecureRandom random)

Performs the scalar multiplication n * p employing precomputation and blinding of n.

Parameters:

p - a point on the curve

n - the scalar

random - a SecureRandom instance

Returns:

the multiple of p

addPoint

public ECPoint addPoint(ECPoint p,
                        ECPoint q)

Adds two points.

Parameters:

p - a point on the curve

q - a second point on the curve

Returns:

the sum of p and q

subtractPoint

public ECPoint subtractPoint(ECPoint p,
                             ECPoint q)

Subtracts two points.

Parameters:

p - a point on the curve

q - a second point on the curve

Returns:

the difference of p and q

negatePoint

public ECPoint negatePoint(ECPoint p)

Negates a point.

Parameters:

p - a point on the curve

Returns:

the negative of p

setGenerator

public void setGenerator(ECPoint g)

Sets the curve's generator and performs precomputation to speed up scalar multiplications that involve the generator.

Parameters:

g - the generator of the curve group

multiplyGenerator

public ECPoint multiplyGenerator(BigInteger n)

Performs the scalar multiplication n * g, where g is the generator of the curve group. Note a generator must be set previous to calling this method using setGenerator(ECPoint).

Parameters:

n - the scalar

Returns:

the multiple of g

secureMultiplyGenerator

public ECPoint secureMultiplyGenerator(BigInteger n)

Securely performs the scalar multiplication n * g by using blinding, where g is the generator of the curve group. Note a generator must be set previous to calling this method using setGenerator(ECPoint).

Parameters:

n - the scalar

Returns:

the multiple of g

secureMultiplyGenerator

public ECPoint secureMultiplyGenerator(BigInteger n,
                                       SecureRandom random)

Securely performs the scalar multiplication n * g by using blinding, where g is the generator of the curve group. Note a generator must be set previous to calling this method using setGenerator(ECPoint).

Parameters:

n - the scalar

random - a SecureRandom instance

Returns:

the multiple of g

multiplyPointSimultaneouslyWithGenerator

public ECPoint multiplyPointSimultaneouslyWithGenerator(BigInteger k,
                                                        ECPoint q,
                                                        BigInteger l)

Performs the simultaneous scalar multiplication k * g + l * q, where g is the generator. Note a generator must be set previous to calling this method using setGenerator(ECPoint).

Parameters:

k - the first scalar

q - the second point on the curve

l - the second scalar

Returns:

the multiple of g

getField

public Field getField()

Overrides:

getField in class EllipticCurve

containsPoint

public boolean containsPoint(ECPoint p)

Returns true, iff p satisfies the curve equation.

Parameters:

p - the ECPoint

Returns:

true, iff p satisfies the curve equation

encodePoint

public byte[] encodePoint(ECPoint p)

Encodes a point, i.e. converts it to a byte[], using the default encoding algorithm.

Parameters:

p - the point to be encoded

Returns:

a byte[] representing the encoded point

See Also:

PointEncoders.getDefaultPointEncoder(), PointEncoders.setDefaultPointEncoder(iaik.security.ec.common.PointEncoders)

encodePoint

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

Encodes a point, i.e. converts it to a byte[], using the default encoding algorithm.

Parameters:

p - the point to be encoded

encoder - the point encoding algorithm to be used

Returns:

a byte[] representing the encoded point

See Also:

PointEncoders.getDefaultPointEncoder(), PointEncoders.setDefaultPointEncoder(iaik.security.ec.common.PointEncoders)

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 encodedPoint could not be decoded

decodePoint

public 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 encodedPoint could not be decoded

toIAIKECPoint

public ECPoint toIAIKECPoint(ECPoint p)

Converts a JDK ECPoint object into an IAIK ECPoint.

Parameters:

p - the JDK ECPoint

Returns:

an IAIK ECPoint

toASN1Object

public iaik.asn1.SEQUENCE toASN1Object()

Converts a curve to the following ASN.1 structure: Curve ::= SEQUENCE { a FieldElement, -- Elliptic curve coefficient a b FieldElement, -- Elliptic curve coefficient b seed BIT STRING OPTIONAL -- The seed that was used to generate this curve }

Returns:

the ASN.1 structure.

toASN1Object

public iaik.asn1.OCTET_STRING toASN1Object(ECPoint p)

The ASN.1 representation of the given point p as defined in [1].

Parameters:

p - the point to be ASN.1 encoded

Returns:

the octet string ASN.1 object.

getCurveType

public CurveTypes getCurveType()

Return the curve type of the curve, i.e. whether it is a curve in short Weierstrass form or a twisted Edwards curve.

Returns:

the curve type

toString

public String toString()

Returns a String representation of this curve.

Overrides:

toString in class Object

Returns:

a String describing this curve

equals

public boolean equals(Object obj)

Overrides:

equals in class EllipticCurve

hashCode

public int hashCode()

Overrides:

hashCode in class EllipticCurve

clone

public EllipticCurve clone()

Overrides:

clone in class Object