crypto/x509: better documentation for ParsePKIXPublicKey

The existing documentation for ParsePKIXPublicKey is difficult to understand
and the return type of the parsed public key are not mentioned explicitly.

Descriptions about types of public key supported, as well as an example on
how to use type assertions to determine return type of a parsed public key
has been added.

Fixes #14355

Change-Id: Ib9561efb34255292735742c0b3e835c4b97ac589
Reviewed-on: https://go-review.googlesource.com/19757
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/crypto/x509/example_test.go b/src/crypto/x509/example_test.go
index 29e7c21397516119614bffc6eedd30fec344c967..97c2ea2442e28ac38fd6bc083be18c5f4f215315 100644 (file)
--- a/src/crypto/x509/example_test.go
+++ b/src/crypto/x509/example_test.go
@@ -5,8 +5,12 @@
 package x509_test
 
 import (
+       "crypto/dsa"
+       "crypto/ecdsa"
+       "crypto/rsa"
        "crypto/x509"
        "encoding/pem"
+       "fmt"
 )
 
 func ExampleCertificate_Verify() {
@@ -89,3 +93,42 @@ yE+vPxsiUkvQHdO2fojCkY8jg70jxM+gu59tPDNbw3Uh/2Ij310FgTHsnGQMyA==
                panic("failed to verify certificate: " + err.Error())
        }
 }
+
+func ExampleParsePKIXPublicKey() {
+       const pubPEM = `
+-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAlRuRnThUjU8/prwYxbty
+WPT9pURI3lbsKMiB6Fn/VHOKE13p4D8xgOCADpdRagdT6n4etr9atzDKUSvpMtR3
+CP5noNc97WiNCggBjVWhs7szEe8ugyqF23XwpHQ6uV1LKH50m92MbOWfCtjU9p/x
+qhNpQQ1AZhqNy5Gevap5k8XzRmjSldNAFZMY7Yv3Gi+nyCwGwpVtBUwhuLzgNFK/
+yDtw2WcWmUU7NuC8Q6MWvPebxVtCfVp/iQU6q60yyt6aGOBkhAX0LpKAEhKidixY
+nP9PNVBvxgu3XZ4P36gZV6+ummKdBVnc3NqwBLu5+CcdRdusmHPHd5pHf4/38Z3/
+6qU2a/fPvWzceVTEgZ47QjFMTCTmCwNt29cvi7zZeQzjtwQgn4ipN9NibRH/Ax/q
+TbIzHfrJ1xa2RteWSdFjwtxi9C20HUkjXSeI4YlzQMH0fPX6KCE7aVePTOnB69I/
+a9/q96DiXZajwlpq3wFctrs1oXqBp5DVrCIj8hU2wNgB7LtQ1mCtsYz//heai0K9
+PhE4X6hiE0YmeAZjR0uHl8M/5aW9xCoJ72+12kKpWAa0SFRWLy6FejNYCYpkupVJ
+yecLk/4L1W0l6jQQZnWErXZYe0PNFcmwGXy1Rep83kfBRNKRy5tvocalLlwXLdUk
+AIU+2GKjyT3iMuzZxxFxPFMCAwEAAQ==
+-----END PUBLIC KEY-----`
+
+       block, _ := pem.Decode([]byte(pubPEM))
+       if block == nil {
+               panic("failed to parse PEM block containing the public key")
+       }
+
+       pub, err := x509.ParsePKIXPublicKey(block.Bytes)
+       if err != nil {
+               panic("failed to parse DER encoded public key: " + err.Error())
+       }
+
+       switch pub := pub.(type) {
+       case *rsa.PublicKey:
+               fmt.Println("pub is of type RSA:", pub)
+       case *dsa.PublicKey:
+               fmt.Println("pub is of type DSA:", pub)
+       case *ecdsa.PublicKey:
+               fmt.Println("pub is of type ECDSA:", pub)
+       default:
+               panic("unknown type of public key")
+       }
+}

diff --git a/src/crypto/x509/x509.go b/src/crypto/x509/x509.go
index d9288bb30e880f92e0385c155d0796ab22b7b6f1..dc793cadead24f76f6537e5e14708fae3a00c497 100644 (file)
--- a/src/crypto/x509/x509.go
+++ b/src/crypto/x509/x509.go
@@ -36,6 +36,12 @@ type pkixPublicKey struct {
 
 // ParsePKIXPublicKey parses a DER encoded public key. These values are
 // typically found in PEM blocks with "BEGIN PUBLIC KEY".
+//
+// Supported key types include RSA, DSA, and ECDSA. Unknown key
+// types result in an error.
+//
+// On success, pub will be of type *rsa.PublicKey, *dsa.PublicKey,
+// or *ecdsa.PublicKey.
 func ParsePKIXPublicKey(derBytes []byte) (pub interface{}, err error) {
        var pki publicKeyInfo
        if rest, err := asn1.Unmarshal(derBytes, &pki); err != nil {