// Package elliptic implements the standard NIST P-224, P-256, P-384, and P-521
// elliptic curves over prime fields.
//
-// The P224(), P256(), P384() and P521() values are necessary to use the crypto/ecdsa package.
-// Most other uses should migrate to the more efficient and safer crypto/ecdh package.
+// Direct use of this package is deprecated, beyond the P224(), P256(), P384(),
+// and P521() values necessary to use the crypto/ecdsa package. Most other uses
+// should migrate to the more efficient and safer crypto/ecdh package, or to
+// third-party modules for lower-level functionality.
package elliptic
import (
// Note that the conventional point at infinity (0, 0) is not considered on the
// curve, although it can be returned by Add, Double, ScalarMult, or
// ScalarBaseMult (but not the Unmarshal or UnmarshalCompressed functions).
+//
+// Using Curve implementations besides those returned by P224(), P256(), P384(),
+// and P521() is deprecated.
type Curve interface {
// Params returns the parameters for the curve.
Params() *CurveParams
// IsOnCurve reports whether the given (x,y) lies on the curve.
//
- // Note: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
+ // Deprecated: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
// package. The NewPublicKey methods of NIST curves in crypto/ecdh accept
// the same encoding as the Unmarshal function, and perform on-curve checks.
IsOnCurve(x, y *big.Int) bool
// Add returns the sum of (x1,y1) and (x2,y2).
//
- // Note: this is a low-level unsafe API.
+ // Deprecated: this is a low-level unsafe API.
Add(x1, y1, x2, y2 *big.Int) (x, y *big.Int)
// Double returns 2*(x,y).
//
- // Note: this is a low-level unsafe API.
+ // Deprecated: this is a low-level unsafe API.
Double(x1, y1 *big.Int) (x, y *big.Int)
// ScalarMult returns k*(x,y) where k is an integer in big-endian form.
//
- // Note: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
+ // Deprecated: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
// package. Most uses of ScalarMult can be replaced by a call to the ECDH
// methods of NIST curves in crypto/ecdh.
ScalarMult(x1, y1 *big.Int, k []byte) (x, y *big.Int)
// ScalarBaseMult returns k*G, where G is the base point of the group
// and k is an integer in big-endian form.
//
- // Note: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
+ // Deprecated: this is a low-level unsafe API. For ECDH, use the crypto/ecdh
// package. Most uses of ScalarBaseMult can be replaced by a call to the
// PrivateKey.PublicKey method in crypto/ecdh.
ScalarBaseMult(k []byte) (x, y *big.Int)
// GenerateKey returns a public/private key pair. The private key is
// generated using the given reader, which must return random data.
//
-// Note: for ECDH, use the GenerateKey methods of the crypto/ecdh package;
+// Deprecated: for ECDH, use the GenerateKey methods of the crypto/ecdh package;
// for ECDSA, use the GenerateKey function of the crypto/ecdsa package.
func GenerateKey(curve Curve, rand io.Reader) (priv []byte, x, y *big.Int, err error) {
N := curve.Params().N
// SEC 1, Version 2.0, Section 2.3.3. If the point is not on the curve (or is
// the conventional point at infinity), the behavior is undefined.
//
-// Note: for ECDH, use the crypto/ecdh package. This function returns an
+// Deprecated: for ECDH, use the crypto/ecdh package. This function returns an
// encoding equivalent to that of PublicKey.Bytes in crypto/ecdh.
func Marshal(curve Curve, x, y *big.Int) []byte {
panicIfNotOnCurve(curve, x, y)
// an error if the point is not in uncompressed form, is not on the curve, or is
// the point at infinity. On error, x = nil.
//
-// Note: for ECDH, use the crypto/ecdh package. This function accepts an
+// Deprecated: for ECDH, use the crypto/ecdh package. This function accepts an
// encoding equivalent to that of the NewPublicKey methods in crypto/ecdh.
func Unmarshal(curve Curve, data []byte) (x, y *big.Int) {
if c, ok := curve.(unmarshaler); ok {
// CurveParams contains the parameters of an elliptic curve and also provides
// a generic, non-constant time implementation of Curve.
//
-// Note: Custom curves (those not returned by P224(), P256(), P384(), and P521())
-// are not guaranteed to provide any security property.
+// The generic Curve implementation is deprecated, and using custom curves
+// (those not returned by P224(), P256(), P384(), and P521()) is not guaranteed
+// to provide any security property.
type CurveParams struct {
P *big.Int // the order of the underlying field
N *big.Int // the order of the base point
// IsOnCurve implements Curve.IsOnCurve.
//
-// Note: the CurveParams methods are not guaranteed to
+// Deprecated: the CurveParams methods are deprecated and are not guaranteed to
// provide any security property. For ECDH, use the crypto/ecdh package.
// For ECDSA, use the crypto/ecdsa package with a Curve value returned directly
// from P224(), P256(), P384(), or P521().
// Add implements Curve.Add.
//
-// Note: the CurveParams methods are not guaranteed to
+// Deprecated: the CurveParams methods are deprecated and are not guaranteed to
// provide any security property. For ECDH, use the crypto/ecdh package.
// For ECDSA, use the crypto/ecdsa package with a Curve value returned directly
// from P224(), P256(), P384(), or P521().
// Double implements Curve.Double.
//
-// Note: the CurveParams methods are not guaranteed to
+// Deprecated: the CurveParams methods are deprecated and are not guaranteed to
// provide any security property. For ECDH, use the crypto/ecdh package.
// For ECDSA, use the crypto/ecdsa package with a Curve value returned directly
// from P224(), P256(), P384(), or P521().
// ScalarMult implements Curve.ScalarMult.
//
-// Note: the CurveParams methods are not guaranteed to
+// Deprecated: the CurveParams methods are deprecated and are not guaranteed to
// provide any security property. For ECDH, use the crypto/ecdh package.
// For ECDSA, use the crypto/ecdsa package with a Curve value returned directly
// from P224(), P256(), P384(), or P521().
// ScalarBaseMult implements Curve.ScalarBaseMult.
//
-// Note: the CurveParams methods are not guaranteed to
+// Deprecated: the CurveParams methods are deprecated and are not guaranteed to
// provide any security property. For ECDH, use the crypto/ecdh package.
// For ECDSA, use the crypto/ecdsa package with a Curve value returned directly
// from P224(), P256(), P384(), or P521().