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