This page is about Caddy 1 and will stay here forever.

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. Alternatively, if you just have more subdomains than CA rate limits allow, you can enable the DNS challenge and obtain a single wildcard certificate.

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.

Caddy does not disambiguate between different or conflicting TLS configurations with the same hostname as the key. If a TLS configuration is customized, then any other TLS configuration keyed by the same hostname must match, or at least be compatible, or it is an error. This includes cipher suites, curve preferences, etc.

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

Specifying your own certificate and key disables automatic HTTPS, including the changing of the port and redirecting HTTP to HTTPS. You will need to do that yourself if you are managing your own certificates.

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 that lasts 7 days (enough for local development):

tls self_signed

The above syntaxes use Caddy's default TLS settings with your own certificate and key or a self-signed certificate that lasts for 7 days: it intended for local development only.

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

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

Protocols

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

Note that setting the minimum protocol version lower may allow very old clients to connect, but at the risk of a false sense of security.

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

Cipher Suites

The following cipher suites are currently supported:

Note: Cipher suites cannot be customized when TLS 1.3 is used.

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:

Summary of Features

In summary, Caddy implements these TLS features for you automatically. It is the only server to do so by default:

Most sites will not even use the tls directive. It is not needed to use these features.

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, after consulting a backend for permission:

tls { ask http://localhost:9095/should-obtain-cert }

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?

Purchase a commercial license to use Caddy with your business and for basic email support, along with other benefits!