DNS Configuration for Proxying IP in HTTP

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 7 January 2025.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Proxying IP in HTTP ([CONNECT-IP]) allows building a VPN through HTTP load balancers. However, at the time of writing, that mechanism doesn't offer a mechanism for communicating DNS configuration information inline. In contrast, most existing VPN protocols provide a mechanism to exchange DNS configuration information (e.g., [IKEv2]). This document describes an extension that exchanges this information using HTTP capsules ([HTTP-DGRAM]). This document does not define any new ways to convey DNS queries or responses, only a mechanism to exchange DNS configuration information.¶

2. Mechanism

Similar to how Proxying IP in HTTP exchanges IP address configuration information (Section 4.7 of [CONNECT-IP]), this mechanism leverages capsules to request DNS configuration information and to assign it. Similarly, this mechanism is bidirectional: either endpoint can request DNS configuration information by sending a DNS_REQUEST capsule, and either endpoint can send DNS configuration information in a DNS_ASSIGN capsule. These capsules follow the format defined below.¶

Nameserver {
  Type (i),
  Length (i),
  Value (...),
}

Each Nameserver structure contains the following fields:¶

Type:

An integer representing the protocol over which DNS queries and responses are sent. See below for possible values. Encoded as a variable-length integer.¶

Length:

The length of the following Value field, encoded as a variable-length integer.¶

Value:

DNS name server configuration value, depends on the Type. This is commonly an IP address, but for other protocols it can also represent a URI template or a hostname.¶

This document defines the following types:¶

• DNS over port 53. Type = 0. DNS is sent unencrypted over UDP or TCP port 53, as per [DNS]. The Value is an IP address (either IPv4 or IPv6) encoded in network byte order. Length SHALL be either 32 or 128 bits.¶

• DNS over TLS. Type = 1. DNS is sent over TLS, as per [DoT]. The Value is a hostname, optionally followed by a colon and a port. The encoding is the same as an authority without userinfo as defined in Section 3.2 of [URI]. It is encoded as ASCII, and not null-terminated. IPv4 and IPv6 addresses can be encoded using this format, though IPv6 addresses need to be enclosed in square brackets.¶

• DNS over QUIC. Type = 2. DNS is sent over QUIC, as per [DoQ]. The Value is a hostname, encoded the same as for DNS over TLS.¶

• DNS over HTTPS. Type = 3. DNS is sent over HTTPS, as per [DoH]. The Value is a URI Template. It is encoded as ASCII, and not null-terminated.¶

• TODO: properly define an IANA registry with GREASE for future types.¶

Domain {
  Domain Length (i),
  Domain Name (..),
}

Each Domain contains the following fields:¶

Domain Length:

Length of the following Domain field, encoded as a variable-length integer.¶

Domain Name:

Fully Qualified Domain Name in DNS presentation format and using an Internationalized Domain Names for Applications (IDNA) A-label ([IDNA]).¶

DNS Configuration {
  Request ID (i),
  Nameserver Count (i),
  Nameserver (..) ...,
  Internal Domain Count (i),
  Internal Domain (..) ...,
  Search Domain Count (i),
  Search Domain (..) ...,
}

Each DNS Configuration contains the following fields:¶

Request ID:

Request identifier, encoded as a variable-length integer. If this DNS Configuration is part of a request, then this contains a unique request identifier. If this DNS configuration is part of an assignment that is in response to a DNS configuration request then this field SHALL contain the value of the corresponding field in the request. If this DNS configuration is part of an unsolicited assignment, this field SHALL be zero.¶

Nameserver Count:

The number of Nameserver structures following this field. Encoded as a variable-length integer.¶

Nameserver:

A series of Nameserver structures representing DNS name servers.¶

Internal Domain Count:

The number of Domain structures following this field. Encoded as a variable-length integer.¶

Internal Domain:

A series of Domain structures representing internal DNS names.¶

Search Domain Count:

The number of Domain structures following this field. Encoded as a variable-length integer.¶

Search Domain:

A series of Domain structures representing search domains.¶

DNS_REQUEST Capsule {
  Type (i) = DNS_REQUEST,
  Length (i),
  DNS Configuration (..),
}

DNS_ASSIGN Capsule {
  Type (i) = DNS_ASSIGN,
  Length (i),
  DNS Configuration (..),
}

3. Handling

Note that internal domains include subdomains. In other words, if the DNS configuration contains a domain, that indicates that the corresponding domain and all of its subdomains can be resolved by the name servers exchanged in the same DNS configuration. Sending an empty string as an internal domain indicates the DNS root; i.e., that the corresponding name server can resolve all domain names.¶

As with other IP Proxying capsules, the receiver can decide whether to use or ignore the configuration information. For example, in the consumer VPN scenario, clients will trust the server and apply received DNS configuration, whereas servers will ignore any DNS configuration sent by the client.¶

If the IP proxy sends a DNS_ASSIGN capsule containing a DNS over HTTPS name server, then the client can validate whether the IP proxy is authoritative for the hostname in the URI template. If this validation succeeds, the client SHOULD send its DNS queries to that name server directly as independent HTTPS requests over the same HTTPS connection.¶

4. Examples

DNS Configuration = {
  Nameservers = [{
    Type = 3,  // DNS over HTTPS
    Value = "https://masque.example/dns-query{?dns}",
  }],
  Internal Domains = [""],
  Search Domains = [],
}

DNS Configuration = {
  Nameservers = [{
    Type = 0,  // DNS over 53
    Value = 2001:db8::1,
  }, {
    Type = 0,  // DNS over 53
    Value = 192.0.2.33,
  }],
  Internal Domains = ["internal.corp.example"],
  Search Domains = [
    "internal.corp.example",
    "corp.example",
  ],
}

5. Security Considerations

Acting on received DNS_ASSIGN capsules can have significant impact on endpoint security. Endpoints MUST ignore DNS_ASSIGN capsules unless it has reason to trust its peer and is expecting DNS configuration from it.¶

The requirement for an endpoint to always send DNS_ASSIGN capsules in response to DNS_REQUEST capsules could lead it to buffer unbounded amounts of memory if the underlying stream is blocked by flow or congestion control. Implementations MUST place an upper bound on that buffering and abort the stream if that limit is reached.¶

6. IANA Considerations

This document, if approved, will request IANA add the following values to the "HTTP Capsule Types" registry maintained at <https://www.iana.org/assignments/masque>.¶

Note that, if this document is approved, the values defined above will be replaced by smaller ones before publication.¶

All of these new entries use the following values for these fields:¶

Status:

provisional (permanent if this document is approved)¶

Reference:

This document¶

Change Controller:

IETF¶

Contact:

masque@ietf.org¶

Notes:

None¶

Acknowledgments

The mechanism is this document was inspired by [IKEv2] and [IKEv2-DNS].¶

Author's Address