A well-known URI for publishing service parameters

Internet-Draft	Well-Known URI for SVCB	October 2024
Farrell, et al.	Expires 4 April 2025	[Page]

Abstract

We define a well-known URI at which an HTTP origin can inform an authoritative DNS server, or other interested parties, about its Service Bindings. The data can include Encrypted ClientHello (ECH) configurations, allowing the origin, in collaboration with DNS infrastructure elements, to publish and rotate its own ECH keys.¶

1. Introduction

Encrypted ClientHello (ECH) [I-D.ietf-tls-esni] for TLS1.3 [RFC8446] defines a confidentiality mechanism for server names and other ClientHello content in TLS. The Service Bindings (SVCB) in DNS [RFC9460] RFC defines how to put information needed to make connections to services by using a new DNS record set (RRset). The [I-D.ietf-tls-svcb-ech] document defines an entry in that RRset for Encrypted Client Hello (ECH).¶

Many applications will require publication of SVCB data, such as a list of ECHConfig values, in the DNS. Each ECHConfig value contains the public component of a key pair that will typically be periodically (re-)generated by a web server. Many web infrastructures will have an API that can be used to dynamically update the DNS RRset to contain the current list of ECHConfig data, known as an ECHConfigList. Some deployments, however, will not, and those deployments could¶

Note that this is not intended for universal deployment, but rather for cases where the web server doesn't have write access to the relevant zone file (or equivalent). This mechanism is extensible to deliver other kinds of information about the origin, that can be of use in these circumstances. This document will use the ECH data to provide a concrete example.¶

We use the term "zone factory" (ZF) for the entity that does have write access to the zone file. We assume the ZF can also make HTTPS requests to the web server with the ECH keys. We define a well-known URI [RFC8615] on the web server that allows the ZF to poll for changes to ECHConfigList values. For example, if a web server generates new ECHConfigList values hourly and publishes those at the well-known URI, the ZF can poll that URI. When the ZF sees new values, it can check if those work, and if they do, then update the zone file and re-publish the zone.¶

If ECH is being operated in split-mode then the web server (backend) can similarly poll the ECH client-facing server at the well-known URI and then create it's own value to publish for the ZF to read. ECH split-mode is defined in [I-D.ietf-tls-esni] and some examples are shown below (Section 3).¶

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

We define or re-use the following terms:¶

Zone factory (ZF):: an entity that has write-access to the DNS¶
Client-Facing Server:: the web server that has an ECH private value. This processes the outer ClientHello and attempts ECH decryption. The name of client-facing server will typically be the public_name value used in an ECHConfig.¶
Backend:: the web server that will process the inner ClientHello. Note that even if client-facing server and backend are on the same web server, they almost certainly have different DNS names.¶
Shared-mode:: this is where client-facing and backend servers are the same web server.¶
Split-mode:: this refers to the case where the client-facing server only does ECH decryption but the TLS session is between the client and backend, which will typically be on a different host to client-facing server¶
regeninterval:: the number of seconds after which the value retrieved after acessing a well-known URI may be changed.¶

3. Example uses of the well-known URI for ECH

Some example deployments are described here.¶

3.1. Shared-mode deplpoyment.

                    +--------------------+
                    |                    |
 TLS                |   2001:DB8::1111   | Client-
Client <----------->|                    | facing
                    |   cfs.example.com  | server
                    | backend.example.com|
                    +--------------------+
                        ^            ^
     (1) ZF reads       |            |  (2) ZF checks
         .well-known    V            V      ECHConfig
                    +--------------------+
                    |                    |
                    |   zf.example.net   | Zone Factory (ZF)
                    |                    |
                    +--------------------+
                              |
                              | (3) ZF publishes new HTTPS RR
                              V
                    +--------------------+
                    |                    |
                    |   ns.example.net   | Authoritative DNS
                    |                    |
                    +--------------------+

Figure 1: Shared-Mode Topology with Zone Factory and DNS

The shared-mode ECH server generates new ECHConfigList values every "regeninterval" seconds via some regular, automated process (e.g., a cronjob). ECHConfigList values are "current" for an hour, and remain usable for three hours from the time of generation. The automated process updates the ECHConfigList values in a JSON resource (see Figure 3) at the well-known URI, https://backend.example.com/.well-known/origin-svcb.¶

These steps then occur:¶

On the ZF, another regularly executed job uses an HTTP client to retrieve this JSON resource from backend.example.com. The data MUST be fetched via HTTPS and the certificate validity MUST be verified.¶
The ZF next attempts to connect to backend.example.com using these ECH values and confirms that they are working.¶
The ZF observes that the JSON resource has a regeninterval of 3600 seconds, and chooses a DNS TTL of 1800. It updates the DNS zone file for backend.example.com and re-publishes the zone containing the new ECHConfigList values instead of the old.¶

When "regeninterval" seconds have passed, the ZF attempts to refresh its cached copy of the JSON resource. If the resource has changed, it repeats this process.¶

3.2. Split-mode, multi-CDN deplpoyment.

The following diagram, and this entire section, is a place-holder just to have something on which to base discussion, and will change.¶


                    +--------------------+
                    |        REAL        |
                    | backend.example.com|
                    |                    |
                    +--------------------+
                        ^^           ^^
                        ||    VPN    ||
                        VV           VV
           +--------------------+ +--------------------+
           |                    | |                    |
 TLS       |   2001:DB8::1111   | |   2001:DB8::FFFF   | Client-
Client <-->|backend.example.com | | backend.example.com| facing
           |  cfs.cdn1.example  | |  cfs.cdn2.example  | servers
           +--------------------+ +--------------------+
                        ^            ^
     (1) ZF reads       |            |  (2) ZF checks
         .well-known    V            V      ECHConfig
                    +--------------------+
                    |                    |
                    |   zf.example.net   | Zone Factory (ZF)
                    |                    |
                    +--------------------+
                              |
                              | (3) ZF publishes new HTTPS RR
                              V
                    +--------------------+
                    |                    |
                    |   ns.example.net   | Authoritative DNS
                    |                    |
                    +--------------------+

Figure 2: Shared-Mode Topology with Zone Factory and DNS

In this topology, the overall process is as in the previous section, but with the following differences:¶

There are two client-facing servers (in different CDNs) for the one "REAL" backend server that hosts the actual web resources.¶
ECH split-mode is assumed to be supported by both CDNs.¶
The "REAL" backend.example.com content is hosted on some machine(s) accessible from the client-facing servers via a VPN.¶
The ZF notes that backend.example.com has multiple AAAA RR values published, so queries for the .well-known at each of those. In this case the values received differ.¶
The ZF next attempts to connect to each CFS using the relevant ECH values and confirms that they are all working.¶
Note tha the ZF is not aware that ECH split-mode is in use.¶

5. The JSON structure for origin service binding info

    {
        "regeninterval": 3600,
        "endpoints": [{
            "priority": 1,
            "target": "cdn.example.",
            "params": {
                "ech": "AD7+DQA65wAgAC..AA=="
            }
        }, {
            "priority": 1,
            "params": {
                "port": 8413,
                "ech": "AD7+DQA65wAgAC..AA=="
            }
        }]
    }

Figure 3: Sample JSON for ECH without aliases

     {
        "regeninterval": 108000,
        "endpoints": [{
            "alias": "cdn1.example.com",
        }]
      }

Figure 4: Sample JSON with aliasing

The JSON file at the well-known URI MUST contain an object with two keys: "regeninterval", whose value is a number, and "endpoints" whose value is an array of objects. All other keys MUST be ignored.¶

The "regeninterval" must be a positive integer and specifies the number of seconds between key generation actions at the origin, i.e. a replacement ECHConfigList may be generated this often. This is used by the ZF to generate DNS TTL values and to determine when to next poll the origin for updates.¶

More precise expiration times are common (e.g., the "notAfter" field in certificate lifetime validity, discussed in Section 4.1.2.5 of [RFC5280]), but are too stringent for this use-case. The ZF cannot afford to fail open (by removing the HTTPS records) or fail closed (by removing the IP addresses), but it can safely "stretch" the lifetime of the HTTPS records because of ECH's "retry_configs" behavior. Since we have to accept this stretching, it makes sense to avoid an explicit expiration time and instead speak about the intended update frequency. This also make it clear the origin must tolerate some amount of version skew, and gives operational flexibility to avoid unreasonable update frequencies.¶

The "endpoints" key is an array of objects.¶

An empty endpoints array means that all HTTPS records that the ZF has published for the origin should be deleted.¶
An endpoints array with one element can be one of three things:¶
1. An empty object, which the ZF should take to be an HTTPS record with inferred SvcPriority, a TargetName equal to ".", and no ECH support. This can can be useful as a simple way to make use of the HTTPS RR type's HSTS behavior.¶
2. A ServiceMode entry, containing at least one key from the JSON HTTP Origin Info registry (see IANA Considerations (Section 9), below).¶
3. An AliasMode entry that points to another DNS name that must be resolved.¶
If the endpoints array has more than one element, every item SHOULD be a ServiceMode entry, due to restrictions on the use of multiple AliasMode records (see , Section 2.4.2 [RFC9460]).¶

This format is designed to allow full use of the capabilities of HTTPS records [RFC9460] in natural JSON while minimizing the risk of invalid configurations.¶

The following keys are defined for ServiceMode entries:¶

target:

The value is a string containing a fully qualified domain name, corresponding to the HTTPS record's TargetName. The default value is ".".¶

priority:

The value is a positive integer corresponding to the SvcPriority. If omitted, the ZF MAY infer numerically increasing SvcPriority from the order of the endpoints array.¶

params:

A JSON Dictionary representing the SVCB SvcParams. Each key in the dictionary is a string containing a registered SvcParamKey name (e.g., "ipv6hint") or a SvcParamKey in generic form (e.g., "key65528"). The default value is "{}".¶

For single-valued SvcParams (e.g., "ech"), the value is a JSON String. A JSON String is a sequence of Unicode codepoints, while a SvcParam's presentation value is a sequence of octets, so each value octet is stored as a single Unicode codepoint [ISOMORPHIC-DECODE]. In almost all cases, this is equivalent to the ordinary string representation of the presentation value.¶
For list-valued SvcParams (e.g., "alpn"), the value is a JSON Array of Strings. Each String represents an octet sequence, as in the single-value case.¶

The following key is defined for AliasMode entries.¶

alias:: The value MUST be a DNS name that could be used as the TargetName of an HTTPS resource record. This indicates that the backend is hosted on the same endpoints as this target, and is equivalent to an HTTPS AliasMode record. The ZF might implement this directive by publishing an AliasMode record, publishing a CNAME record, copying HTTPS records from the target zone, or fetching https://cfs.example.com/.well-known/origin-svcb (if it exists).¶

These definitions, taken with the ZF behaviour (Section 6) specified below, provide the following important properties:¶

Origins can express any useful configuration that is representable by HTTPS records, including multiple endpoints representing different ports, providers, etc.¶
Origins that simply alias to a single target can indicate this without copying the ECHConfig and other parameters, avoiding the maintenance burden of staying synchronized with the target's key rotations and configuration updates.¶

6. Zone Factory behaviour

If the ZF is unable to convert the JSON into a DNS zone fragment (e.g., due to an unrecognized SvcParamKey), or if the resulting zone fails validation checks, the ZF MUST NOT update the DNS. Such failures will not be directly visible to the client-facing server, so ZF implementations will need to provide some form of reporting so that the situation can be resolved. Note that this can lead to inconsistent behavior for a single origin served by multiple ZFs.¶

A ZF MAY apply additional processing according to its own policy, such as adjusting TTL values and correcting common misconfigurations.¶

ZF SHOULD check that ECH with the presented endpoints succeeds with the backend before publication. In order to make such checks, the ZF SHOULD attempt to access the well-known URI defined here while attempting ECH.¶

A bespoke TLS client is likely needed for this check, that does not require the ECHConfigList value to have already been published in the DNS. The TLS client also needs to allow checking for the success or failure of ECH.¶

If more than one ECHConfig is present in an ECHConfigList, then the ZF SHOULD explode the ECHConfigList value presented into "singleton" values with one public key in each, and then test each of those separately.¶

If ipv4hints or ipv6hints are present, and if those are not the same values as are published in A/AAAA RRs for the backend, then the ZF SHOULD check that webPKI based authentication of the backend works at all of the relevant addresses.¶

ZF SHOULD publish all the endpoints that are presented in the JSON file that pass the checks above.¶

ZF SHOULD set a DNS TTL less than regeninterval, i.e. short enough so that any cached DNS resource records are likely to have expired before the JSON object's content is likely to have changed. The ZF MUST attempt to refresh the JSON object and regenerate the zone before this time. This aims to ensure that ECHConfig values are not used longer than intended by backend.¶

7. Security Considerations

This document defines a way to publish SVCB/HTTPS RR values. If the wrong values were published in the DNS, then TLS clients using ECH might suffer a privacy leak, or degraded service due to overuse of ECH retry_configs.¶

Similarly, a ZF that also has write access to A/AAAA RRs for a backend, SHOULD NOT publish HTTPS RRs that contain ipv4hints or ipv6hints that are in conflict with the correct A/AAAA values unless those have been verified (via webPKI) as belonging to the same backend.¶

When considering the content of SVCB/HTTPS RRs, the general argument for the security of this scheme is that, this scheme has the backend server authenticate the JSON structure that is mapped directly to the SVCB/HTTPS RR, to eventually be used by TLS clients when interacting with the backend server, via the client-facing server.¶

ECH split-mode security also requires that the backend server acquire SvcParamKey values from the client-facing server via some authenticated means. If the backend server acquires the JSON data from the well-known URL and it is properly authenticated via HTTPS from the client-facing server's public_name then that satisfies this requirement.¶

The system described here depends on the webPKI for authentication of entities and results in publication of new SVCB/HTTPS RRs. The webPKI itself, however, often depends on the DNS to demonstrate control over a DNS name, e.g. when using the ACME protocol [RFC8555] with the HTTP-01 challenge type. A temporary breach of a backend server that allows the attacker to contol the JSON content described here could be used to bootsrap more long-lasting control over the backend's DNS name if the attacker were to request new certificates during the time when the attacker's chosen values were published in the DNS, and if the ACME server doing the validation solely depended on content from the backend's HTTPS RR, e.g. preferring ipv6hints over the AAAA for the backend. It would seem prudent for ACME servers to be cautious if using ipv4hints and ipv6hints, e.g. flagging divergence between those values and A/AAAA RRs.¶

Although the .well-known URL defined here may well be publicly accessible, general HTTP clients SHOULD NOT attempt to use this resource in lieu of HTTPS records queries through their preferred DNS server for the following reasons:¶

The bootstrap connection would not be able to use ECH, so it would reveal all the information that ECH seeks to protect.¶
The origin could serve the user with a uniquely identifying configuration, potentially resulting in an unexpected tracking vector.¶

The .well-known URI chosen here means that services running on different ports of the same backend are trusting the service running on the default port (443) for that backend to provide correct endpoint information.¶

As described, in mutlti-CDN and simlar scenarios, a ZF might only test ECH success against one of the CDNs unless the ZF can make use of the ipv4hints and/or ipv6hint values, or the ZF has out of band information about the different addresses at which backend.example.com can be accessed.¶

9. IANA Considerations

IANA is requested to take two actions: registering a new well-known URI in the registry at https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml#well-known-uris-1 and creating a new registry for defining items in the JSON object found at that endpoint.¶

9.1. Well-known endpoint registration

IANA is requested to add the following entry to the Well-Known URIs table:¶

Table 1: Additional Well-Known entry
Column	Value
URI Suffix	origin-svcb
Change Controller	IETF
Reference	{This RFC}
Status	permanent
Related Information	Must be fetched via HTTPS
Date Registered	{When registered}
Date Modified

Items in curly braces should be replaced with their actual values.¶

9.2. JSON Service Binding Info

If approved, this specification requests the creation of an IANA registry named "JSON Service Binding Info" with a Standards Action registration policy. The request is to put the table in a new file "json-svcb.xml" in the existing "dns-svcb" registry group. The table has three columns:¶

Name:: the name of the top-level field being added¶
Reference:: the document that defines the semantics of the field¶
Notes:: any short additional information the registrant wishes to add¶

The table should be populated with the following two entries, where Items in curly braces should be replaced with their actual values, and the "Notes" column is empty.¶

Table 2: Initial values for the registry
Name	Reference	Notes
endpoints	{This RFC}
regeninterval	{This RFC}

10. References

10.1. Normative References

[RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC5280]: Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <https://www.rfc-editor.org/info/rfc5280>.
[RFC8174]: Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8446]: Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8615]: Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/info/rfc8615>.
[RFC9460]: Schwartz, B., Bishop, M., and E. Nygren, "Service Binding and Parameter Specification via the DNS (SVCB and HTTPS Resource Records)", RFC 9460, DOI 10.17487/RFC9460, November 2023, <https://www.rfc-editor.org/info/rfc9460>.
[I-D.ietf-tls-esni]: Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS Encrypted Client Hello", Work in Progress, Internet-Draft, draft-ietf-tls-esni-22, 15 September 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22>.
[I-D.ietf-tls-svcb-ech]: Schwartz, B. M., Bishop, M., and E. Nygren, "Bootstrapping TLS Encrypted ClientHello with DNS Service Bindings", Work in Progress, Internet-Draft, draft-ietf-tls-svcb-ech-05, 3 September 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-tls-svcb-ech-05>.

10.2. Informative References

[RFC8555]: Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. Kasten, "Automatic Certificate Management Environment (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, <https://www.rfc-editor.org/info/rfc8555>.
[ISOMORPHIC-DECODE]: WHATWG, "WHATWG definition of Isomorphic Decode", <https://infra.spec.whatwg.org/#isomorphic-decode>.

Appendix A. Change Log

This section is to be removed before publishing as an RFC.¶

The -00 WG draft replaces draft-farrell-tls-wkesni-03.¶

Version 01 changed from a special-purpose design, carrying only ECHConfigs and port numbers, to a more general approach based on Service Bindings.¶

Version 02 is just a keep-alive¶

Version 03 reflects some local implementation experience with -02¶

Version 04 matches a proof-of-concept bash script implementation and results of IETF-117 discussion.¶

Version 05 updated the IANA and Security considerations and fixed conformance to HTTPS SVCB spec. It also addressed early artart and dnsop reviews, and some list discussion/github issues.¶

Version 06 changed the name and some of the text because it is no longer ECH-specific.¶