crypto/elliptic: deprecate unsafe APIs

Per the updated go.dev/wiki/Deprecated, those APIs replaced by
crypto/ecdh (added in Go 1.20) can now be marked as deprecated
in Go 1.21.

Updates #52221
Updates #34648

Change-Id: Id0e11d7faa3a58a1716ce1ec6e2fff97bab96259
Reviewed-on: https://go-review.googlesource.com/c/go/+/459977
Run-TryBot: Filippo Valsorda <filippo@golang.org>
Auto-Submit: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

api/next/34648.txt

@@ -0,0 +1,5 @@
+pkg crypto/elliptic, method (*CurveParams) Add //deprecated #34648
+pkg crypto/elliptic, method (*CurveParams) Double //deprecated #34648
+pkg crypto/elliptic, method (*CurveParams) IsOnCurve //deprecated #34648
+pkg crypto/elliptic, method (*CurveParams) ScalarBaseMult //deprecated #34648
+pkg crypto/elliptic, method (*CurveParams) ScalarMult //deprecated #34648

api/next/52221.txt

@@ -0,0 +1,8 @@
+pkg crypto/elliptic, func GenerateKey //deprecated #52221
+pkg crypto/elliptic, func Marshal //deprecated #52221
+pkg crypto/elliptic, func Unmarshal //deprecated #52221
+pkg crypto/elliptic, type Curve interface, Add //deprecated #52221
+pkg crypto/elliptic, type Curve interface, Double //deprecated #52221
+pkg crypto/elliptic, type Curve interface, IsOnCurve //deprecated #52221
+pkg crypto/elliptic, type Curve interface, ScalarBaseMult //deprecated #52221
+pkg crypto/elliptic, type Curve interface, ScalarMult //deprecated #52221

src/crypto/elliptic/elliptic.go

@@ -5,8 +5,10 @@
 // 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 (
@@ -23,38 +25,41 @@ 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)
@@ -65,7 +70,7 @@ var mask = []byte{0xff, 0x1, 0x3, 0x7, 0xf, 0x1f, 0x3f, 0x7f}
 // 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
@@ -99,7 +104,7 @@ func GenerateKey(curve Curve, rand io.Reader) (priv []byte, x, y *big.Int, err e
 // 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)
@@ -143,7 +148,7 @@ var _ = []unmarshaler{p224, p256, p384, p521}
 // 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 {

src/crypto/elliptic/params.go

@@ -9,8 +9,9 @@ import "math/big"
 // 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
@@ -48,7 +49,7 @@ func (curve *CurveParams) polynomial(x *big.Int) *big.Int {
 
 // 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().
@@ -102,7 +103,7 @@ func (curve *CurveParams) affineFromJacobian(x, y, z *big.Int) (xOut, yOut *big.
 
 // 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().
@@ -200,7 +201,7 @@ func (curve *CurveParams) addJacobian(x1, y1, z1, x2, y2, z2 *big.Int) (*big.Int
 
 // 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().
@@ -279,7 +280,7 @@ func (curve *CurveParams) doubleJacobian(x, y, z *big.Int) (*big.Int, *big.Int,
 
 // 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().
@@ -309,7 +310,7 @@ func (curve *CurveParams) ScalarMult(Bx, By *big.Int, k []byte) (*big.Int, *big.
 
 // 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().