crypto: document the extended key interfaces

Change-Id: Iaff3f77b0a168e8bde981c791035a6451b3a49ac
Reviewed-on: https://go-review.googlesource.com/c/go/+/353049
Trust: Filippo Valsorda <filippo@golang.org>
Run-TryBot: Filippo Valsorda <filippo@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Julie Qiu <julie@golang.org>

diff --git a/src/crypto/crypto.go b/src/crypto/crypto.go
index ce473b5afe1a4ac1f94d778d91b2f7158fce2a34..cb87972afc7611b8a83bade8f2669f9a85364fbb 100644 (file)
--- a/src/crypto/crypto.go
+++ b/src/crypto/crypto.go
@@ -150,9 +150,29 @@ func RegisterHash(h Hash, f func() hash.Hash) {
 }
 
 // PublicKey represents a public key using an unspecified algorithm.
+//
+// Although this type is an empty interface for backwards compatibility reasons,
+// all public key types in the standard library implement the following interface
+//
+//     interface{
+//         Equal(x crypto.PublicKey) bool
+//     }
+//
+// which can be used for increased type safety within applications.
 type PublicKey interface{}
 
 // PrivateKey represents a private key using an unspecified algorithm.
+//
+// Although this type is an empty interface for backwards compatibility reasons,
+// all private key types in the standard library implement the following interface
+//
+//     interface{
+//         Public() crypto.PublicKey
+//         Equal(x crypto.PrivateKey) bool
+//     }
+//
+// as well as purpose-specific interfaces such as Signer and Decrypter, which
+// can be used for increased type safety within applications.
 type PrivateKey interface{}
 
 // Signer is an interface for an opaque private key that can be used for