a807fe06 · marcel91200/caddy · siGit Code & Deploy

@@ -29,7 +29,22 @@ func init() {

29

30 // ECH enables Encrypted ClientHello (ECH) and configures its management.

31 //

32 -// Note that, as of Caddy 2.10 (~March 2025), ECH keys are not automatically

32 +// ECH helps protect site names (also called "server names" or "domain names"

33 +// or "SNI"), which are normally sent over plaintext when establishing a TLS

34 +// connection. With ECH, the true ClientHello is encrypted and wrapped by an

35 +// "outer" ClientHello that uses a more generic, shared server name that is

36 +// publicly known.

37 +//

38 +// Clients need to know which public name (and other parameters) to use when

39 +// connecting to a site with ECH, and the methods for this vary; however,

40 +// major browsers support reading ECH configurations from DNS records (which

41 +// is typically only secure when DNS-over-HTTPS or DNS-over-TLS is enabled in

42 +// the client). Caddy has the ability to automatically publish ECH configs to

43 +// DNS records if a DNS provider is configured either in the TLS app or with

44 +// each individual publication config object. (Requires a custom build with a

45 +// DNS provider module.)

46 +//

47 +// Note that, as of Caddy 2.10.0 (~March 2025), ECH keys are not automatically

48 // rotated due to a limitation in the Go standard library (see

49 // https://github.com/golang/go/issues/71920). This should be resolved when

50 // Go 1.25 is released (~Aug. 2025), and Caddy will be updated to automatically

@@ -39,6 +54,11 @@ func init() {

54 type ECH struct {

55 // The list of ECH configurations for which to automatically generate

56 // and rotate keys. At least one is required to enable ECH.

57 + //

58 + // It is strongly recommended to use as few ECH configs as possible

59 + // to maximize the size of your anonymity set (see the ECH specification

60 + // for a definition). Typically, each server should have only one public

61 + // name, i.e. one config in this list.

62 Configs []ECHConfiguration `json:"configs,omitempty"`

63

64 // Publication describes ways to publish ECH configs for clients to

@@ -482,33 +502,49 @@ func generateAndStoreECHConfig(ctx caddy.Context, publicName string) (echConfig,

502 //

503 // EXPERIMENTAL: Subject to change.

504 type ECHConfiguration struct {

485 - // The public server name that will be used in the outer ClientHello. This

486 - // should be a domain name for which this server is authoritative, because

487 - // Caddy will try to provision a certificate for this name. As an outer

488 - // SNI, it is never used for application data (HTTPS, etc.), but it is

489 - // necessary for securely reconciling inconsistent client state without

490 - // breakage and brittleness.

491 - OuterSNI string `json:"outer_sni,omitempty"`

505 + // The public server name (SNI) that will be used in the outer ClientHello.

506 + // This should be a domain name for which this server is authoritative,

507 + // because Caddy will try to provision a certificate for this name. As an

508 + // outer SNI, it is never used for application data (HTTPS, etc.), but it

509 + // is necessary for enabling clients to connect securely in some cases.

510 + // If this field is empty or missing, or if Caddy cannot get a certificate

511 + // for this domain (e.g. the domain's DNS records do not point to this server),

512 + // client reliability becomes brittle, and you risk coercing clients to expose

513 + // true server names in plaintext, which compromises both the privacy of the

514 + // server and makes clients more vulnerable.

515 + PublicName string `json:"public_name"`

516 }

517

494 -// ECHPublication configures publication of ECH config(s).

518 +// ECHPublication configures publication of ECH config(s). It pairs a list

519 +// of ECH configs with the list of domains they are assigned to protect, and

520 +// describes how to publish those configs for those domains.

521 +//

522 +// Most servers will have only a single publication config, unless their

523 +// domains are spread across multiple DNS providers or require different

524 +// methods of publication.

525 +//

526 +// EXPERIMENTAL: Subject to change.

527 type ECHPublication struct {

496 - // TODO: Should these first two fields be called outer_sni and inner_sni ?

497 -

528 // The list of ECH configurations to publish, identified by public name.

529 // If not set, all configs will be included for publication by default.

530 + //

531 + // It is generally advised to maximize the size of your anonymity set,

532 + // which implies using as few public names as possible for your sites.

533 + // Usually, only a single public name is used to protect all the sites

534 + // for a server

535 + //

536 + // EXPERIMENTAL: This field may be renamed or have its structure changed.

537 Configs []string `json:"configs,omitempty"`

538

502 - // The list of domain names which are protected with the associated ECH

503 - // configurations ("inner names"). Not all publishers may require this

504 - // information, but some, like the DNS publisher, do. (The DNS publisher,

505 - // for example, needs to know for which domain(s) to create DNS records.)

539 + // The list of ("inner") domain names which are protected with the associated

540 + // ECH configurations.

541 //

542 // If not set, all server names registered with the TLS module will be

508 - // added to this list implicitly. (Other Caddy apps that use the TLS

509 - // module automatically register their configured server names for this

510 - // purpose. For example, the HTTP server registers the hostnames for

511 - // which it applies automatic HTTPS.)

543 + // added to this list implicitly. (This registration is done automatically

544 + // by other Caddy apps that use the TLS module. They should register their

545 + // configured server names for this purpose. For example, the HTTP server

546 + // registers the hostnames for which it applies automatic HTTPS. This is

547 + // not something you, the user, have to do.) Most servers

548 //

549 // Names in this list should not appear in any other publication config

550 // object with the same publishers, since the publications will likely

@@ -526,11 +562,8 @@ type ECHPublication struct {

562 // server names in plaintext.

563 Domains []string `json:"domains,omitempty"`

564

529 - // How to publish the ECH configurations so clients can know to use them.

530 - // Note that ECH configs are only published when they are newly created,

531 - // so adding or changing publishers after the fact will have no effect

532 - // with existing ECH configs. The next time a config is generated (including

533 - // when a key is rotated), the current publication modules will be utilized.

565 + // How to publish the ECH configurations so clients can know to use

566 + // ECH to connect more securely to the server.

567 PublishersRaw caddy.ModuleMap `json:"publishers,omitempty" caddy:"namespace=tls.ech.publishers"`

568 publishers []ECHPublisher

569 }

caddytls: Enhance ECH documentation