example_test.go

     1  // Copyright 2014 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package tls_test
     6  
     7  import (
     8  	"crypto/tls"
     9  	"crypto/x509"
    10  	"log"
    11  	"net/http"
    12  	"net/http/httptest"
    13  	"os"
    14  	"time"
    15  )
    16  
    17  // zeroSource is an io.Reader that returns an unlimited number of zero bytes.
    18  type zeroSource struct{}
    19  
    20  func (zeroSource) Read(b []byte) (n int, err error) {
    21  	for i := range b {
    22  		b[i] = 0
    23  	}
    24  
    25  	return len(b), nil
    26  }
    27  
    28  func ExampleDial() {
    29  	// Connecting with a custom root-certificate set.
    30  
    31  	const rootPEM = `
    32  -- GlobalSign Root R2, valid until Dec 15, 2021
    33  -----BEGIN CERTIFICATE-----
    34  MIIDujCCAqKgAwIBAgILBAAAAAABD4Ym5g0wDQYJKoZIhvcNAQEFBQAwTDEgMB4G
    35  A1UECxMXR2xvYmFsU2lnbiBSb290IENBIC0gUjIxEzARBgNVBAoTCkdsb2JhbFNp
    36  Z24xEzARBgNVBAMTCkdsb2JhbFNpZ24wHhcNMDYxMjE1MDgwMDAwWhcNMjExMjE1
    37  MDgwMDAwWjBMMSAwHgYDVQQLExdHbG9iYWxTaWduIFJvb3QgQ0EgLSBSMjETMBEG
    38  A1UEChMKR2xvYmFsU2lnbjETMBEGA1UEAxMKR2xvYmFsU2lnbjCCASIwDQYJKoZI
    39  hvcNAQEBBQADggEPADCCAQoCggEBAKbPJA6+Lm8omUVCxKs+IVSbC9N/hHD6ErPL
    40  v4dfxn+G07IwXNb9rfF73OX4YJYJkhD10FPe+3t+c4isUoh7SqbKSaZeqKeMWhG8
    41  eoLrvozps6yWJQeXSpkqBy+0Hne/ig+1AnwblrjFuTosvNYSuetZfeLQBoZfXklq
    42  tTleiDTsvHgMCJiEbKjNS7SgfQx5TfC4LcshytVsW33hoCmEofnTlEnLJGKRILzd
    43  C9XZzPnqJworc5HGnRusyMvo4KD0L5CLTfuwNhv2GXqF4G3yYROIXJ/gkwpRl4pa
    44  zq+r1feqCapgvdzZX99yqWATXgAByUr6P6TqBwMhAo6CygPCm48CAwEAAaOBnDCB
    45  mTAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUm+IH
    46  V2ccHsBqBt5ZtJot39wZhi4wNgYDVR0fBC8wLTAroCmgJ4YlaHR0cDovL2NybC5n
    47  bG9iYWxzaWduLm5ldC9yb290LXIyLmNybDAfBgNVHSMEGDAWgBSb4gdXZxwewGoG
    48  3lm0mi3f3BmGLjANBgkqhkiG9w0BAQUFAAOCAQEAmYFThxxol4aR7OBKuEQLq4Gs
    49  J0/WwbgcQ3izDJr86iw8bmEbTUsp9Z8FHSbBuOmDAGJFtqkIk7mpM0sYmsL4h4hO
    50  291xNBrBVNpGP+DTKqttVCL1OmLNIG+6KYnX3ZHu01yiPqFbQfXf5WRDLenVOavS
    51  ot+3i9DAgBkcRcAtjOj4LaR0VknFBbVPFd5uRHg5h6h+u/N5GJG79G+dwfCMNYxd
    52  AfvDbbnvRG15RjF+Cv6pgsH/76tuIMRQyV+dTZsXjAzlAcmgQWpzU/qlULRuJQ/7
    53  TBj0/VLZjmmx6BEP3ojY+x1J96relc8geMJgEtslQIxq/H5COEBkEveegeGTLg==
    54  -----END CERTIFICATE-----`
    55  
    56  	// First, create the set of root certificates. For this example we only
    57  	// have one. It's also possible to omit this in order to use the
    58  	// default root set of the current operating system.
    59  	roots := x509.NewCertPool()
    60  	ok := roots.AppendCertsFromPEM([]byte(rootPEM))
    61  	if !ok {
    62  		panic("failed to parse root certificate")
    63  	}
    64  
    65  	conn, err := tls.Dial("tcp", "mail.google.com:443", &tls.Config{
    66  		RootCAs: roots,
    67  	})
    68  	if err != nil {
    69  		panic("failed to connect: " + err.Error())
    70  	}
    71  	conn.Close()
    72  }
    73  
    74  func ExampleConfig_keyLogWriter() {
    75  	// Debugging TLS applications by decrypting a network traffic capture.
    76  
    77  	// WARNING: Use of KeyLogWriter compromises security and should only be
    78  	// used for debugging.
    79  
    80  	// Dummy test HTTP server for the example with insecure random so output is
    81  	// reproducible.
    82  	server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
    83  	server.TLS = &tls.Config{
    84  		Rand: zeroSource{}, // for example only; don't do this.
    85  	}
    86  	server.StartTLS()
    87  	defer server.Close()
    88  
    89  	// Typically the log would go to an open file:
    90  	// w, err := os.OpenFile("tls-secrets.txt", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
    91  	w := os.Stdout
    92  
    93  	client := &http.Client{
    94  		Transport: &http.Transport{
    95  			TLSClientConfig: &tls.Config{
    96  				KeyLogWriter: w,
    97  
    98  				Rand:               zeroSource{}, // for reproducible output; don't do this.
    99  				InsecureSkipVerify: true,         // test server certificate is not trusted.
   100  			},
   101  		},
   102  	}
   103  	resp, err := client.Get(server.URL)
   104  	if err != nil {
   105  		log.Fatalf("Failed to get URL: %v", err)
   106  	}
   107  	resp.Body.Close()
   108  
   109  	// The resulting file can be used with Wireshark to decrypt the TLS
   110  	// connection by setting (Pre)-Master-Secret log filename in SSL Protocol
   111  	// preferences.
   112  }
   113  
   114  func ExampleLoadX509KeyPair() {
   115  	cert, err := tls.LoadX509KeyPair("testdata/example-cert.pem", "testdata/example-key.pem")
   116  	if err != nil {
   117  		log.Fatal(err)
   118  	}
   119  	cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
   120  	listener, err := tls.Listen("tcp", ":2000", cfg)
   121  	if err != nil {
   122  		log.Fatal(err)
   123  	}
   124  	_ = listener
   125  }
   126  
   127  func ExampleX509KeyPair() {
   128  	certPem := []byte(`-----BEGIN CERTIFICATE-----
   129  MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
   130  DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
   131  EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
   132  7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
   133  5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
   134  BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
   135  NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
   136  Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
   137  6MF9+Yw1Yy0t
   138  -----END CERTIFICATE-----`)
   139  	keyPem := []byte(`-----BEGIN EC PRIVATE KEY-----
   140  MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
   141  AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
   142  EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
   143  -----END EC PRIVATE KEY-----`)
   144  	cert, err := tls.X509KeyPair(certPem, keyPem)
   145  	if err != nil {
   146  		log.Fatal(err)
   147  	}
   148  	cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
   149  	listener, err := tls.Listen("tcp", ":2000", cfg)
   150  	if err != nil {
   151  		log.Fatal(err)
   152  	}
   153  	_ = listener
   154  }
   155  
   156  func ExampleX509KeyPair_httpServer() {
   157  	certPem := []byte(`-----BEGIN CERTIFICATE-----
   158  MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
   159  DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
   160  EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
   161  7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
   162  5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
   163  BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
   164  NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
   165  Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
   166  6MF9+Yw1Yy0t
   167  -----END CERTIFICATE-----`)
   168  	keyPem := []byte(`-----BEGIN EC PRIVATE KEY-----
   169  MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
   170  AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
   171  EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
   172  -----END EC PRIVATE KEY-----`)
   173  	cert, err := tls.X509KeyPair(certPem, keyPem)
   174  	if err != nil {
   175  		log.Fatal(err)
   176  	}
   177  	cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
   178  	srv := &http.Server{
   179  		TLSConfig:    cfg,
   180  		ReadTimeout:  time.Minute,
   181  		WriteTimeout: time.Minute,
   182  	}
   183  	log.Fatal(srv.ListenAndServeTLS("", ""))
   184  }
   185  
   186  func ExampleConfig_verifyConnection() {
   187  	// VerifyConnection can be used to replace and customize connection
   188  	// verification. This example shows a VerifyConnection implementation that
   189  	// will be approximately equivalent to what crypto/tls does normally to
   190  	// verify the peer's certificate.
   191  
   192  	// Client side configuration.
   193  	_ = &tls.Config{
   194  		// Set InsecureSkipVerify to skip the default validation we are
   195  		// replacing. This will not disable VerifyConnection.
   196  		InsecureSkipVerify: true,
   197  		VerifyConnection: func(cs tls.ConnectionState) error {
   198  			opts := x509.VerifyOptions{
   199  				DNSName:       cs.ServerName,
   200  				Intermediates: x509.NewCertPool(),
   201  			}
   202  			for _, cert := range cs.PeerCertificates[1:] {
   203  				opts.Intermediates.AddCert(cert)
   204  			}
   205  			_, err := cs.PeerCertificates[0].Verify(opts)
   206  			return err
   207  		},
   208  	}
   209  
   210  	// Server side configuration.
   211  	_ = &tls.Config{
   212  		// Require client certificates (or VerifyConnection will run anyway and
   213  		// panic accessing cs.PeerCertificates[0]) but don't verify them with the
   214  		// default verifier. This will not disable VerifyConnection.
   215  		ClientAuth: tls.RequireAnyClientCert,
   216  		VerifyConnection: func(cs tls.ConnectionState) error {
   217  			opts := x509.VerifyOptions{
   218  				DNSName:       cs.ServerName,
   219  				Intermediates: x509.NewCertPool(),
   220  				KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth},
   221  			}
   222  			for _, cert := range cs.PeerCertificates[1:] {
   223  				opts.Intermediates.AddCert(cert)
   224  			}
   225  			_, err := cs.PeerCertificates[0].Verify(opts)
   226  			return err
   227  		},
   228  	}
   229  
   230  	// Note that when certificates are not handled by the default verifier
   231  	// ConnectionState.VerifiedChains will be nil.
   232  }
   233
View as plain text