Package com.google.crypto.tink.subtle

Class EllipticCurves

  • public final class EllipticCurves
extends java.lang.Object
    Utility functions and enums for elliptic curve crypto, used in ECDSA and ECDH.
    Since:
    1.0.0

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static byte[] computeSharedSecret​(java.security.interfaces.ECPrivateKey myPrivateKey, java.security.interfaces.ECPublicKey peerPublicKey)
      Generates the DH shared secret using myPrivateKey and peerPublicKey
      static byte[] computeSharedSecret​(java.security.interfaces.ECPrivateKey myPrivateKey, java.security.spec.ECPoint publicPoint)
      Generates the DH shared secret using myPrivateKey and publicPoint
      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 java.security.spec.ECPoint ecPointDecode​(java.security.spec.EllipticCurve curve, EllipticCurves.PointFormatType format, byte[] encoded)
      Decodes an encoded point on an elliptic curve.
      static int encodingSizeInBytes​(java.security.spec.EllipticCurve curve, EllipticCurves.PointFormatType format)
      Returns the encoding size of a point on an elliptic curve.
      static int fieldSizeInBits​(java.security.spec.EllipticCurve curve)
      Returns the size of an element of the field over which the curve is defined.
      static int fieldSizeInBytes​(java.security.spec.EllipticCurve curve)
      Returns the size of an element of the field over which the curve is defined.
      static java.security.KeyPair generateKeyPair​(EllipticCurves.CurveType curve)
      Generates a new key pair for curve.
      static java.security.KeyPair generateKeyPair​(java.security.spec.ECParameterSpec spec)
      Generates a new key pair for spec.
      static java.security.spec.ECParameterSpec getCurveSpec​(EllipticCurves.CurveType curve)
      Returns the ECParameterSpec for a named curve.
      static java.security.interfaces.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 java.security.interfaces.ECPrivateKey getEcPrivateKey​(EllipticCurves.CurveType curve, byte[] keyValue)
      Returns an ECPrivateKey from curve type and keyValue.
      static java.security.interfaces.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 java.security.interfaces.ECPublicKey getEcPublicKey​(EllipticCurves.CurveType curve, byte[] x, byte[] y)
      Returns an ECPublicKey from curve type and x and y coordinates.
      static java.security.interfaces.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 java.security.interfaces.ECPublicKey getEcPublicKey​(java.security.spec.ECParameterSpec spec, EllipticCurves.PointFormatType pointFormat, byte[] publicKey)
      Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.
      static java.math.BigInteger getModulus​(java.security.spec.EllipticCurve curve)
      Returns the modulus of the field used by the curve specified in ecParams.
      static java.security.spec.ECParameterSpec getNistP256Params()  
      static java.security.spec.ECParameterSpec getNistP384Params()  
      static java.security.spec.ECParameterSpec getNistP521Params()  
      static java.math.BigInteger getY​(java.math.BigInteger x, boolean lsb, java.security.spec.EllipticCurve curve)
      Deprecated.
      This shouldn't be used directly, use pointDecode(com.google.crypto.tink.subtle.EllipticCurves.CurveType,com.google.crypto.tink.subtle.EllipticCurves.PointFormatType,byte[]) to decompress points.
      static boolean isNistEcParameterSpec​(java.security.spec.ECParameterSpec spec)
      Returns whether spec is a ECParameterSpec of one of the NIST curves.
      static boolean isSameEcParameterSpec​(java.security.spec.ECParameterSpec one, java.security.spec.ECParameterSpec two)
      Returns whether one is the same ECParameterSpec as two.
      static boolean isValidDerEncoding​(byte[] sig)  
      static java.security.spec.ECPoint pointDecode​(EllipticCurves.CurveType curveType, EllipticCurves.PointFormatType format, byte[] encoded)
      Decodes an encoded point on an elliptic curve.
      static java.security.spec.ECPoint pointDecode​(java.security.spec.EllipticCurve curve, EllipticCurves.PointFormatType format, byte[] encoded)
      Decodes an encoded point on an elliptic curve.
      static byte[] pointEncode​(EllipticCurves.CurveType curveType, EllipticCurves.PointFormatType format, java.security.spec.ECPoint point)
      Encodes a point on an elliptic curve.
      static byte[] pointEncode​(java.security.spec.EllipticCurve curve, EllipticCurves.PointFormatType format, java.security.spec.ECPoint point)
      Encodes a point on an elliptic curve.
      static void validatePublicKey​(java.security.interfaces.ECPublicKey publicKey, java.security.interfaces.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 java.security.spec.ECParameterSpec getNistP256Params()

      • getNistP384Params

        public static java.security.spec.ECParameterSpec getNistP384Params()

      • getNistP521Params

        public static java.security.spec.ECParameterSpec getNistP521Params()

      • isNistEcParameterSpec

        public static boolean isNistEcParameterSpec​(java.security.spec.ECParameterSpec spec)
        Returns whether spec is a ECParameterSpec of one of the NIST curves.

      • isSameEcParameterSpec

        public static boolean isSameEcParameterSpec​(java.security.spec.ECParameterSpec one,
                                            java.security.spec.ECParameterSpec two)
        Returns whether one is the same ECParameterSpec as two.

      • validatePublicKey

        public static void validatePublicKey​(java.security.interfaces.ECPublicKey publicKey,
                                     java.security.interfaces.ECPrivateKey privateKey)
                              throws java.security.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:
        java.security.GeneralSecurityException
        Since:
        1.1.0

      • getModulus

        public static java.math.BigInteger getModulus​(java.security.spec.EllipticCurve curve)
                                       throws java.security.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:
        java.security.GeneralSecurityException

      • fieldSizeInBits

        public static int fieldSizeInBits​(java.security.spec.EllipticCurve curve)
                           throws java.security.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:
        java.security.GeneralSecurityException

      • fieldSizeInBytes

        public static int fieldSizeInBytes​(java.security.spec.EllipticCurve curve)
                            throws java.security.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:
        java.security.GeneralSecurityException

      • ecdsaIeee2Der

        public static byte[] ecdsaIeee2Der​(byte[] ieee)
                            throws java.security.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:
        java.security.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 java.security.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:
        java.security.GeneralSecurityException - if the signature is not valid DER encoding.

      • isValidDerEncoding

        public static boolean isValidDerEncoding​(byte[] sig)

      • encodingSizeInBytes

        public static int encodingSizeInBytes​(java.security.spec.EllipticCurve curve,
                                      EllipticCurves.PointFormatType format)
                               throws java.security.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:
        java.security.GeneralSecurityException - if the point format is unknown or if the elliptic curve is not supported

      • ecPointDecode

        public static java.security.spec.ECPoint ecPointDecode​(java.security.spec.EllipticCurve curve,
                                                       EllipticCurves.PointFormatType format,
                                                       byte[] encoded)
                                                throws java.security.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:
        java.security.GeneralSecurityException - if the encoded point is invalid or if the curve or format are not supported.

      • pointDecode

        public static java.security.spec.ECPoint pointDecode​(EllipticCurves.CurveType curveType,
                                                     EllipticCurves.PointFormatType format,
                                                     byte[] encoded)
                                              throws java.security.GeneralSecurityException
        Decodes an encoded point on an elliptic curve. This method checks that the encoded point is on the curve.
        Parameters:
        curveType - the elliptic curve
        format - the format used to enocde the point
        encoded - the encoded point
        Returns:
        the point
        Throws:
        java.security.GeneralSecurityException - if the encoded point is invalid or if the curve or format are not supported.
        Since:
        1.1.0

      • pointDecode

        public static java.security.spec.ECPoint pointDecode​(java.security.spec.EllipticCurve curve,
                                                     EllipticCurves.PointFormatType format,
                                                     byte[] encoded)
                                              throws java.security.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:
        java.security.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,
                                 java.security.spec.ECPoint point)
                          throws java.security.GeneralSecurityException
        Encodes a point on an elliptic curve.
        Parameters:
        curveType - the elliptic curve
        format - the format for the encoding
        point - the point to encode
        Returns:
        the encoded key exchange
        Throws:
        java.security.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​(java.security.spec.EllipticCurve curve,
                                 EllipticCurves.PointFormatType format,
                                 java.security.spec.ECPoint point)
                          throws java.security.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:
        java.security.GeneralSecurityException - if the point is not on the curve or if the format is not supported.
        Since:
        1.1.0

      • getCurveSpec

        public static java.security.spec.ECParameterSpec getCurveSpec​(EllipticCurves.CurveType curve)
                                                       throws java.security.NoSuchAlgorithmException
        Returns the ECParameterSpec for a named curve.
        Parameters:
        curve - the curve type
        Returns:
        the ECParameterSpec for the curve.
        Throws:
        java.security.NoSuchAlgorithmException

      • getEcPublicKey

        public static java.security.interfaces.ECPublicKey getEcPublicKey​(byte[] x509PublicKey)
                                                           throws java.security.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 Key.getEncoded(), regardless of the provider.

        Throws:
        java.security.GeneralSecurityException

      • getEcPublicKey

        public static java.security.interfaces.ECPublicKey getEcPublicKey​(EllipticCurves.CurveType curve,
                                                                  EllipticCurves.PointFormatType pointFormat,
                                                                  byte[] publicKey)
                                                           throws java.security.GeneralSecurityException
        Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.
        Throws:
        java.security.GeneralSecurityException

      • getEcPublicKey

        public static java.security.interfaces.ECPublicKey getEcPublicKey​(java.security.spec.ECParameterSpec spec,
                                                                  EllipticCurves.PointFormatType pointFormat,
                                                                  byte[] publicKey)
                                                           throws java.security.GeneralSecurityException
        Returns an ECPublicKey from publicKey that is a public key in point format pointFormat on curve.
        Throws:
        java.security.GeneralSecurityException

      • getEcPublicKey

        public static java.security.interfaces.ECPublicKey getEcPublicKey​(EllipticCurves.CurveType curve,
                                                                  byte[] x,
                                                                  byte[] y)
                                                           throws java.security.GeneralSecurityException
        Returns an ECPublicKey from curve type and x and y coordinates.
        Throws:
        java.security.GeneralSecurityException

      • getEcPrivateKey

        public static java.security.interfaces.ECPrivateKey getEcPrivateKey​(byte[] pkcs8PrivateKey)
                                                             throws java.security.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 Key.getEncoded(), regardless of the provider.

        Throws:
        java.security.GeneralSecurityException

      • getEcPrivateKey

        public static java.security.interfaces.ECPrivateKey getEcPrivateKey​(EllipticCurves.CurveType curve,
                                                                    byte[] keyValue)
                                                             throws java.security.GeneralSecurityException
        Returns an ECPrivateKey from curve type and keyValue.
        Throws:
        java.security.GeneralSecurityException

      • generateKeyPair

        public static java.security.KeyPair generateKeyPair​(EllipticCurves.CurveType curve)
                                             throws java.security.GeneralSecurityException
        Generates a new key pair for curve.
        Throws:
        java.security.GeneralSecurityException

      • generateKeyPair

        public static java.security.KeyPair generateKeyPair​(java.security.spec.ECParameterSpec spec)
                                             throws java.security.GeneralSecurityException
        Generates a new key pair for spec.
        Throws:
        java.security.GeneralSecurityException

      • computeSharedSecret

        public static byte[] computeSharedSecret​(java.security.interfaces.ECPrivateKey myPrivateKey,
                                         java.security.interfaces.ECPublicKey peerPublicKey)
                                  throws java.security.GeneralSecurityException
        Generates the DH shared secret using myPrivateKey and peerPublicKey
        Throws:
        java.security.GeneralSecurityException

      • computeSharedSecret

        public static byte[] computeSharedSecret​(java.security.interfaces.ECPrivateKey myPrivateKey,
                                         java.security.spec.ECPoint publicPoint)
                                  throws java.security.GeneralSecurityException
        Generates the DH shared secret using myPrivateKey and publicPoint
        Throws:
        java.security.GeneralSecurityException
        Since:
        1.1.0