crypto/tls: add example for Config KeyLogWriter

For #13057.

Change-Id: Idbc50d5b08e055a23ab7cc9eb62dbc47b65b1815
Reviewed-on: https://go-review.googlesource.com/29050
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/tls/example_test.go b/src/crypto/tls/example_test.go
index 7628e431bf90a97f70b26a73527faab1e6f1c61a..02d0f180af3184ed6cf580c3eb49452a806c5523 100644 (file)
--- a/src/crypto/tls/example_test.go
+++ b/src/crypto/tls/example_test.go
@@ -7,8 +7,23 @@ package tls_test
 import (
        "crypto/tls"
        "crypto/x509"
+       "log"
+       "net/http"
+       "net/http/httptest"
+       "os"
 )
 
+// zeroSource is an io.Reader that returns an unlimited number of zero bytes.
+type zeroSource struct{}
+
+func (zeroSource) Read(b []byte) (n int, err error) {
+       for i := range b {
+               b[i] = 0
+       }
+
+       return len(b), nil
+}
+
 func ExampleDial() {
        // Connecting with a custom root-certificate set.
 
@@ -55,3 +70,46 @@ yuGnBXj8ytqU0CwIPX4WecigUCAkVDNx
        }
        conn.Close()
 }
+
+func ExampleConfig_keyLogWriter() {
+       // Debugging TLS applications by decrypting a network traffic capture.
+
+       // WARNING: Use of KeyLogWriter compromises security and should only be
+       // used for debugging.
+
+       // Dummy test HTTP server for the example with insecure random so output is
+       // reproducible.
+       server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+       server.TLS = &tls.Config{
+               Rand: zeroSource{}, // for example only; don't do this.
+       }
+       server.StartTLS()
+       defer server.Close()
+
+       // Typically the log would go to an open file:
+       // w, err := os.OpenFile("tls-secrets.txt", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
+       w := os.Stdout
+
+       client := &http.Client{
+               Transport: &http.Transport{
+                       TLSClientConfig: &tls.Config{
+                               KeyLogWriter: w,
+
+                               Rand:               zeroSource{}, // for reproducible output; don't do this.
+                               InsecureSkipVerify: true,         // test server certificate is not trusted.
+                       },
+               },
+       }
+       resp, err := client.Get(server.URL)
+       if err != nil {
+               log.Fatalf("Failed to get URL: %v", err)
+       }
+       resp.Body.Close()
+
+       // The resulting file can be used with Wireshark to decrypt the TLS
+       // connection by setting (Pre)-Master-Secret log filename in SSL Protocol
+       // preferences.
+
+       // Output:
+       // CLIENT_RANDOM 0000000000000000000000000000000000000000000000000000000000000000 baca0df460a688e44ce018b025183cc2353ae01f89755ef766eedd3ecc302888ee3b3a22962e45f48c20df15a98c0e80
+}