Skip to content
Tutorials Center
My learning

Topics

Lesson 114 of 147 ยท Web and Networking

TLS and HTTPS in Go

Learn how TLS works in Go with crypto/tls and net/http - certificates, trust pools, hostname checks, httptest TLS servers, mutual TLS (mTLS) and safe production settings.

Every request you send over plain HTTP can be read, and changed, by anyone on the path between client and server. TLS (Transport Layer Security) fixes that. It gives you three guarantees: the traffic is encrypted, it cannot be modified unnoticed, and the client can check who it is talking to. HTTPS is simply HTTP carried inside a TLS connection.

Go has TLS built into the standard library. The crypto/tls package implements the protocol, crypto/x509 handles certificates, and net/http uses both when you use an https:// URL or call ListenAndServeTLS. In this lesson you will see what the handshake does, start throw-away HTTPS servers in tests, create your own certificate authority in memory, and finish with mutual TLS, where the server also checks the client. Everything runs on loopback, so no real certificates or domain names are needed.

What happens in a handshake

Before any HTTP bytes are sent, the client and server agree on keys. The server proves its identity by sending a certificate: a signed statement that says "this public key belongs to this name". The client checks the signature against a list of trusted authorities and checks that the name matches the one it wanted to reach.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: ClientHello (versions, ciphers, server name)
    S->>C: ServerHello + certificate chain
    Note over C: Verify chain against trusted roots<br/>Verify the name matches
    C->>S: Key exchange + Finished
    S->>C: Finished
    C->>S: Encrypted HTTP request
    S->>C: Encrypted HTTP response

A TLS 1.3 handshake in outline: the client verifies the certificate before it sends any request.

The important idea is trust. A certificate is only worth something if the client already trusts whoever signed it. Operating systems ship a list of trusted root authorities. A browser or a Go program uses that list by default, which is why https://example.org just works. A certificate you made yourself is not in that list, so the client must be told about it explicitly.

A throw-away HTTPS server with httptest

The package net/http/httptest can start a TLS server with a built-in certificate, which makes it the easiest way to test HTTPS code. NewTLSServer returns a server whose Client() method gives you an *http.Client that already trusts that certificate.

Go httptest TLS server and a client that trusts it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Three things are worth noticing. First, r.TLS is nil for plain HTTP requests and holds the connection state (tls.ConnectionState) for HTTPS ones, so a handler can tell how a request arrived. Second, the response also carries resp.TLS on the client side, which lets you inspect the negotiated version and the server's certificates. Third, a normal client refuses the connection because it cannot build a chain from the test certificate to a trusted root. That refusal is the whole point of TLS; never switch it off to "make the error go away".

Avoid InsecureSkipVerify: true outside of throw-away experiments. It turns off certificate checking, so the connection is encrypted but you could be talking to anyone. Add the right certificate to RootCAs instead, as shown next.

Making your own certificate authority

Real certificates come from public authorities, and tools such as openssl or mkcert can create local ones. Go can do it in memory with crypto/x509, which is a good way to understand what a certificate contains. The recipe is:

  1. Generate a key pair for the authority (the CA) and create a self-signed CA certificate.
  2. Generate a key pair for the server and ask the CA to sign a certificate for it. The certificate lists the names (DNS names or IP addresses) that it is valid for.
  3. Give the server the certificate and its private key. Give the client the CA certificate in a CertPool.
Go A CA, a signed server certificate and a hostname check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Step 1 shows the name check. The client trusts the CA, but the certificate lists only api.example.test and the client dialed 127.0.0.1, so Go reports an x509.HostnameError (Go checks the name before it builds the chain). Step 3 uses the right name but no trusted CA, which gives x509.UnknownAuthorityError. Step 2 sets ServerName, which is both the name sent in the handshake (SNI, so one IP can serve many certificates) and the name used for verification. Normally Go takes this name from the URL for you; here we override it because the test server listens on an IP address.

Because the certificate is just a data structure, you can read any field from resp.TLS.PeerCertificates: subject, issuer, DNS names, expiry (NotAfter), key usage and more. Monitoring tools that warn you before a certificate expires do exactly this.

Configuring tls.Config

tls.Config is the single place where you tune TLS for a server or a client. These are the fields you will touch most:

Field Used by Purpose
Certificates server (and client for mTLS) The certificate chain and private key to present.
RootCAs client Authorities the client trusts; nil means the system's list.
ClientCAs server Authorities used to verify client certificates.
ClientAuth server Whether and how to ask clients for a certificate.
ServerName client Name for SNI and hostname verification.
MinVersion both Oldest protocol version you accept.
GetCertificate server Pick a certificate per request, for many domains or reloading.

Go's defaults are already sensible: TLS 1.2 is the minimum for servers and clients, TLS 1.3 is preferred, and the cipher suite list is curated, so you rarely need to set CipherSuites (and TLS 1.3 suites cannot be configured at all). Setting MinVersion: tls.VersionTLS13 as in the example is reasonable for internal services where you control both ends. Public servers usually keep TLS 1.2 for older clients.

A tls.Config must not be changed after it has been used in a connection. Build it once, or clone it with cfg.Clone() if you need a variation.

Serving HTTPS in production

For a real server you give http.Server a certificate and key files and call ListenAndServeTLS:

Go
srv := &http.Server{
    Addr:              ":8443",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,
    TLSConfig:         &tls.Config{MinVersion: tls.VersionTLS12},
}
log.Fatal(srv.ListenAndServeTLS("fullchain.pem", "privkey.pem"))

The first file must contain your certificate followed by any intermediate certificates (the "full chain"), otherwise some clients cannot build the path to a trusted root. If your certificates renew automatically (for example every 60 to 90 days with an ACME service such as Let's Encrypt), use TLSConfig.GetCertificate to load the new files without a restart. A small cache that re-reads the files when they change is enough.

The extended library has golang.org/x/crypto/acme/autocert, which obtains and renews certificates by itself. It is a third-party module, so it is not runnable here, but it is a one-liner on a real server: srv.TLSConfig = m.TLSConfig() with a autocert.Manager that lists the allowed host names.

HTTPS servers should also tell browsers to stay on HTTPS. Add the header Strict-Transport-Security: max-age=31536000 on responses, and redirect plain HTTP on port 80 to the secure URL. In many deployments a load balancer or reverse proxy ends TLS for you and forwards plain HTTP to your Go program inside a private network. That is fine, but then remember that r.TLS is nil; the proxy usually tells you the original scheme in an X-Forwarded-Proto header, which you should trust only when the request really came from that proxy.

Mutual TLS (mTLS)

In normal TLS only the server proves its identity. With mutual TLS the client has a certificate too. This is popular for service-to-service traffic: the service does not need passwords or API keys, because the certificate itself says which service is calling. The server sets ClientAuth: tls.RequireAndVerifyClientCert and provides ClientCAs, a pool of authorities allowed to sign client certificates. The client puts its certificate in Certificates.

Go Mutual TLS: the server learns who is calling

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The rejected calls fail inside the handshake, so your handler never runs. In TLS 1.3 the client may only notice the rejection when it first reads, which is why the code simply checks that err != nil instead of printing the message (it is not stable across versions). The handler can rely on r.TLS.PeerCertificates[0] being verified, because RequireAndVerifyClientCert checked the chain before the connection was accepted.

Notice that a certificate proves identity, not permission. After the handshake, your code still decides what billing-service may do. A common pattern is a middleware that reads the subject (or a URI SAN) from the verified certificate, puts it in the request context and checks it against an allow list. See handlers and middleware for the pattern.

Common mistakes

  • Skipping verification with InsecureSkipVerify and forgetting to remove it. Add the right CA to RootCAs instead.
  • Forgetting names in the certificate. Modern clients ignore the old Common Name field and look only at the Subject Alternative Names (DNSNames, IPAddresses).
  • Wrong key usage. A client certificate needs ExtKeyUsageClientAuth and a server certificate needs ExtKeyUsageServerAuth.
  • Missing intermediates in the file passed to ListenAndServeTLS: browsers may cope, other clients will not.
  • Mutating a shared tls.Config while connections are being made. Clone it first.
  • No timeouts. A TLS handshake is part of the connection set-up, so set ReadHeaderTimeout on servers and TLSHandshakeTimeout (default 10 seconds in http.DefaultTransport) on custom transports. See building an HTTP server and the HTTP client.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A default http.Client calls an httptest.NewTLSServer URL and fails with an unknown-authority error. What is the right fix?

    The test server uses a certificate that is not in the system trust store. srv.Client() is configured with that certificate in its RootCAs, so verification succeeds without turning checks off.
  2. 2. A client trusts your CA but still gets an x509.HostnameError when it connects. What is the most likely cause?

    The chain is valid, but a certificate is only valid for the names it lists. Add the DNS name or IP address to the certificate, or set tls.Config.ServerName to the right name.
  3. 3. Which server setting makes a TLS server require and verify a certificate from every client?

    ClientAuth chooses the policy and ClientCAs says which authorities may sign client certificates. RootCAs and ServerName are client-side settings.
  4. 4. Inside a handler on an HTTPS server, what does r.TLS == nil tell you?

    r.TLS holds the connection state only for TLS connections. Behind a proxy that ends TLS it is nil even for users who typed https://.
  5. 5. After mutual TLS succeeds for the caller billing-service, what must your code still do?

    A verified certificate proves who the caller is. Authorization is a separate decision that your application makes.

Summary

  • TLS gives encryption, integrity and server identity. HTTPS is HTTP inside TLS, and Go's net/http handles it with https:// URLs and ListenAndServeTLS.
  • A client trusts a server when the certificate chain leads to a root in RootCAs (default: the system list) and the certificate lists the name that was dialed.
  • httptest.NewTLSServer and StartTLS give you HTTPS servers for tests, and srv.Client() trusts them. r.TLS and resp.TLS expose the connection state.
  • crypto/x509 can create a CA and sign certificates in memory; use DNSNames/IPAddresses and the right ExtKeyUsage.
  • Never use InsecureSkipVerify to silence errors; fix RootCAs or ServerName instead.
  • Mutual TLS uses ClientAuth and ClientCAs on the server and Certificates on the client. It proves identity; you still authorize.

Next: Authentication, Sessions and JWT in Go