User Guide

tls

tls configures HTTPS connections. Since HTTPS is enabled automatically, this directive should only be used to deliberately override default settings. Use with care, if at all.

Caddy supports SNI (Server Name Indication), so you can serve multiple HTTPS sites from the same port on your machine. In addition, Caddy implements OCSP stapling for all qualifying certificates. Caddy also automatically rotates all TLS session ticket keys periodically.

The tls directive will ignore sites that are explicitly defined to be http:// or are on port 80. This allows you to use the tls directive in a server block that is shared with both HTTP and HTTPS sites.

If not all the hostnames are not known when starting the server, you can use the On-Demand TLS feature, which issues certificates during the TLS handshake rather than at startup.

Caddy ships with sane defaults for cipher suites, curves, key types, and protocols. Their exact selection and ordering may change at any time with new releases. You probably do not need to change them yourself. Adjust the TLS configuration at your own risk.

Syntax

tls off

Disables TLS for the site. Not recommended unless you have a good reason. With TLS off, automatic HTTPS is also disabled, so the default port (2015) will not be changed.

tls email

Although the above syntax is not needed to enable TLS, it allows you to specify the email address used for your CA account, instead of prompting for one or using another one from a previous run.

To use Caddy with your own certificate and key:

tls cert key

You can use this directive multiple times to specify multiple certificate and key pairs.

Or to have Caddy generate and use an untrusted, self-signed certificate in memory:

tls self_signed

The above syntaxes use Caddy's default TLS settings with your own certificate and key or a self-signed certificate, which should be sufficient in most cases.

Advanced users may open a settings block for more control, optionally specifying their own certificate and key:

tls [cert key] { protocols min max ciphers ciphers... curves curves... clients [request|require|verify_if_given] clientcas... load dir max_certs limit key_type type dns provider alpn protos... must_staple }

Protocols

The following protocols are supported, in descending order of preference:

Note that setting the minimum protocol version too high will restrict the clients which are able to connect, but with the benefit of better privacy.

Supported protocols and default protocol versions may be changed at any time.

Cipher Suites

The following cipher suites are currently supported:

Note: The HTTP/2 spec blacklists over 275 cipher suites for security reasons. Unless you know what you're doing, it's best to accept the default cipher suite settings.

Cipher suites may be added to or removed from Caddy at any time. Similarly, the default cipher suites may be changed at any time.

Curves

The following curves are supported for EC cipher suites:

Examples

Remember, TLS is enabled by default, and this directive is not usually needed! These examples are for advanced users who manage certificates manually or need custom settings.

Serve with HTTPS using a certificate and private key located one folder up:

tls ../cert.pem ../key.pem

Obtain certificates during TLS handshakes as needed, with a hard limit of 10 new certificates:

tls { max_certs 10 }

Load all certificates and keys from .pem files found in /www/certificates:

tls { load /www/certificates }

Serve a site with a self-signed certificate in memory (untrusted by browsers, but convenient for local development):

tls self_signed

Need help with this feature?

Join us in the Caddy forum, where the open source community gathers to share their knowledge!

Does your company use Caddy?

Subscribe to the Engineering Package for prioritized bug fixes and private support from the authors.