Relay-supplied options: Relay-Supplied DHCP Options
A DHCPv6 option that lets a relay agent ask the server to pass an option on to the client.
Lemon, T. and Q. Wu, "Relay-Supplied DHCP Options", RFC 6422, DOI 10.17487/RFC6422, December 2011, <https://www.rfc-editor.org/info/rfc6422>.
@misc{rfc6422,
series = {Request for Comments},
number = 6422,
howpublished = {RFC 6422},
publisher = {RFC Editor},
doi = {10.17487/RFC6422},
url = {https://www.rfc-editor.org/info/rfc6422},
author = {T. Lemon and Q. Wu},
title = {{Relay-Supplied DHCP Options}},
pagetotal = 8,
year = 2011,
month = dec,
} RFC text
Contents
Internet Engineering Task Force (IETF) T. Lemon
Request for Comments: 6422 Nominum
Updates: 3315 Q. Wu
Category: Standards Track Huawei
ISSN: 2070-1721 December 2011
Relay-Supplied DHCP Options
Abstract
DHCPv6 relay agents cannot communicate with DHCPv6 clients directly.
However, in some cases, the relay agent possesses some information
that would be useful to the DHCPv6 client. This document describes a
mechanism whereby the DHCPv6 relay agent can provide such information
to the DHCPv6 server, which can, in turn, pass this information on to
the DHCP client.
This document updates RFC 3315 (DHCPv6) by making explicit the
implicit requirement that relay agents not modify the content of
encapsulation payloads as they are relayed back toward clients.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6422.
Copyright Notice
Copyright (c) 2011 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
(http://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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................2
1.1. Requirements Language ......................................3
1.2. Terminology ................................................3
2. Protocol Summary ................................................3
3. Encoding ........................................................3
4. RSOO-Enabled Options ............................................4
5. DHCP Relay Agent Behavior .......................................4
6. DHCP Server Behavior ............................................5
7. Security Considerations .........................................6
8. IANA Considerations .............................................7
9. References ......................................................7
9.1. Normative References .......................................7
9.2. Informative References .....................................7
1. Introduction
The DHCPv6 specification [RFC3315] allows DHCP relay agents to
forward DHCPv6 messages between clients and servers that are not on
the same IPv6 link. In some cases, the DHCP relay agent has
information not available to the DHCP server that would be useful to
provide to a DHCP client. For example, the DHCP client may need to
learn the EAP Re-authentication Protocol (ERP) local domain name
[RFC6440] for use in EAP re-authentication [RFC5296], which is known
to the relay agent but not the server.
The DHCPv6 protocol specification does not provide a mechanism
whereby the relay agent can provide options to the client. This
document extends DHCP with a mechanism that allows DHCP relay agents
to propose options for the server to send to DHCP clients.
This document is not intended to provide a general mechanism for
storing client configuration information in the relay agent. Rather,
it is intended to address specific use cases where only the relay
agent has information needed by the client. This extension is not
applicable to DHCP options in general, but rather provided as a
mechanism for new specifications that require this functionality.
1.1. 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 RFC 2119 [RFC2119].
1.2. Terminology
The following terms and acronyms are used in this document:
o DHCP: Dynamic Host Configuration Protocol Version 6 [RFC3315]
o RSOO: Relay-Supplied Options option
2. Protocol Summary
DHCP clients do not support a mechanism for receiving options from
relay agents -- the relay agent is required to deliver the payload
from the DHCP server to the DHCP client without changing it. In
order for the DHCP relay agent to provide options to the client, it
sends those options to the DHCP server, encapsulated in an RSOO. The
DHCP server can then choose to place those options in the response it
sends to the client.
3. Encoding
In order to supply options for the DHCP server to send to the client,
the relay agent sends an RSOO in the Relay-Forward message. This
option encapsulates whatever options the relay agent wishes to
provide to the DHCPv6 server.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| OPTION_RSOO | option-length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| options...
+-+-+-+-+-+-+-+-+-+-+-+
OPTION_RSOO
Relay-Supplied Options code (66).
option-length
Length of the RSOO.
options
One or more DHCPv6 options.
4. RSOO-Enabled Options
The RSOO MUST NOT contain any option that is not specifically called
out as an RSOO-enabled option. Specifications that describe RSOO-
enabled options MUST reference this specification, and MUST state
that the option they define is RSOO-enabled. No DHCP option
specified prior to the issuance of this specification is RSOO-
enabled.
A current list of RSOO-enabled options can be found in the list
titled "Options Permitted in the Relay-Supplied Options Option"
maintained at http://www.iana.org/.
DHCP option specifications that define RSOO-enabled options MUST add
text similar to the following to their IANA Considerations section;
"random relay option" should be replaced with the name of the option
being defined in the specification:
We request that IANA add the name "random relay option" to the
registry titled "Options Permitted in the Relay-Supplied Options
Option" maintained at http://www.iana.org/.
5. DHCP Relay Agent Behavior
Relay agents MAY include an RSOO in the option payload of a Relay-
Forward message being sent toward a DHCP server. When relaying the
payload of Relay-Reply messages toward clients, relay agents MUST NOT
modify the payload.
Relay agents MUST NOT send non-RSOO-enabled options in the Relay-
Supplied Options option.
In order to allow network administrators to control the flow of RSOO
options onto the network, relay agents that implement the Relay-
Supplied Options option need to have a configuration parameter that
determines whether or not they will relay Relay-Forward messages
containing RSOOs.
Relay agents that have this configuration parameter and that are
configured to disable forwarding of a Relay-Forward message
containing an RSOO MUST silently discard any such message.
Implementations that can be configured in this way MUST examine all
Relay-Forward encapsulations, not just the outer encapsulation.
6. DHCP Server Behavior
DHCP servers that implement this protocol specification MUST examine
each option contained in an RSOO to see if it is an RSOO-enabled
option. DHCP servers MUST silently discard any option contained in
an RSOO that is not RSOO-enabled. DHCP server implementations SHOULD
have an administrator-configurable list of RSOO-enabled options, so
that new RSOO-enabled options do not require software to be updated.
DHCP servers normally construct a list of options that are candidates
to send to the DHCP client, and then construct the DHCP packet
according to Section 17.2.2 of the DHCPv6 specification [RFC3315].
If the server implementing this protocol specification receives an
RSOO, it SHOULD add any options that appear in the RSOO for which it
has no internal candidate to the list of options that are candidates
to send to the DHCP client. The server SHOULD discard any options
that appear in the RSOO for which it already has one or more
candidates.
Aside from the addition of options from the RSOO, the DHCP server
should then construct a DHCP packet as it normally would, and
transmit it to the DHCP client as described in [RFC3315].
DHCP servers may receive multiply-nested Relay-Forward messages
containing conflicting values for options contained in RSOOs in these
messages.
When such a conflict exists, the DHCP server MUST choose no more than
one of these options to forward to the client. The DHCP server MUST
NOT forward more than one of these options to the client.
By default, the DHCP server MUST choose the innermost value -- the
value supplied by the relay agent closest to the DHCP client -- to
forward to the DHCP client.
DHCP server implementations MAY provide other heuristics for choosing
which one of a set of such conflicting options to forward to the
client, as long as the specified behavior is the default behavior.
7. Security Considerations
This document provides a mechanism whereby a relay agent can inject
options into the response the DHCP server sends to the DHCP client.
In currently known use cases -- for example, the ERP Local Domain
Option [RFC6440] -- RSOO-enabled options are options that will only
ever originate on a relay agent, and do not make sense when
originating on a DHCP server.
In the event that some new RSOO-enabled option is specified that can
originate from either the server or the relay agent, this should be
addressed in the Security Considerations section of the document that
specifies the use of that option.
In some environments, there is an interface on one side of which is
the client, and zero or more routers, and on the other side of which
is a network managed by a monolithic or effectively monolithic
administrative entity. Nodes and routers on the client side of the
interface are not controlled by this entity, and are considered
"untrusted". Nodes and routers on the network side of this interface
are considered trusted.
It is possible for a malicious node acting as a relay agent on the
untrusted side of this interface to supply an RSOO containing one or
more RSOO-enabled options that would override the same option or
options that were provided by a relay agent on the trusted side of
the interface.
In environments where this is a possibility, network administrators
are advised to use relay agents that are capable of dropping Relay-
Forward messages containing the RSOO, and are advised to configure
those relay agents to drop such messages.
Note, however, that this will only be effective if the message from
the DHCP server to the DHCP client is authenticated as specified in
Section 21 of [RFC3315], or using some similar mechanism. Without
this authentication, the malicious node on the untrusted portion of
the network can simply modify the DHCP server's response in transit
back to the DHCP client, and there is no way for the client to detect
that this has happened.
8. IANA Considerations
IANA has assigned one new DHCPv6 option code from the registry of
DHCP Option Codes maintained at http://www.iana.org/. The option
code 66 (OPTION_RSOO) has been assigned to the Relay-Supplied Options
option.
IANA has created a new registry on the same assignments page, titled
"Options Permitted in the Relay-Supplied Options Option". This
registry will enumerate the set of all code points from the DHCP
Option Codes table for options that may appear in the RSOO. Options
may be added to this list after IETF Review [RFC5226]. When adding
options to the list, please ensure that the description for the code
added matches the description in the DHCP Option Codes table for that
code. Option codes that have not been requested to be added
according to the stated procedure should not be mentioned at all in
the table, and should not be listed as "reserved" or "unassigned".
IETF Review should include careful consideration of the security
implications of allowing a relay agent to provide a value for the
option being considered for addition to this registry. In the case
where an IETF working group chartered to review DHCP protocol
extensions exists, it is not sufficient for some other working group
to review the registry addition.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins,
C., and M. Carney, "Dynamic Host Configuration Protocol
for IPv6 (DHCPv6)", RFC 3315, July 2003.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
9.2. Informative References
[RFC5296] Narayanan, V. and L. Dondeti, "EAP Extensions for EAP
Re-authentication Protocol (ERP)", RFC 5296, August 2008.
[RFC6440] Zorn, G., Wu, Q., and Y. Wang, "The EAP Re-authentication
Protocol (ERP) Local Domain Name DHCPv6 Option", RFC 6440,
December 2011.
Authors' Addresses
Ted Lemon
Nominum
2000 Seaport Blvd.
Redwood City, CA 94063
USA
Phone: +1 650 381 6000
EMail: mellon@nominum.com
Qin Wu
Huawei Technologies Co., Ltd.
101 Software Avenue, Yuhua District
Nanjing, Jiangsu 210012
China
Phone: +86-25-56623633
EMail: sunseawq@huawei.com
ISO Plain Language
On this page
§1Introduction
The DHCPv6 specification of RFC 3315 allows DHCP relay agents to forward DHCPv6 messages between clients and servers that are not on the same IPv6 link. In some cases the relay agent has information that is not available to the DHCP server but that would be useful to provide to the client. For example, the DHCP client may need to learn the EAP Re-authentication Protocol local domain name of RFC 6440, used for EAP re-authentication under RFC 5296, which is known to the relay agent but not to the server.
The DHCPv6 protocol specification does not provide a mechanism whereby the relay agent can provide options to the client. This document extends DHCP with a mechanism that allows relay agents to propose options for the server to send to DHCP clients.
The RFC is careful about its scope. It is not intended to provide a general mechanism for storing client configuration information in the relay agent. It is intended to address specific use cases where only the relay agent has information needed by the client. The extension is not applicable to DHCP options in general, but is provided as a mechanism for new specifications that require this functionality.
This is a narrow extension, not a general way to configure clients from a relay. Each option has to be named one at a time as allowed to travel this way, and no existing DHCPv6 option is.
§3Encoding
To supply options for the server to send to the client, the relay agent sends a Relay-Supplied Options option, abbreviated RSOO, in the Relay-Forward message. That option encapsulates whatever options the relay agent wishes to provide to the DHCPv6 server.
The option has three parts. The OPTION_RSOO field carries the Relay-Supplied Options code, 66. The option-length field carries the length of the RSOO. The options field carries one or more DHCPv6 options.
The relay wraps the options it wants to offer in a single DHCPv6 option with the number 66. The server sees that wrapper and knows where to look inside it.
| Field | Name | Size | Value | Description |
|---|---|---|---|---|
OPTION-CODE | OPTION_RSOO | 2 bytes | 66 | The Relay-Supplied Options option code. |
OPTION-LENGTH | option-length | 2 bytes | Length of the RSOO. | |
OPTIONS | options | 4 bytes | One or more DHCPv6 options that the relay agent wishes to provide to the server. The number of bytes is variable. |
§4Which Options May Travel This Way
The RSOO must not contain any option that is not specifically called out as an RSOO-enabled option. Specifications that describe RSOO-enabled options must reference this specification and must state that the option they define is RSOO-enabled. No DHCP option specified prior to the issuance of this specification is RSOO-enabled.
A current list of RSOO-enabled options is kept by IANA in the registry titled Options Permitted in the Relay-Supplied Options Option. DHCP option specifications that define RSOO-enabled options must add text to their IANA Considerations section asking IANA to add the name of the option to that registry, in place of the words random relay option in the template the RFC gives.
Only options that have been explicitly approved for this path may be put in the wrapper. The list of approved ones is kept by IANA, and a new option has to be added there before a relay may send it.
- Only opted-in optionsAn RSOO must not contain any option that is not specifically called out as RSOO-enabled.
- No existing options qualifyNo DHCP option specified before this document is RSOO-enabled.
- IANA keeps the listThe permitted options are the ones in the IANA registry titled Options Permitted in the Relay-Supplied Options Option.
- New specifications must say soA specification defining an RSOO-enabled option must reference this document and state that the option is RSOO-enabled.
§5DHCP Relay Agent Behavior
Relay agents may include an RSOO in the option payload of a Relay-Forward message being sent toward a DHCP server. When relaying the payload of Relay-Reply messages toward clients, relay agents must not modify the payload. Relay agents must not send non-RSOO-enabled options in the Relay-Supplied Options option.
To allow network administrators to control the flow of RSOO options onto the network, relay agents that implement the Relay-Supplied Options option need a configuration parameter that determines whether they relay Relay-Forward messages containing RSOOs. A relay agent that has this parameter and is configured to disable forwarding of a Relay-Forward message containing an RSOO must silently discard any such message. Implementations that can be configured in this way must examine all Relay-Forward encapsulations, not just the outer one, because a relay agent may itself be nested inside another relay agent's message.
The relay can be told not to pass these messages on at all, and when it is told that it must drop them without telling anyone. It has to look inside nested relay messages too, not just the outermost one.
§6DHCP Server Behavior
DHCP servers that implement this specification must examine each option contained in an RSOO to see whether it is an RSOO-enabled option, and must silently discard any option in an RSOO that is not. Server implementations should have an administrator-configurable list of RSOO-enabled options, so that new RSOO-enabled options do not require the software to be updated.
DHCP servers normally construct a list of options that are candidates to send to the client, and then construct the DHCP packet according to Section 17.2.2 of the DHCPv6 specification. If the server receives an RSOO it should add any options in it for which it has no internal candidate to that list of candidates. It should discard any option in the RSOO for which it already has one or more candidates. Aside from that addition, the server then constructs the DHCP packet as it normally would and transmits it to the client.
DHCP servers may receive multiply-nested Relay-Forward messages containing conflicting values for options contained in RSOOs. When such a conflict exists the server must choose no more than one of those options to forward to the client, and must not forward more than one. By default the server must choose the innermost value, the value supplied by the relay agent closest to the DHCP client. Server implementations may provide other heuristics for choosing which one of a set of conflicting options to forward, as long as the specified behaviour is the default.
The server checks each relayed option against its approved list and drops anything not on it. It uses a relayed option only when it has nothing of its own for that option. When two relays in a chain supply different values for the same option, the server picks one, and by default that is the one from the relay nearest the client.
- SolicitThe client asks for configuration.
- Relay-Forward with RSOOThe relay puts an RSOO option in the message, carrying the option it wants the client to receive.
- Relay-ReplyThe server checks the relayed option against its approved list and adds it to the reply.
- AdvertiseThe relay forwards the server's payload unchanged.
| Situation | What the server does |
|---|---|
| Option in the RSOO that is not RSOO-enabled | Silently discards it. |
| Option in the RSOO for which the server has no candidate | Adds it to the list of options to send to the client. |
| Option in the RSOO for which the server already has candidates | Discards the relayed option. |
| Conflicting values from nested Relay-Forward messages | Chooses no more than one, and by default the innermost value, from the relay closest to the client. |
§7Security Considerations
This document provides a mechanism whereby a relay agent can inject options into the response the DHCP server sends to the DHCP client. In the currently known use cases, such as the ERP Local Domain Option of RFC 6440, RSOO-enabled options are options that will only ever originate on a relay agent and do not make sense when originating on a DHCP server. If some new RSOO-enabled option is specified that can originate from either the server or the relay agent, the RFC says this should be addressed in the security considerations of the document that specifies the use of that option.
In some environments there is an interface with a client and zero or more routers on one side, and a network managed by a monolithic or effectively monolithic administrative entity on the other. The nodes and routers on the client side are not controlled by that entity and are considered untrusted, while those on the network side are considered trusted.
It is possible for a malicious node acting as a relay agent on the untrusted side to supply an RSOO containing options that would override the same options provided by a relay agent on the trusted side. Where this is possible, network administrators are advised to use relay agents capable of dropping Relay-Forward messages containing the RSOO, and to configure them to do so. The RFC notes that this is only effective if the message from the DHCP server to the client is authenticated as specified in Section 21 of RFC 3315, or by some similar mechanism. Without that authentication, the malicious node can simply modify the server's response in transit back to the client, and there is no way for the client to detect it.
A relay near the client is under the control of whoever owns the client, not the network operator, and it could lie about an option. The advice is to configure relays to drop these messages, and to authenticate the server's reply, because otherwise a modified reply cannot be detected at all.
§8IANA Considerations
IANA has assigned one new DHCPv6 option code from the registry of DHCP Option Codes. The option code 66, OPTION_RSOO, has been assigned to the Relay-Supplied Options option.
IANA has created a new registry on the same assignments page, titled Options Permitted in the Relay-Supplied Options Option. This registry enumerates the set of all code points from the DHCP Option Codes table for options that may appear in the RSOO. Options may be added to the list after IETF Review under the process of RFC 5226. When adding options, the description for the code added must match the description in the DHCP Option Codes table for that code, and option codes that have not been requested to be added should not be mentioned at all in the table, and should not be listed as reserved or unassigned.
IETF Review should include careful consideration of the security implications of allowing a relay agent to provide a value for the option being considered for addition to the registry. Where an IETF working group chartered to review DHCP protocol extensions exists, it is not sufficient for some other working group to review the registry addition.
IANA keeps two lists here: the DHCPv6 option numbers, and the subset of them allowed inside the relay-supplied wrapper. Adding to the second list needs an IETF review that looks at the security consequences, not just a name check.