crypto/elliptic: document the Name and names of each curve

See https://tools.ietf.org/html/rfc8422#appendix-A for a helpful table.

Also, commit to keeping them singletons, as that assumption is already
made all over the place in the ecosystem.

Fixes #34193

Change-Id: I2ec50fa18bb80e11d6101f2562df60b5e27d4f66
Reviewed-on: https://go-review.googlesource.com/c/go/+/218921
Run-TryBot: Filippo Valsorda <filippo@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/crypto/elliptic/elliptic.go b/src/crypto/elliptic/elliptic.go
index c84657c5e36777fcdf435b56ecf34d958f1b686f..e2f71cdb63babf2fcd72bacff4acafdcd5264b60 100644 (file)
--- a/src/crypto/elliptic/elliptic.go
+++ b/src/crypto/elliptic/elliptic.go
@@ -372,7 +372,12 @@ func initP521() {
        p521.BitSize = 521
 }
 
-// P256 returns a Curve which implements P-256 (see FIPS 186-3, section D.2.3)
+// P256 returns a Curve which implements NIST P-256 (FIPS 186-3, section D.2.3),
+// also known as secp256r1 or prime256v1. The CurveParams.Name of this Curve is
+// "P-256".
+//
+// Multiple invocations of this function will return the same value, so it can
+// be used for equality checks and switch statements.
 //
 // The cryptographic operations are implemented using constant-time algorithms.
 func P256() Curve {
@@ -380,7 +385,11 @@ func P256() Curve {
        return p256
 }
 
-// P384 returns a Curve which implements P-384 (see FIPS 186-3, section D.2.4)
+// P384 returns a Curve which implements NIST P-384 (FIPS 186-3, section D.2.4),
+// also known as secp384r1. The CurveParams.Name of this Curve is "P-384".
+//
+// Multiple invocations of this function will return the same value, so it can
+// be used for equality checks and switch statements.
 //
 // The cryptographic operations do not use constant-time algorithms.
 func P384() Curve {
@@ -388,7 +397,11 @@ func P384() Curve {
        return p384
 }
 
-// P521 returns a Curve which implements P-521 (see FIPS 186-3, section D.2.5)
+// P521 returns a Curve which implements NIST P-521 (FIPS 186-3, section D.2.5),
+// also known as secp521r1. The CurveParams.Name of this Curve is "P-521".
+//
+// Multiple invocations of this function will return the same value, so it can
+// be used for equality checks and switch statements.
 //
 // The cryptographic operations do not use constant-time algorithms.
 func P521() Curve {