RFC 3397

🎀 Part 1 of 2! Sections 1 to 3 are here, and Section 4 onward comes next. ✨

Dynamic Host Configuration Protocol (DHCP) Domain Search Option 💖

okay so RFC 3397 is giving "small spec, big vibes" 🦋 It's a Standards Track doc from November 2002, written by B. Aboba (Microsoft) and S. Cheshire (Apple Computer, Inc.), and it's published under the Network Working Group. The title block doesn't list any RFCs that it obsoletes or updates, so it's standing on its own. 🧚

Status of this Memo ✨

This is a standards track protocol for the Internet community 🌸 It also asks for discussion and suggestions for improvements. For the standardization state and status of this protocol, go check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 💅

Copyright Notice 🫶

Copyright (C) The Internet Society (2002). All Rights Reserved.

Abstract 🌈

This doc defines a brand new Dynamic Host Configuration Protocol (DHCP) option 💜 The server sends it to the client to specify the domain search list that gets used when resolving hostnames with DNS. It's giving "one option to rule the search list" 👑

Table of Contents 🍓

1.  Introduction ................................................  2
     1.1 Terminology ............................................  2
     1.2 Requirements Language ..................................  2
2.  Domain Search Option Format .................................  2
3.  Example .....................................................  3
4.  Security Considerations .....................................  4
5.  Normative References ........................................  5
6.  Informative References ......................................  5
7.  IANA Considerations .........................................  6
8.  Acknowledgments .............................................  6
9.  Intellectual Property Statement .............................  6
10. Authors' Addresses ..........................................  7
11. Full Copyright Statement ....................................  8

1. Introduction ✨

okay so DHCP [RFC2131] is the thing that gives hosts their configuration 🎀 [RFC2132] and [RFC2937] let DHCP servers pass name service configuration info over to DHCP clients. Sometimes it's really useful for the client to get the domain search list too 🦋 That's where this doc comes in: it defines a new DHCP option that the server passes to the client, specifying the domain search list used when resolving hostnames with DNS. This option applies only to DNS. It does not apply to other name resolution mechanisms, so don't try to make it do that, bestie 🙈

1.1. Terminology 💅

This doc uses the following terms:

DHCP client A DHCP client or "client" is an Internet host using DHCP to obtain configuration parameters such as a network address.

DHCP server A DHCP server or "server" is an Internet host that returns configuration parameters to DHCP clients.

1.2. Requirements Language 🔥

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. These are the official BCP 14 words, so they're the ones that carry the weight 💜

2. Domain Search Option Format 🧚

The code for this option is 119 🌸

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     119       |     Len       |         Searchstring...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                     Searchstring...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

In that diagram, Searchstring is a string that specifies the searchlist. If the searchlist is longer than the max a single option can hold (255 octets), then multiple options MAY be used. The way to do that is described in "Encoding Long Options in the Dynamic Host Configuration Protocol (DHCPv4)" [RFC3396] 🎀

Now here's the compact-encoding bit, and it's a little spicy 🌶️ Searchstrings in the searchlist MUST be concatenated and encoded using the technique from section 4.1.4 of "Domain Names - Implementation And Specification" [RFC1035]. In that scheme, a whole domain name, or a list of labels at the end of a domain name, gets swapped out for a pointer to an earlier occurrence of the same name. It's complicated, I know 😭 but it's worth it, because DHCP option space is limited, and a domain searchstring will probably repeat the same domain name over and over. So DNS name compression is both useful and likely to work well here 🦋

For this spec, the pointer refers to the offset within the data portion of the DHCP option. That means it doesn't count the option code byte or the option length byte that come before it 💖

If there are multiple Domain Search Options, the data portions of all of them get concatenated together, as specified in "Encoding Long DHCP Options in the Dynamic Host Configuration Protocol (DHCPv4)" [RFC3396]. The pointer then indicates an offset within that whole aggregate block of data 🌈

3. Example 🍓

Here's an example encoding of a search list with "eng.apple.com." and "marketing.apple.com." in it 🧁

+---+---+---+---+---+---+---+---+---+---+---+
|119| 9 | 3 |'e'|'n'|'g'| 5 |'a'|'p'|'p'|'l'|
+---+---+---+---+---+---+---+---+---+---+---+

+---+---+---+---+---+---+---+---+---+---+---+
|119| 9 |'e'| 3 |'c'|'o'|'m'| 0 | 9 |'m'|'a'|
+---+---+---+---+---+---+---+---+---+---+---+

+---+---+---+---+---+---+---+---+---+---+---+
|119| 9 |'r'|'k'|'e'|'t'|'i'|'n'|'g'|xC0|x04|
+---+---+---+---+---+---+---+---+---+---+---+

Notes on that, because they matter:

i. The encoding has been split (just for this example) into three Domain Search Options. All Domain Search Options are logically concatenated into one block of data before the client interprets it 🧚

ii. The encoding of "eng.apple.com." ends with a zero, the null root label, which marks the end of the name, as required by RFC 1035 💅

iii. The encoding of "marketing" (for "marketing.apple.com.") ends with the two-octet compression pointer C004 (hex). That pointer points to offset 4 in the complete aggregated block of Domain Search Option data, where another validly encoded domain name can be found to finish the name ("apple.com.") 🫶

Every search domain name MUST end either with a zero or with a two-octet compression pointer 🔥 If the receiver is partway through decoding a search domain name when it reaches the end of the complete aggregated block of searchlist option data, and it hasn't found a zero or a valid two-octet compression pointer, then the partially read name MUST be discarded as invalid. No half-baked names allowed, periodt 💀

✨ Part 2 covers Section 4 (Security Considerations, which is serious business 👀), the References, IANA Considerations, Acknowledgments, and the rest. Stay tuned, bestie 🎀

9. Intellectual Property Statement ✨

okay so this one is the legal bit, but it's still important bestie 💅 The IETF doesn't say anything about whether any rights (patents, copyrights, that kind of thing) apply to the tech in this doc, or whether you can get a license to use them. It also doesn't claim it went looking for any of those rights. 🙈

If you want the whole process for rights in standards-track and standards-related docs, the IETF's procedures are written up in BCP-11 🌸

Anyone who has claims of rights can get copies from the IETF Secretariat, along with any promises to license stuff, or the results of trying to get a general license or permission for implementers or users of this spec to use those proprietary rights. Lowkey important stuff 👑

The IETF also invites anyone who's interested to tell them about any copyrights, patents, patent applications, or other proprietary rights that might cover tech you'd need to practice this standard. Send that info to the IETF Executive Director 🦋

10. Authors' Addresses 🎀

Here are the people who wrote this one, with their contact details, nothing spicy 💜

Bernard Aboba
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052

Phone: +1 425 706 6605
EMail: bernarda@microsoft.com


Stuart Cheshire
Apple Computer, Inc.
1 Infinite Loop
Cupertino
California 95014
USA

Phone: +1 408 974 3207
EMail: rfc@stuartcheshire.org

11. Full Copyright Statement 🌈

Copyright (C) The Internet Society (2002). All Rights Reserved. 💖

Here's the deal with copying this doc 🫶 You're totally allowed to copy it and share it with others, and you can make derivative works that comment on it, explain it, or help people implement it, and publish and distribute those too, in whole or in part, with no restrictions of any kind. The only catch is that the copyright notice and this paragraph have to stay on all those copies and derivative works.

BUT this document itself can't be modified in any way. So no removing the copyright notice or the references to the Internet Society or other Internet organizations. The exceptions are if you need it for developing Internet standards (then the Internet Standards process copyright procedures have to be followed), or if you need to translate it into languages other than English 🌸

The permissions above are perpetual and won't be revoked by the Internet Society or its successors or assigns. Forever and ever 🧚

This document and the info in it is provided "AS IS", and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 😭

Acknowledgement 🍓

Funding for the RFC Editor function is currently provided by the Internet Society. ✨