com.google.crypto.tink.subtle

Class EllipticCurves

java.lang.Object

com.google.crypto.tink.subtle.EllipticCurves

public final class EllipticCurves
extends Object

Utility functions and enums for elliptic curve crypto, used in ECDSA and ECDH.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EllipticCurves.CurveType Elliptic curve types.
static class	EllipticCurves.EcdsaEncoding Ecdsa signature encoding.
static class	EllipticCurves.PointFormatType Point formats.

Method Summary

Modifier and Type	Method and Description
static byte[]	computeSharedSecret(ECPrivateKey myPrivateKey, ECPoint publicPoint) Generates the DH shared secret using myPrivateKey and publicPoint
static byte[]	computeSharedSecret(ECPrivateKey myPrivateKey, ECPublicKey peerPublicKey)
static byte[]	ecdsaDer2Ieee(byte[] der, int ieeeLength) Transforms ECDSA DER signature encoding to IEEE_P1363 encoding.
static byte[]	ecdsaIeee2Der(byte[] ieee) Transforms ECDSA IEEE_P1363 signature encoding to DER encoding.
static ECPoint	ecPointDecode(EllipticCurve curve, EllipticCurves.PointFormatType format, byte[] encoded) Decodes an encoded point on an elliptic curve.
static int	encodingSizeInBytes(EllipticCurve curve, EllipticCurves.PointFormatType format) Returns the encoding size of a point on an elliptic curve.
static int	fieldSizeInBits(EllipticCurve curve) Returns the size of an element of the field over which the curve is defined.
static int	fieldSizeInBytes(EllipticCurve curve) Returns the size of an element of the field over which the curve is defined.
static KeyPair	generateKeyPair(ECParameterSpec spec) Generates a new key pair for spec.
static KeyPair	generateKeyPair(EllipticCurves.CurveType curve) Generates a new key pair for curve.
static ECParameterSpec	getCurveSpec(EllipticCurves.CurveType curve) Returns the ECParameterSpec for a named curve.
static ECPrivateKey	getEcPrivateKey(byte[] pkcs8PrivateKey) Returns an ECPrivateKey from pkcs8PrivateKey which is an encoding of a private key, encoded according to the ASN.1 type SubjectPublicKeyInfo.
static ECPrivateKey	getEcPrivateKey(EllipticCurves.CurveType curve, byte[] keyValue) Returns an ECPrivateKey from curve type and keyValue.
static ECPublicKey	getEcPublicKey(byte[] x509PublicKey) Returns an ECPublicKey from x509PublicKey which is an encoding of a public key, encoded according to the ASN.1 type SubjectPublicKeyInfo.
static ECPublicKey	getEcPublicKey(ECParameterSpec spec, EllipticCurves.PointFormatType pointFormat, byte[] publicKey) Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.
static ECPublicKey	getEcPublicKey(EllipticCurves.CurveType curve, byte[] x, byte[] y) Returns an ECPublicKey from curve type and x and y coordinates.
static ECPublicKey	getEcPublicKey(EllipticCurves.CurveType curve, EllipticCurves.PointFormatType pointFormat, byte[] publicKey) Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.
static BigInteger	getModulus(EllipticCurve curve) Returns the modulus of the field used by the curve specified in ecParams.
static ECParameterSpec	getNistP256Params()
static ECParameterSpec	getNistP384Params()
static ECParameterSpec	getNistP521Params()
static BigInteger	getY(BigInteger x, boolean lsb, EllipticCurve curve) Computes the y coordinate of a point on an elliptic curve.
static boolean	isNistEcParameterSpec(ECParameterSpec spec) Returns whether spec is a ECParameterSpec of one of the NIST curves.
static boolean	isSameEcParameterSpec(ECParameterSpec one, ECParameterSpec two) Returns whether one is the same ECParameterSpec as two.
static boolean	isValidDerEncoding(byte[] sig)
protected static BigInteger	modSqrt(BigInteger x, BigInteger p) Computes a square root modulo an odd prime.
static ECPoint	pointDecode(EllipticCurve curve, EllipticCurves.PointFormatType format, byte[] encoded) Decodes an encoded point on an elliptic curve.
static ECPoint	pointDecode(EllipticCurves.CurveType curveType, EllipticCurves.PointFormatType format, byte[] encoded) Decodes an encoded point on an elliptic curve.
static byte[]	pointEncode(EllipticCurve curve, EllipticCurves.PointFormatType format, ECPoint point) Encodes a point on an elliptic curve.
static byte[]	pointEncode(EllipticCurves.CurveType curveType, EllipticCurves.PointFormatType format, ECPoint point) Encodes a point on an elliptic curve.
static void	validatePublicKey(ECPublicKey publicKey, ECPrivateKey privateKey) Checks that the public key's params is the same as the private key's params, and the public key is a valid point on the private key's curve.

Methods inherited from class java.lang.Object

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

Method Detail

getNistP256Params

public static ECParameterSpec getNistP256Params()

getNistP384Params

public static ECParameterSpec getNistP384Params()

getNistP521Params

public static ECParameterSpec getNistP521Params()

isNistEcParameterSpec

public static boolean isNistEcParameterSpec(ECParameterSpec spec)

Returns whether spec is a ECParameterSpec of one of the NIST curves.

isSameEcParameterSpec

public static boolean isSameEcParameterSpec(ECParameterSpec one,
                                            ECParameterSpec two)

Returns whether one is the same ECParameterSpec as two.

validatePublicKey

public static void validatePublicKey(ECPublicKey publicKey,
                                     ECPrivateKey privateKey)
                              throws GeneralSecurityException

Checks that the public key's params is the same as the private key's params, and the public key is a valid point on the private key's curve.

Throws:

GeneralSecurityException

Since:

1.1.0

getModulus

public static BigInteger getModulus(EllipticCurve curve)
                             throws GeneralSecurityException

Returns the modulus of the field used by the curve specified in ecParams.

Parameters:

curve - must be a prime order elliptic curve

Returns:

the order of the finite field over which curve is defined.

Throws:

GeneralSecurityException

fieldSizeInBits

public static int fieldSizeInBits(EllipticCurve curve)
                           throws GeneralSecurityException

Returns the size of an element of the field over which the curve is defined.

Parameters:

curve - must be a prime order elliptic curve

Returns:

the size of an element in bits

Throws:

GeneralSecurityException

fieldSizeInBytes

public static int fieldSizeInBytes(EllipticCurve curve)
                            throws GeneralSecurityException

Returns the size of an element of the field over which the curve is defined.

Parameters:

curve - must be a prime order elliptic curve

Returns:

the size of an element in bytes.

Throws:

GeneralSecurityException

modSqrt

protected static BigInteger modSqrt(BigInteger x,
                                    BigInteger p)
                             throws GeneralSecurityException

Computes a square root modulo an odd prime. Timing and exceptions can leak information about the inputs. Therefore this method must only be used to decompress public keys.

Parameters:

x - the square

p - the prime modulus (the behaviour of the method is undefined if p is not prime).

Returns:

a value s such that s^2 mod p == x mod p

Throws:

GeneralSecurityException - if the square root could not be found.

getY

public static BigInteger getY(BigInteger x,
                              boolean lsb,
                              EllipticCurve curve)
                       throws GeneralSecurityException

Computes the y coordinate of a point on an elliptic curve. This method can be used to decompress elliptic curve points.

Parameters:

x - the x-coordinate of the point

lsb - the least significant bit of the y-coordinate of the point.

curve - this must be an elliptic curve over a prime field using Weierstrass representation.

Returns:

the y coordinate.

Throws:

GeneralSecurityException - if there is no point with coordinate x on the curve, or if curve is not supported.

ecdsaIeee2Der

public static byte[] ecdsaIeee2Der(byte[] ieee)
                            throws GeneralSecurityException

Transforms ECDSA IEEE_P1363 signature encoding to DER encoding.

The IEEE_P1363 signature's format is r || s, where r and s are zero-padded and have the same size in bytes as the order of the curve. For example, for NIST P-256 curve, r and s are zero-padded to 32 bytes.

The DER signature is encoded using ASN.1 (https://tools.ietf.org/html/rfc5480#appendix-A): ECDSA-Sig-Value :: = SEQUENCE { r INTEGER, s INTEGER }. In particular, the encoding is: 0x30 || totalLength || 0x02 || r's length || r || 0x02 || s's length || s.

Parameters:

ieee - ECDSA's signature in IEEE_P1363 format.

Returns:

ECDSA's signature in DER format.

Throws:

GeneralSecurityException - if ieee's length is zero, greater than 132-byte (corresponding to NIST P521) or not divisible by 2.

ecdsaDer2Ieee

public static byte[] ecdsaDer2Ieee(byte[] der,
                                   int ieeeLength)
                            throws GeneralSecurityException

Transforms ECDSA DER signature encoding to IEEE_P1363 encoding.

The IEEE_P1363 signature's format is r || s, where r and s are zero-padded and have the same size in bytes as the order of the curve. For example, for NIST P-256 curve, r and s are zero-padded to 32 bytes.

The DER signature is encoded using ASN.1 (https://tools.ietf.org/html/rfc5480#appendix-A): ECDSA-Sig-Value :: = SEQUENCE { r INTEGER, s INTEGER }. In particular, the encoding is: 0x30 || totalLength || 0x02 || r's length || r || 0x02 || s's length || s.

Parameters:

der - ECDSA's signature in DER encoding.

ieeeLength - length of ECDSA signature's in IEEE_P1363's format which equals to 2 * (size of elliptic curve's field in bytes).

Returns:

ECDSA's signature in IEEE_P1363 format.

Throws:

GeneralSecurityException - if the signature is not valid DER encoding.

isValidDerEncoding

public static boolean isValidDerEncoding(byte[] sig)

encodingSizeInBytes

public static int encodingSizeInBytes(EllipticCurve curve,
                                      EllipticCurves.PointFormatType format)
                               throws GeneralSecurityException

Returns the encoding size of a point on an elliptic curve.

Parameters:

curve - the elliptic curve

format - the format used to encode the point

Returns:

the size of an encoded point in bytes

Throws:

GeneralSecurityException - if the point format is unknown or if the elliptic curve is not supported

ecPointDecode

public static ECPoint ecPointDecode(EllipticCurve curve,
                                    EllipticCurves.PointFormatType format,
                                    byte[] encoded)
                             throws GeneralSecurityException

Decodes an encoded point on an elliptic curve. This method checks that the encoded point is on the curve.

Parameters:

curve - the elliptic curve

format - the format used to enocde the point

encoded - the encoded point

Returns:

the point

Throws:

GeneralSecurityException - if the encoded point is invalid or if the curve or format are not supported.

pointDecode

public static ECPoint pointDecode(EllipticCurves.CurveType curveType,
                                  EllipticCurves.PointFormatType format,
                                  byte[] encoded)
                           throws GeneralSecurityException

Decodes an encoded point on an elliptic curve. This method checks that the encoded point is on the curve.

Parameters:

curve - the elliptic curve

format - the format used to enocde the point

encoded - the encoded point

Returns:

the point

Throws:

GeneralSecurityException - if the encoded point is invalid or if the curve or format are not supported.

Since:

1.1.0

pointDecode

public static ECPoint pointDecode(EllipticCurve curve,
                                  EllipticCurves.PointFormatType format,
                                  byte[] encoded)
                           throws GeneralSecurityException

Decodes an encoded point on an elliptic curve. This method checks that the encoded point is on the curve.

Parameters:

curve - the elliptic curve

format - the format used to enocde the point

encoded - the encoded point

Returns:

the point

Throws:

GeneralSecurityException - if the encoded point is invalid or if the curve or format are not supported.

Since:

1.1.0

pointEncode

public static byte[] pointEncode(EllipticCurves.CurveType curveType,
                                 EllipticCurves.PointFormatType format,
                                 ECPoint point)
                          throws GeneralSecurityException

Encodes a point on an elliptic curve.

Parameters:

curve - the elliptic curve

format - the format for the encoding

point - the point to encode

Returns:

the encoded key exchange

Throws:

GeneralSecurityException - if the point is not on the curve or if the format is not supported.

Since:

1.1.0

pointEncode

public static byte[] pointEncode(EllipticCurve curve,
                                 EllipticCurves.PointFormatType format,
                                 ECPoint point)
                          throws GeneralSecurityException

Encodes a point on an elliptic curve.

Parameters:

curve - the elliptic curve

format - the format for the encoding

point - the point to encode

Returns:

the encoded key exchange

Throws:

GeneralSecurityException - if the point is not on the curve or if the format is not supported.

Since:

1.1.0

getCurveSpec

public static ECParameterSpec getCurveSpec(EllipticCurves.CurveType curve)
                                    throws NoSuchAlgorithmException

Returns the ECParameterSpec for a named curve.

Parameters:

curve - the curve type

Returns:

the ECParameterSpec for the curve.

Throws:

NoSuchAlgorithmException

getEcPublicKey

public static ECPublicKey getEcPublicKey(byte[] x509PublicKey)
                                  throws GeneralSecurityException

Returns an ECPublicKey from x509PublicKey which is an encoding of a public key, encoded according to the ASN.1 type SubjectPublicKeyInfo. TODO(b/68672497): test that in Java one can always get this representation by using {@link ECPublicKey#getEncoded), regardless of the provider.

Throws:

GeneralSecurityException

getEcPublicKey

public static ECPublicKey getEcPublicKey(EllipticCurves.CurveType curve,
                                         EllipticCurves.PointFormatType pointFormat,
                                         byte[] publicKey)
                                  throws GeneralSecurityException

Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.

Throws:

GeneralSecurityException

getEcPublicKey

public static ECPublicKey getEcPublicKey(ECParameterSpec spec,
                                         EllipticCurves.PointFormatType pointFormat,
                                         byte[] publicKey)
                                  throws GeneralSecurityException

Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.

Throws:

GeneralSecurityException

getEcPublicKey

public static ECPublicKey getEcPublicKey(EllipticCurves.CurveType curve,
                                         byte[] x,
                                         byte[] y)
                                  throws GeneralSecurityException

Returns an ECPublicKey from curve type and x and y coordinates.

Throws:

GeneralSecurityException

getEcPrivateKey

public static ECPrivateKey getEcPrivateKey(byte[] pkcs8PrivateKey)
                                    throws GeneralSecurityException

Returns an ECPrivateKey from pkcs8PrivateKey which is an encoding of a private key, encoded according to the ASN.1 type SubjectPublicKeyInfo. TODO(b/68672497): test that in Java one can always get this representation by using {@link ECPrivateKey#getEncoded), regardless of the provider.

Throws:

GeneralSecurityException

getEcPrivateKey

public static ECPrivateKey getEcPrivateKey(EllipticCurves.CurveType curve,
                                           byte[] keyValue)
                                    throws GeneralSecurityException

Returns an ECPrivateKey from curve type and keyValue.

Throws:

GeneralSecurityException

generateKeyPair

public static KeyPair generateKeyPair(EllipticCurves.CurveType curve)
                               throws GeneralSecurityException

Generates a new key pair for curve.

Throws:

GeneralSecurityException

generateKeyPair

public static KeyPair generateKeyPair(ECParameterSpec spec)
                               throws GeneralSecurityException

Generates a new key pair for spec.

Throws:

GeneralSecurityException

computeSharedSecret

public static byte[] computeSharedSecret(ECPrivateKey myPrivateKey,
                                         ECPublicKey peerPublicKey)
                                  throws GeneralSecurityException

Throws:

GeneralSecurityException

computeSharedSecret

public static byte[] computeSharedSecret(ECPrivateKey myPrivateKey,
                                         ECPoint publicPoint)
                                  throws GeneralSecurityException

Generates the DH shared secret using myPrivateKey and publicPoint

Throws:

GeneralSecurityException

Since:

1.1.0