An SVCB Service Parameter for Well-Known URI Paths

Introduction SVCB and HTTPS resource records let a client learn connection parameters for a service before connecting, such as the protocols it supports and alternative endpoints. They do not say which resources are available once connected. Well-known URIs give machine-readable metadata a conventional location under "/.well-known/". The IANA "Well-Known URIs" registry holds many such suffixes, for example "api-catalog" and "agent-card.json", registered by the Linux Foundation for the Agent2Agent protocol . A client that already knows the applicable suffix can construct the URI itself, but it cannot learn from the DNS which of the registered resources a particular service offers. The "well-known" SvcParamKey closes that gap. A service binding advertises the well-known URI suffixes available at its endpoint, so a client can retrieve the resource it needs directly after resolution, without probing. Each DNS record in an RRset carries its own list, so a hosted endpoint or an alternative protocol can advertise different resources. The service parameter is defined here as a general primitive so that other specifications can reference it. o DNS for AI Discovery is one user of this parameter, advertising the location of an agent's capability descriptor. o [editors note] Authors will add other in progress work.

Requirements Notation 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 when, and only when, they appear in all capitals, as shown here.

The "well-known" SvcParamKey The "well-known" SvcParamKey advertises one or more well-known URI suffixes , each naming a resource under "/.well-known/" at the service endpoint. A client MAY retrieve any advertised resource. The list need not include every well-known resource available at the endpoint.

Wire Format The wire-format SvcParamValue consists of one or more entries concatenated without separators. Each entry is: a 2-octet unsigned length in network byte order, giving the length of the suffix in octets; then the suffix itself. A decoder reads entries until the SvcParamValue is exhausted. A value that ends inside an entry, or that contains a zero-length entry, does not have the expected format, so the RR is malformed (Section 2.2 of ).

Presentation Format

The value is a comma-separated list of one or more suffixes, using the character-string and list escaping rules of Section 2.1 and Appendix A.1 of . Empty items and whitespace around separators are not allowed. Each decoded suffix MUST match this ABNF :

The segment-nz and segment rules are from Section 3.3 of . A suffix does not begin with "/", does not include the "/.well-known/" prefix, and carries no query or fragment component. A suffix may extend below a registered well-known name where that registration allows it. Non-ASCII characters MUST be percent-encoded. Invalid percent escapes and segments equal to "." or "..", including their percent-encoded forms, MUST be rejected. Other percent-encoded octets MUST be preserved without decoding or normalisation. A value containing a suffix that fails these checks does not have the expected format, so the RR is malformed. Each decoded suffix is encoded as one length-prefixed entry (). Conversion in either direction MUST preserve suffix octets and list order, using the escaping rules for presentation output.

Examples The examples use the requested key name for illustration; no allocation is implied.

The first record advertises one resource at the owner name, "https://svc.example.com/.well-known/api-catalog". The second, with a hosted TargetName, advertises two resources at that host. Their wire-format SvcParamValues are, respectively, the first entry below and the second and third entries concatenated:

The suffix lengths are 11 and 15 octets; the two values are 13 and 30 octets. The following single-suffix value contains a literal comma:

Character-string decoding produces "foo/a\,b"; list decoding produces "foo/a,b". Its wire value is:

Interactions with Other SvcParamKeys The "well-known" key MAY appear alongside any other SvcParamKey. The "alpn" key selects the protocol used to retrieve a resource; the "port" key and the TargetName affect the origin (). Each ServiceMode record carries its own "well-known" value. The key MUST be ignored when it appears in an AliasMode record. If "well-known" is listed in "mandatory", a client that does not implement it MUST skip the record (Section 8 of ). This does not oblige a client to retrieve any advertised resource.

Resolving and Retrieving Advertised Resources A client forms the URI of an advertised resource by appending "/.well-known/" and the suffix to the origin of the service. For HTTPS records, the origin is that of the URI being resolved, as in Section 9 of ; the "port" key changes the connection port, not the origin. For SVCB records, the specification that maps the service to SVCB defines the scheme and authority. Where it does not, the origin is "https" at the TargetName (or the owner name when TargetName is "."), using the "port" key or 443.

Security Considerations The security and privacy considerations of and apply. The "well-known" parameter is conveyed in the DNS and has the same integrity properties as the enclosing record. The value is free text. It is deliberately not constrained to the suffixes in the IANA "Well-Known URIs" registry: an enumerated encoding would require DNS software to change each time a suffix is registered, and neither authoritative servers nor resolvers are positioned to validate it. A publisher, or an attacker able to alter records, can therefore advertise any string. Clients MUST treat an advertised suffix as metadata, not as a trust signal. A suffix that is well formed, or even registered, implies nothing about whether a resource exists at that location or whether its contents are trustworthy. A client MUST NOT relax endpoint authentication, destination restrictions, or redirect policy because a suffix was advertised in the DNS. Publishers MAY sign records carrying this key with DNSSEC . DNSSEC lets a validating resolver confirm that the record was published by the zone's authoritative source and was not altered in transit. It does not validate the suffix or the resource it names. Forged or hostile advertisements can induce unwanted requests or disclose client interests. Implementations SHOULD bound retrieval work rather than fetch every advertised resource. Publishing suffixes discloses information about a service; publishers SHOULD keep advertisements compact.

IANA Considerations IANA is requested to add the following entry to the "Service Parameter Keys (SvcParamKeys)" registry, in the "DNS Service Bindings (SVCB)" registry group, per the procedure defined in Section 14.3 of : Number Name Meaning Format Reference Change Controller TBD well-known One or more well-known URI suffixes available at the service endpoint (This document) IETF This request does not register individual well-known URI suffixes. Testing before allocation can use the private-use SvcParamKey range of .

Open Issues This section lists questions on which the authors seek input, in particular from the DNSOP and HTTPBIS working groups. It will be removed before publication. Suffix-only values. This document carries the suffix without the "/.well-known/" prefix, matching the IANA registry and saving octets. The original registration request and the current DNS-AID draft use full paths. Wire encoding. A list of length-prefixed entries is proposed, as used by other list-valued SvcParamKeys. An existing DNS-AID implementation carries a single string at a private-use key. Implementer input is welcome. The "dohpath" key is the existing precedent for a path-valued parameter, but this key is single valued. HTTPBIS review. The designated experts asked for consultation with HTTPBIS before a renewed allocation request.