Internet-Draft DoC March 2023
Lenders, et al. Expires 14 September 2023 [Page]
Intended Status:
Standards Track
M. S. Lenders
FU Berlin
C. Amsüss
C. Gündoğan
Huawei Technologies
T. C. Schmidt
HAW Hamburg
M. Wählisch
FU Berlin

DNS over CoAP (DoC)


This document defines a protocol for sending DNS messages over the Constrained Application Protocol (CoAP). These CoAP messages are protected by DTLS-Secured CoAP (CoAPS) or Object Security for Constrained RESTful Environments (OSCORE) to provide encrypted DNS message exchange for constrained devices in the Internet of Things (IoT).

Discussion Venues

This note is to be removed before publishing as an RFC.

Discussion of this document takes place on the Constrained RESTful Environments Working Group mailing list (, which is archived at

Source for this draft and an issue tracker can be found at

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

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 14 September 2023.

Table of Contents

1. Introduction

This document defines DNS over CoAP (DoC), a protocol to send DNS [RFC1035] queries and get DNS responses over the Constrained Application Protocol (CoAP) [RFC7252]. Each DNS query-response pair is mapped into a CoAP message exchange. Each CoAP message is secured by DTLS [RFC9147] or Object Security for Constrained RESTful Environments (OSCORE) [RFC8613] to ensure message integrity and confidentiality.

The application use case of DoC is inspired by DNS over HTTPS [RFC8484] (DoH). DoC, however, aims for the deployment in the constrained Internet of Things (IoT), which usually conflicts with the requirements introduced by HTTPS.

To prevent TCP and HTTPS resource requirements, constrained IoT devices could use DNS over DTLS [RFC8094]. In contrast to DNS over DTLS, DoC utilizes CoAP features to mitigate drawbacks of datagram-based communication. These features include: block-wise transfer, which solves the Path MTU problem of DNS over DTLS (see [RFC8094], section 5); CoAP proxies, which provide an additional level of caching; re-use of data structures for application traffic and DNS information, which saves memory on constrained devices.

To prevent resource requirements of DTLS or TLS on top of UDP (e.g., introduced by DNS over QUIC [RFC9250]), DoC allows for lightweight end-to-end payload encryption based on OSCORE.

FETCH coaps://[2001:db8::1]/ CoAP request [DNS query] DNS query DoC DoC DNS Client Server Infrastructure CoAP response DNS response [DNS response] DNS over CoAP DNS over UDP/HTTPS/QUIC/..
Figure 1: Basic DoC architecture

The most important components of DoC can be seen in Figure 1: A DoC client tries to resolve DNS information by sending DNS queries carried within CoAP requests to a DoC server. That DoC server is a DNS client (i.e., a stub or recursive resolver) that resolves DNS information by using other DNS transports such as DNS over UDP [RFC1035], DNS over HTTPS [RFC8484], or DNS over QUIC [RFC9250] when communicating with the upstream DNS infrastructure. Using that information, the DoC server then replies to the queries of the DoC client with DNS responses carried within CoAP responses.

2. Terminology

A server that provides the service specified in this document is called a "DoC server" to differentiate it from a classic "DNS server". A DoC server acts either as a DNS stub resolver [RFC8499] or a DNS recursive resolver [RFC8499].

A client using the service specified in this document to retrieve the DNS information is called a "DoC client".

The term "constrained nodes" is used as defined in [RFC7228].

The terms "CoAP payload" and "CoAP body" are used as defined in [RFC7959], Section 2.

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.

3. Selection of a DoC Server

In this document, it is assumed that the DoC client knows the DoC server and the DNS resource at the DoC server. Possible options could be manual configuration of a URI [RFC3986] or CRI [I-D.ietf-core-href], or automatic configuration, e.g., using a CoRE resource directory [RFC9176], DHCP or Router Advertisement options [I-D.ietf-add-dnr]. Automatic configuration SHOULD only be done from a trusted source.

When discovering the DNS resource through a link mechanism that allows describing a resource type (e.g., the Resource Type Attribute in [RFC6690]), the resource type "core.dns" can be used to identify a generic DNS resolver that is available to the client.

4. Basic Message Exchange

4.1. The "application/dns-message" Content-Format

This document defines a CoAP Content-Format number for the Internet media type "application/dns-message". This media type is defined as in [RFC8484] Section 6, i.e., a single DNS message encoded in the DNS on-the-wire format [RFC1035]. Both DoC client and DoC server MUST be able to parse contents in the "application/dns-message" format.

4.2. DNS Queries in CoAP Requests

A DoC client encodes a single DNS query in one or more CoAP request messages that use the CoAP FETCH [RFC8132] method. Requests SHOULD include an Accept option to indicate the type of content that can be parsed in the response.

Since CoAP provides reliability of the message layer (e.g. CON) the retransmission mechanism of the DNS protocol as defined in [RFC1035] is not needed.

4.2.1. Request Format

When sending a CoAP request, a DoC client MUST include the DNS query in the body of the CoAP request. As specified in [RFC8132] Section 2.3.1, the type of content of the body MUST be indicated using the Content-Format option. This document specifies the usage of Content-Format "application/dns-message" (details see Section 4.1). A DoC server MUST be able to parse requests of Content-Format "application/dns-message".

4.2.2. Support of CoAP Caching

The DoC client SHOULD set the ID field of the DNS header always to 0 to enable a CoAP cache (e.g., a CoAP proxy en-route) to respond to the same DNS queries with a cache entry. This ensures that the CoAP Cache-Key (see [RFC8132] Section 2) does not change when multiple DNS queries for the same DNS data, carried in CoAP requests, are issued.

4.2.3. Examples

The following example illustrates the usage of a CoAP message to resolve " IN AAAA" based on the URI "coaps://[2001:db8::1]/". The CoAP body is encoded in "application/dns-message" Content Format.

FETCH coaps://[2001:db8::1]/
Content-Format: application/dns-message
Accept: application/dns-message
Payload: 00 00 01 20 00 02 00 00 00 00 00 00 07 65 78 61 [binary]
         6d 70 6c 65 03 6f 72 67 00 00 1c 00 01 c0 0c 00 [binary]
         01 00 01                                        [binary]

4.3. DNS Responses in CoAP Responses

Each DNS query-response pair is mapped to a CoAP REST request-response operation. DNS responses are provided in the body of the CoAP response. A DoC server MUST be able to produce responses in the "application/dns-message" Content-Format (details see Section 4.1) when requested. A DoC client MUST understand responses in "application/dns-message" format when it does not send an Accept option. Any other response format than "application/dns-message" MUST be indicated with the Content-Format option by the DoC server.

4.3.1. Response Codes and Handling DNS and CoAP errors

A DNS response indicates either success or failure in the Response code of the DNS header (see [RFC1035] Section 4.1.1). It is RECOMMENDED that CoAP responses that carry any valid DNS response use a "2.05 Content" response code.

CoAP responses use non-successful response codes MUST NOT contain a DNS response and MUST only be used on errors in the CoAP layer or when a request does not fulfill the requirements of the DoC protocol.

Communication errors with a DNS server (e.g., timeouts) SHOULD be indicated by including a SERVFAIL DNS response in a successful CoAP response.

A DoC client might try to repeat a non-successful exchange unless otherwise prohibited. The DoC client might also decide to repeat a non-successful exchange with a different URI, for instance, when the response indicates an unsupported Content-Format.

4.3.2. Support of CoAP Caching

The DoC server MUST ensure that any sum of the Max-Age value of a CoAP response and any TTL in the DNS response is less or equal to the corresponding TTL received from an upstream DNS server. This also includes the default Max-Age value of 60 seconds (see [RFC7252], section 5.10.5) when no Max-Age option is provided. The DoC client MUST then add the Max-Age value of the carrying CoAP response to all TTLs in a DNS response on reception and use these calculated TTLs for the associated records.

The RECOMMENDED algorithm to assure the requirement for the DoC is to set the Max-Age option of a response to the minimum TTL of a DNS response and to subtract this value from all TTLs of that DNS response. This prevents expired records unintentionally being served from an intermediate CoAP cache. Additionally, it allows for the ETag value for cache validation, if it is based on the content of the response, not to change even if the TTL values are updated by an upstream DNS cache. If only one record set per DNS response is assumed, a simplification of this algorithm is to just set all TTLs in the response to 0 and set the TTLs at the DoC client to the value of the Max-Age option.

4.3.3. Examples

The following examples illustrate the replies to the query " IN AAAA record", recursion turned on. Successful responses carry one answer record including address 2001:db8:1::1:2:3:4 and TTL 58719.

A successful response:

2.05 Content
Content-Format: application/dns-message
Max-Age: 58719
Payload: 00 00 81 a0 00 01 00 01 00 00 00 00 07 65 78 61 [binary]
         6d 70 6c 65 03 6f 72 67 00 00 1c 00 01 c0 0c 00 [binary]
         1c 00 01 00 01 37 49 00 10 20 01 0d b8 00 01 00 [binary]
         00 00 01 00 02 00 03 00 04                      [binary]

When a DNS error (SERVFAIL in this case) is noted in the DNS response, the CoAP response still indicates success:

2.05 Content
Content-Format: application/dns-message
Payload: 00 00 81 a2 00 01 00 00 00 00 00 00 07 65 78 61 [binary]
         6d 70 6c 65 03 6f 72 67 00 00 1c 00 01          [binary]

When an error occurs on the CoAP layer, the DoC server SHOULD respond with an appropriate CoAP error, for instance "4.15 Unsupported Content-Format" if the Content-Format option in the request was not set to "application/dns-message" and the Content-Format is not otherwise supported by the server.

5. CoAP/CoRE Integration

5.1. DNS Push

DNS Push requires additional overhead, which conflicts with constrained resources, This is the reason why it is RECOMMENDED to use CoAP Observe [RFC7641] instead of DNS Push in the DoC domain.

If the CoAP request indicates that the DoC client wants to observe a resource record, a DoC server MAY use a DNS Subscribe message [RFC8765] instead of a classic DNS query to fetch the information on behalf of a DoC client. If this is not supported by the DoC server, it MUST act as if the resource were not observable.

Whenever the DoC server receives a DNS Push message [RFC8765] from the DNS infrastructure for an observed resource record, the DoC server sends an appropriate Observe response to the DoC client.

If no more DoC clients observe a resource record for which the DoC server has an open subscription, the DoC server MUST use a DNS Unsubscribe message [RFC8765] to close its subscription to the resource record as well.


It is RECOMMENDED to carry DNS messages end-to-end encrypted using OSCORE [RFC8613]. The exchange of the security context is out of scope of this document.

6. Considerations for Unencrypted Use

While not recommended, DoC can be used without any encryption (e.g., in very constrained environments where encryption is not possible or necessary). It can also be used when lower layers provide secure communication between client and server. In both cases, potential benefits of unencrypted DoC usage over classic DNS are e.g. block-wise transfer or alternative CoAP Content-Formats to overcome link-layer constraints. For unencrypted DoC usage the ID field MUST not be set to a fixed value as suggested in Section 4.2.2, but changed with every query.

7. Security Considerations

When using unencrypted CoAP (see Section 6), setting the ID of a DNS message to 0 as specified in Section 4.2.2 opens the DNS cache of a DoC client to cache poisoning attacks via response spoofing. Because of that, this documents requires the ID to be changed with every query when CoAP is not secured (see Section 6).

For encrypted usage with DTLS or OSCORE the impact of a fixed ID on security is limited, as both harden against injecting spoofed responses. Consequently, it is of little concern to leverage the benefits of CoAP caching by setting the ID to 0.

TODO more security

8. IANA Considerations

8.1. New "application/dns-message" Content-Format

IANA is requested to assign CoAP Content-Format ID for the DNS message media type in the "CoAP Content-Formats" sub-registry, within the "CoRE Parameters" registry [RFC7252], corresponding to the "application/dns-message" media type from the "Media Types" registry:

Media-Type: application/dns-message

Encoding: -


Reference: [TBD-this-spec]

8.2. New "core.dns" Resource Type

IANA is requested to assign a new Resource Type (rt=) Link Target Attribute, "core.dns" in the "Resource Type (rt=) Link Target Attribute Values" sub-registry, within the "CoRE Parameters" register [RFC6690].

Attribute Value: core.dns

Description: DNS over CoAP resource.

Reference: [TBD-this-spec] Section 3

9. References

9.1. Normative References

Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, , <>.
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <>.
Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, , <>.
Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, , <>.
Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, , <>.
Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in the Constrained Application Protocol (CoAP)", RFC 7959, DOI 10.17487/RFC7959, , <>.
van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)", RFC 8132, DOI 10.17487/RFC8132, , <>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <>.
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, , <>.
Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, , <>.

9.2. Informative References

Boucadair, M., Reddy.K, T., Wing, D., Cook, N., and T. Jensen, "DHCP and Router Advertisement Options for the Discovery of Network-designated Resolvers (DNR)", Work in Progress, Internet-Draft, draft-ietf-add-dnr-14, , <>.
Bormann, C. and H. Birkholz, "Constrained Resource Identifiers", Work in Progress, Internet-Draft, draft-ietf-core-href-12, , <>.
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <>.
Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, , <>.
Reddy, T., Wing, D., and P. Patil, "DNS over Datagram Transport Layer Security (DTLS)", RFC 8094, DOI 10.17487/RFC8094, , <>.
Hoffman, P. and P. McManus, "DNS Queries over HTTPS (DoH)", RFC 8484, DOI 10.17487/RFC8484, , <>.
Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, , <>.
Pusateri, T. and S. Cheshire, "DNS Push Notifications", RFC 8765, DOI 10.17487/RFC8765, , <>.
Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and P. van der Stok, "Constrained RESTful Environments (CoRE) Resource Directory", RFC 9176, DOI 10.17487/RFC9176, , <>.
Huitema, C., Dickinson, S., and A. Mankin, "DNS over Dedicated QUIC Connections", RFC 9250, DOI 10.17487/RFC9250, , <>.

Appendix A. Reference Implementations

The authors of this document provide two reference implementations, a DoC client implementation available in the IoT operating system RIOT and a DoC server implementation in Python.

Appendix B. Change Log

B.1. Since draft-ietf-core-dns-over-coap-01

  • Specify DoC server role in terms of DNS terminology
  • Clarify communication of DoC to DNS infrastructure is agnostic of the transport
  • Add subsection on how to implement DNS Push in DoC
  • Add appendix on reference implementation

B.2. Since draft-ietf-core-dns-over-coap-00

  • SVGify ASCII art
  • Move section on "DoC Server Considerations" (was Section 5.1) to its own draft (draft-lenders-dns-cns)
  • Replace layer violating statement for CON with statement of fact
  • Add security considerations on ID=0

B.3. Since draft-lenders-dns-over-coap-04

  • Removed change log of draft-lenders-dns-over-coap


The authors of this document want to thank Ben Schwartz and Tim Wicinski for their feedback and comments.

Authors' Addresses

Martine Sophie Lenders
Freie Universität Berlin
Takustrasse 9
D-14195 Berlin
Christian Amsüss
Cenk Gündoğan
Huawei Technologies
Riesstrasse 25
D-80992 Munich
Thomas C. Schmidt
HAW Hamburg
Berliner Tor 7
D-20099 Hamburg
Matthias Wählisch
Freie Universität Berlin
Takustrasse 9
D-14195 Berlin