Computerized HTTPS
Caddy is the primary and solely internet server to make use of HTTPS routinely and by default.
Computerized HTTPS provisions TLS certificates for all of your websites and retains them renewed. It additionally redirects HTTP to HTTPS for you! Caddy makes use of protected and trendy defaults — no downtime, additional configuration, or separate tooling is required.
Here is a 28-second video displaying the way it works:
Menu:
Overview
By default, Caddy serves all websites over HTTPS.
- Caddy serves IP addresses and native/inner hostnames over HTTPS utilizing self-signed certificates which might be routinely trusted regionally (if permitted).
- Examples:
localhost
,127.0.0.1
- Examples:
- Caddy serves public DNS names over HTTPS utilizing certificates from a public ACME CA reminiscent of Let’s Encrypt or ZeroSSL .
- Examples:
instance.com
,sub.instance.com
,*.instance.com
- Examples:
Caddy retains all managed certificates renewed and redirects HTTP (default port 80
) to HTTPS (default port 443
) routinely.
For native HTTPS:
- Caddy could immediate for a password to put in its distinctive root certificates into your belief retailer. This occurs solely as soon as per root; and you’ll take away it at any time.
- Any consumer accessing the positioning with out trusting Caddy’s root CA certificates will present safety errors.
For public domains:
- In case your area’s A/AAAA data level to your server,
- ports
80
and443
are open externally, - Caddy can bind to these ports (or these ports are forwarded to Caddy),
- your data directory is writeable and chronic,
- and your area title seems someplace related within the config,
then websites might be served over HTTPS routinely. You will not should do the rest about it. It simply works!
As a result of HTTPS makes use of a shared, public infrastructure, you because the server admin ought to perceive the remainder of the knowledge on this web page so to keep away from pointless issues, troubleshoot them after they happen, and correctly configure superior deployments.
Activation
Caddy implicitly prompts automated HTTPS when it is aware of a website title (i.e. hostname) or IP tackle it’s serving. There are numerous methods to inform Caddy your area/IP, relying on the way you run or configure Caddy:
Any of the next will stop automated HTTPS from being activated, both in complete or partly:
Particular circumstances:
Results
When automated HTTPS is activated, the next happens:
Computerized HTTPS by no means overrides express configuration.
You possibly can customize or disable automatic HTTPS if mandatory; for instance, you’ll be able to skip sure domains or disable redirects (for Caddyfile, do that with global options).
Hostname necessities
All hostnames (domains) qualify for fully-managed certificates in the event that they:
- are non-empty
- consist solely of alphanumerics, hyphens, dots, and wildcard (
*
) - don’t begin or finish with a dot (RFC 1034)
As well as, hostnames qualify for publicly-trusted certificates in the event that they:
- aren’t localhost (together with
.localhost
and.native
TLDs) - aren’t an IP tackle
- have solely a single wildcard
*
because the left-most label
Native HTTPS
Caddy makes use of HTTPS routinely for all websites with a number (area, IP, or hostname) specified, together with inner and native hosts. Some hosts are both not public (e.g. 127.0.0.1
, localhost
) or don’t usually qualify for publicly-trusted certificates (e.g. IP addresses — you may get certificates for them, however solely from some CAs). These are nonetheless served over HTTPS except disabled.
To serve personal websites over HTTPS, Caddy generates its personal certificates authority (CA) and makes use of it to signal certificates. The belief chain consists of a root and intermediate certificates. Leaf certificates are signed by the intermediate. They’re saved in Caddy’s data directory at pki/authorities/native
.
Caddy’s native CA is powered by Smallstep libraries .
Native HTTPS doesn’t use ACME nor does it carry out any DNS validation. It really works solely on the native machine and is trusted solely the place the CA’s root certificates is put in.
CA Root
The foundation’s personal key’s uniquely generated utilizing a cryptographically-secure pseudorandom supply and endured to storage with restricted permissions. It’s loaded into reminiscence solely to carry out signing duties, after which it leaves scope to be garbage-collected.
Though Caddy will be configured to signal with the basis immediately (to help non-compliant shoppers), that is disabled by default, and the basis key’s solely used to signal intermediates.
The primary time a root key’s used, Caddy will attempt to set up it into the system’s native belief retailer(s). If it doesn’t have permission to take action, it’ll immediate for a password. This conduct will be disabled within the configuration if it’s not desired. If this fails because of being run as an unprivileged person, chances are you’ll run caddy trust
to retry set up as a privileged person.
After Caddy’s root CA is put in, you will notice it in your native belief retailer as “Caddy Native Authority” (except you’ve got configured a distinct title). You possibly can uninstall it any time if you want (the caddy untrust
command makes this simple).
Word that routinely putting in the certificates into the native belief shops is for comfort solely and is not assured to work, particularly if containers are getting used or if Caddy is being run as an unprivileged system service. In the end, in case you are counting on inner PKI, it’s the system administrator’s accountability to make sure Caddy’s root CA is correctly added to the mandatory belief shops (that is exterior the scope of the online server).
CA Intermediates
An intermediate certificates and key can even be generated, which might be used for signing leaf (particular person website) certificates.
Not like the basis certificates, intermediate certificates have a a lot shorter lifetime and can routinely be renewed as wanted.
Testing
To check or experiment together with your Caddy configuration, be sure you change the ACME endpoint to a staging or growth URL, in any other case you’re more likely to hit charge limits which may block your entry to HTTPS for as much as every week, relying on which charge restrict you hit.
One in every of Caddy’s default CAs is Let’s Encrypt , which has a staging endpoint that’s not topic to the identical rate limits :
https://acme-staging-v02.api.letsencrypt.org/listing
ACME challenges
Acquiring a publicly-trusted TLS certificates requires validation from a publicly-trusted, third-party authority. Nowadays, this validation course of is automated with the ACME protocol , and will be carried out considered one of 3 ways (“problem sorts”), described under.
The primary two problem sorts are enabled by default. If a number of challenges are enabled, Caddy chooses one at random to keep away from unintended dependence on a specific problem. Over time, it learns which problem kind is most profitable and can start to desire it first, however will fall again to different obtainable problem sorts if mandatory.
HTTP problem
The HTTP problem performs an authoritative DNS lookup for the candidate hostname’s A/AAAA file, then requests a brief cryptographic useful resource over port 80
utilizing HTTP. If the CA sees the anticipated useful resource, a certificates is issued.
This problem requires port 80
to be externally accessible. If Caddy can not hear on port 80, packets from port 80
should be forwarded to Caddy’s HTTP port.
This problem is enabled by default and doesn’t require express configuration.
TLS-ALPN problem
The TLS-ALPN problem performs an authoritative DNS lookup for the candidate hostname’s A/AAAA file, then requests a brief cryptographic useful resource over port 443
utilizing a TLS handshake containing particular ServerName and ALPN values. If the CA sees the anticipated useful resource, a certificates is issued.
This problem requires port 443
to be externally accessible. If Caddy can not hear on port 443, packets from port 443
should be forwarded to Caddy’s HTTPS port.
This problem is enabled by default and doesn’t require express configuration.
DNS problem
The DNS problem performs an authoritative DNS lookup for the candidate hostname’s TXT
data, and appears for a particular TXT
file with a sure worth. If the CA sees the anticipated worth, a certificates is issued.
This problem doesn’t require any open ports, and the server requesting a certificates doesn’t should be externally accessible. Nonetheless, the DNS problem requires configuration. Caddy must know the credentials to entry your area’s DNS supplier so it could set (and clear) the particular TXT
data. If the DNS problem is enabled, different challenges are disabled by default.
Since ACME CAs comply with DNS requirements when wanting up TXT
data for problem verification, you should utilize CNAME data to delegate answering the problem to different DNS zones. This can be utilized to delegate the _acme-challenge
subdomain to a different zone. That is significantly helpful in case your DNS supplier would not present an API, or is not supported by one of many DNS plugins for Caddy.
DNS supplier help is a neighborhood effort. Learn how to enable the DNS challenge for your provider at our wiki.
On-Demand TLS
Caddy pioneered a brand new know-how we name On-Demand TLS, which dynamically obtains a brand new certificates throughout the first TLS handshake that requires it, fairly than at config load. Crucially, this does not require hard-coding the domains in your configuration forward of time.
Many companies depend on this distinctive characteristic to scale their TLS deployments at decrease value and with out operational complications when serving tens of 1000’s of web sites.
On-demand TLS is beneficial if:
- you have no idea all of the domains whenever you begin or reload your server,
- domains may not be correctly configured instantly (DNS data not but set),
- you aren’t accountable for the domains (e.g. they’re buyer domains).
When on-demand TLS is enabled, you don’t want to specify the domains in your config with a purpose to get certificates for them. As an alternative, when a TLS handshake is acquired for a server title (SNI) that Caddy doesn’t but have a certificates for, the handshake is held whereas Caddy obtains a certificates to make use of to finish the handshake. The delay is normally only some seconds, and solely that preliminary handshake is gradual. All future handshakes are quick as a result of certificates are cached and reused, and renewals occur within the background. Future handshakes could set off upkeep for the certificates to maintain it renewed, however this upkeep occurs within the background if the certificates hasn’t expired but.
Utilizing On-Demand TLS
On-demand TLS should be each enabled and restricted to forestall abuse.
Enabling on-demand TLS occurs in TLS automation policies if utilizing the JSON config, or in site blocks with the tls
directive if utilizing the Caddyfile.
To forestall abuse of this characteristic, it’s essential to configure restrictions. That is performed within the automation
object of the JSON config, or the on_demand_tls
global option of the Caddyfile. Restrictions are “international” and are not configurable per-site or per-domain. The first restriction is an “ask” endpoint to which Caddy will ship an HTTP request to ask if it has permission to acquire and handle a certificates for the area within the handshake. This implies you have to some inner backend that may, for instance, question the accounts desk of your database and see if a buyer has signed up with that area title.
Be conscious of how rapidly your CA is ready to concern certificates. If it takes various seconds, this may negatively influence the person expertise (for the primary consumer solely).
On account of its deferred nature and the additional configuration required to forestall abuse, we advocate enabling on-demand TLS solely when your precise use case is described above.
See our wiki article for more information about using on-demand TLS effectively.
Errors
Caddy does its finest to proceed if errors happen with certificates administration.
By default, certificates administration is carried out within the background. This implies it won’t block startup or decelerate your websites. Nonetheless, it additionally signifies that the server might be operating even earlier than all certificates can be found. Working within the background permits Caddy to retry with exponential backoff over a protracted time frame.
Here is what occurs if there’s an error acquiring or renewing a certificates:
- Caddy retries as soon as after a short pause simply in case it was a fluke
- Caddy pauses briefly, then switches to the subsequent enabled problem kind
- In spite of everything enabled problem sorts have been tried, it tries the next configured issuer
- In spite of everything issuers have been tried, it backs off exponentially
- Most of 1 day between makes an attempt
- For as much as 30 days
Throughout retries with Let’s Encrypt, Caddy switches to their staging environment to keep away from charge restrict issues. This is not an ideal technique, however basically it is useful.
ACME challenges take at the very least a couple of seconds, and inner charge limiting helps mitigate unintended abuse. Caddy makes use of inner charge limiting along with what you or the CA configure so to hand Caddy a platter with one million domains and it’ll step by step — however as quick as it could — get hold of certificates for all of them. Caddy’s inner charge restrict is presently 10 makes an attempt per ACME account per 10 seconds.
To keep away from leaking assets, Caddy aborts in-flight duties (together with ACME transactions) when config is modified. Whereas Caddy is able to dealing with frequent config reloads, be conscious of operational issues reminiscent of this, and take into account batching config adjustments to cut back reloads and provides Caddy an opportunity to really end acquiring certificates within the background.
Issuer fallback
Caddy is the primary (and up to now solely) server to help fully-redundant, automated failover to different CAs within the occasion it can not efficiently get a certificates.
By default, Caddy permits two ACME-compatible CAs: Let’s Encrypt and ZeroSSL . If Caddy can not get a certificates from Let’s Encrypt, it’ll attempt with ZeroSSL; if each fail, it’ll backoff and retry once more later. In your config, you’ll be able to customise which issuers Caddy makes use of to acquire certificates, both universally or for particular names.
Storage
Caddy will retailer public certificates, personal keys, and different belongings in its configured storage facility (or the default one, if not configured — see hyperlink for particulars).
The primary factor it is advisable know utilizing the default config is that the $HOME
folder should be writeable and chronic. That can assist you troubleshoot, Caddy prints its surroundings variables at startup if the --environ
flag is specified.
Any Caddy situations which might be configured to make use of the identical storage will routinely share these assets and coordinate certificates administration as a cluster.
Earlier than making an attempt any ACME transactions, Caddy will take a look at the configured storage to make sure it’s writeable and has ample capability. This helps cut back pointless lock competition.
Wildcard certificates
Caddy can get hold of and handle wildcard certificates when it’s configured to serve a website with a qualifying wildcard title. A website title qualifies for a wildcard if solely its left-most area label is a wildcard. For instance, *.instance.com
qualifies, however these don’t: sub.*.instance.com
, foo*.instance.com
, *bar.instance.com
, and *.*.instance.com
.
If utilizing the Caddyfile, Caddy takes website names actually on the subject of the certificates topic names. In different phrases, a website outlined as sub.instance.com
will trigger Caddy to handle a certificates for sub.instance.com
, and a website outlined as *.instance.com
will trigger Caddy to handle a wildcard certificates for *.instance.com
. You possibly can see this demonstrated on our Common Caddyfile Patterns web page. Should you want totally different conduct, the JSON config offers you extra exact management over certificates topics and website names (“host matchers”).
Wildcard certificates characterize a large diploma of authority and will solely be used when you might have so many subdomains that managing particular person certificates for them would pressure the PKI or trigger you to hit CA-enforced charge limits.
Word: Let’s Encrypt requires the DNS challenge to acquire wildcard certificates.