Internet DRAFT - draft-herbert-udp-magic-numbers
draft-herbert-udp-magic-numbers
INTERNET-DRAFT T. Herbert
Intended Status: Informational Facebook
Expires: April 17, 2016 L. Yong
Huawei USA
October 15, 2015
UDP Magic Numbers
draft-herbert-udp-magic-numbers-01
Abstract
This specification defines magic numbers in UDP which allow a node to
determine or confirm the protocol contained in a UDP payload. This is
primarily applicable for encapsulation and transport protocols
encapsulated within UDP where intermediate devices, such as middle
boxes, need to parse these protocols for providing service. Magic
numbers can also be used to multiplex different UDP encapsulated
protocols over the same UDP port.
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
Copyright and License Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
Herbert, Yong Expires April 17, 2016 [Page 1]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
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 . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Magic number format . . . . . . . . . . . . . . . . . . . . . . 4
2.1 Magic value . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Protocol types . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Magic number checksum . . . . . . . . . . . . . . . . . . . 6
3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1 End hosts . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1.1 Required magic numbers . . . . . . . . . . . . . . . . . 6
3.1.2 Optional magic numbers . . . . . . . . . . . . . . . . . 6
3.1.3 Use with DTLS . . . . . . . . . . . . . . . . . . . . . 7
3.2 Intermediate devices . . . . . . . . . . . . . . . . . . . . 7
4 Security Considerations . . . . . . . . . . . . . . . . . . . . 8
5 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
6 References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1 Normative References . . . . . . . . . . . . . . . . . . . 8
6.2 Informative References . . . . . . . . . . . . . . . . . . 8
Appendix A: Example of creating a UDP magic number . . . . . . . . 10
Appendix B: Checking magic numbers . . . . . . . . . . . . . . . . 10
B.1 Matching a single magic number . . . . . . . . . . . . . . . 10
B.2 Matching against a set of magic numbers . . . . . . . . . . 11
B.3 Magic number validation . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12
Herbert, Yong Expires April 17, 2016 [Page 2]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
1 Introduction
Several transport and encapsulation protocols have been defined to be
encapsulated within UDP [RFC0768]. In this model, the payload of a
UDP packet contains a protocol header and payload for an encapsulated
protocol. Transport protocols encapsulated in UDP include QUIC
[QUIC], SCTP-in-UDP [RFC6951], and SPUD [I-D.hildebrand-spud-
prototype]. Encapsulation protocols include Geneve [I-D.ietf-nvo3-
geneve], VXLAN-GPE [I-D.ietf-nvo3-vxlan-gpe], GUE [I-D.ietf-nvo3-
gue], MPLS-in-UDP [RFC7510], and GRE-in-UDP [I-D.ietf-tsvwg-gre-in-
udp-encap]. For various reasons, intermediate devices in a network
may want to parse these protocols. For instance, a middlebox would
need to parse an encapsulated transport protocol to implement a
stateful firewall. To parse the encapsulated protocol in a UDP
packet, a node must positively identify the encapsulated protocol.
The destination UDP port number is commonly used to interpret the
contents of a UDP payload, however this is problematic in
intermediate devices for several reasons:
- Port numbers can only be correctly interpreted by the endpoints.
Interpretation by intermediate devices in the network may be
incorrect ([RFC7605]]).
- Encapsulation and transport protocols will usually have assigned
UDP ports, but they are not restricted to use only those.
- UDP encapsulated protocols may use a "substrate" protocol header
as espoused in SPUD. Use of a substrate header may be common
across several port numbers. Configuring each network device for
each port that uses the substrate could be cumbersome.
This specification describes UDP magic numbers which allows network
nodes to identify UDP encapsulated protocols without relying solely
on UDP port numbers. A UDP magic number is a protocol specific,
constant value which is logically inserted between the UDP header and
the encapsulated protocol header. If a node matches the magic number
in a packet to a known protocol's magic number, then it can parse the
encapsulated payload per the matched protocol. Each UDP encapsulated
protocol uses a different magic number which allows multiplexing
multiple encapsulated protocols over the same UDP port.
Note that the use of magic numbers is inherently probabilistic. It is
possible that a UDP packet may have a payload that inadvertently
matches a magic number. The magic number is defined to minimize the
probability of this occurring (1/2^^64 assuming that UDP data has a
random distribution), nevertheless the probability is non-zero. The
consequences of incorrectly matching a UDP packet should be
Herbert, Yong Expires April 17, 2016 [Page 3]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
considered for each UDP encapsulated protocol. An encapsulated
protocol may include its own verification to ensure correct
interpretation.
The use of magic numbers to identify UDP encapsulated protocols was
specified in the SPUD prototype protocol ([I-D.hildebrand-spud-
prototype]) and in "Session Traversal Utilities for NAT (STUN)"
([RFC5389]). This proposal generalizes the concept.
1.1 Terminology
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].
2 Magic number format
The UDP magic number is a sixty-four bit value that includes a fixed
constant, an encapsulated protocol type, and a checksum. The magic
number within a UDP packet is diagrammed below.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source port | Destination port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length | Checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic value = 0xffd871a2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Xor'ed protocol | Xor'ed checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Encapsulated protocol ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The fields of the magic number are:
o Magic value: A fixed constant of 0xffd871a2. This value is the
same for all encapsulated protocol types.
o Xor'ed protocol: Indicates the protocol type of the encapsulated
protocol. The value in the field is a protocol type number
exclusive or'ed with 0x36b4.
o Xor'ed Checksum: Indicates the standard one's complement
Herbert, Yong Expires April 17, 2016 [Page 4]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
checksum over the magic number (including the Magic value and
Xor'ed Protocol fields). The value in this field is the
calculated checksum exclusive or'ed with 0x5ce9.
o Encapsulated protocol: This contains the header and payload of
the encapsulated protocol. The type for the protocol is
indicated in the Xor'ed protocol field.
2.1 Magic value
The first byte of the Magic value field is 0xff and the other three
bytes are a randomly chosen constant.
For UDP encapsulated protocols that allow magic number use to be
optional, the magic number must be clearly distinguishable from a
valid header. Each such protocol must declare that a header which
would match the associated magic number is invalid. The value of 0xff
as the first byte in the magic number was chosen as a likely value
that would indicate an invalid header. It is common that the first
byte of a protocol header contains a version number, and most
protocols have not gotten past version zero. So if a magic number is
received by a node that does not yet support magic numbers, the UDP
payload would likely be interpreted as a protocol header with a bad
version number; this should result in dropping the packet and not
misinterpreting it. In this way, the use of magic numbers can be
enabled for many existing protocols with forward compatibility.
2.2 Protocol types
Protocol types can generally refer to any encapsulation, transport,
substrate, or application specific protocol that is encapsulated in
UDP for which intermediate devices might need to parse. A protocol
type number is encoded in UDP magic numbers to allow intermediate
devices to distinguish different payload types while still using a
common magic number format.
Protocol types are indicated by sixteen bits numbers, and the space
is divided into three regions.
Numbers 0-49151 are reserved to mirror the assigned UDP port
number space. If a port number is assigned to a UDP encapsulated
protocol, that same number can be used as the protocol type
number. This is allowed for convenience, there is no required
correlation between protocol type numbers and UDP port numbers.
Numbers 49152-57343 are reserved for assigned protocol types.
Numbers 57344-65535 are reserved for private protocol types.
Herbert, Yong Expires April 17, 2016 [Page 5]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
The Xor'ed protocol field in a magic number is a protocol type number
exclusive or'ed with 0x36b4.
2.3 Magic number checksum
The magic number checksum is calculated as the standards one
complement checksum computed over the sixty-four bit magic number
where the Xor'ed checksum field is set to zero for the purposes of
calculation. The checksum calculation covers the Magic value and the
Xor'ed protocol fields. The Xor'ed checksum field is set to the
result of the calculation exclusive or'ed with 0x5ce9.
Note that the magic number checksum is performed over constant fields
and is itself a constant value per protocol type. An implementation
should not need to perform this calculation when processing packets.
Appendix A demonstrates how the checksum is applied to create a magic
number constant for Generic UDP Encapsulation.
The magic number checksum may be used to validate the presence of a
well formed UDP magic number. This is demonstrated in Appendix B.
3 Usage
This section describes the processing of UDP magic numbers on end
hosts and intermediate devices.
3.1 End hosts
The use of UDP magic numbers is enabled on a per port basis. Magic
numbers may be required for every UDP packet sent on a port, or may
be optional. If a UDP port is assigned to a single protocol, the
magic number in packets sent to that port is the one assigned to the
protocol. If different encapsulated protocols are multiplexed on the
same UDP port, magic numbers for those protocols will be used.
3.1.1 Required magic numbers
If magic numbers are required for a UDP port, a sender must set the
magic number in any packets sent to the destination port. A receiver
must check for a valid magic number. If the magic number is valid,
that is the Magic value is correct and the protocol type is supported
by the receiver for the port, then the packet is accepted. Otherwise,
the magic number is not matched so the packet is dropped.
3.1.2 Optional magic numbers
When magic numbers are optional for a UDP port, a receiver must check
if a magic number is present in a received packet. If a magic number
Herbert, Yong Expires April 17, 2016 [Page 6]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
is matched for a protocol type supported by the receiver, then the
packet must be accepted and the Encapsulated protocol in the packet
is processed according to the protocol type. If the magic number is
not matched, the packet is still accepted and the UDP payload is
processed as a protocol type implied by the port number.
If it is not feasible in a protocol to distinguish a magic number
from a valid header (MPLS-in-UDP for instance), UDP magic numbers
cannot be optional on the protocol's port number. They can be used on
a separate port number for which magic numbers would be required.
3.1.3 Use with DTLS
UDP magic numbers are intended to occupy the first bytes of the UDP
payload to facilitate interpretation at middleboxes. When they are
used with DTLS [RFC6347], the magic number must precede the DTLS
headers. The protocol type in the magic number would refer to the
payload type contained in DTLS.
3.2 Intermediate devices
Intermediate devices may match magic numbers in two ways:
- Match both the destination port and magic numbers associated
with the port.
- Match magic numbers across a range (possibly all) of ports.
Matching both the port and magic number is recommended. This is
feasible in cases where a UDP encapsulated protocol has an assigned
port number. Matching the port number and magic number significantly
reduces the possibility of misinterpreting a packet.
Matching just the magic number and not a port may be done when UDP
encapsulated protocols are used on unassigned ports, or configuring
port numbers on intermediate devices is prohibitive.
In either case, if a middlebox is able to match a magic number it may
parse the encapsulated payload of the packet for the associated
protocol.
If a middle box does not match a magic number for a packet it should
follow default processing for UDP packets. If magic numbers are known
to be required for a port, a middlebox may perform some alternative
processing when the magic number is not present. This alternative
processing should not be more restrictive than had the packet been
sent to another arbitrary UDP port. In particular, if UDP packets for
other ports would not be dropped, failure to match a magic number
Herbert, Yong Expires April 17, 2016 [Page 7]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
should not result in the packet being dropped.
4 Security Considerations
UDP magic numbers are not a security mechanism and should not
increase security risk.
5 IANA Considerations
IANA will be requested to create a "UDP Magic Number Protocol Type"
registry to allocate protocol types. This shall be a registry of 16-
bit values along with descriptive strings. The allocation ranges are
described in section 2.2.
6 References
6.1 Normative References
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
August 1980, <http://www.rfc-editor.org/info/rfc768>.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI
10.17487/RFC2119, March 1997, <http://www.rfc-
editor.org/info/rfc2119>.
[RFC1776] Crocker, S., "The Address is the Message", RFC 1776, DOI
10.17487/RFC1776, April 1 1995, <http://www.rfc-
editor.org/info/rfc1776>.
[TRUTHS] Callon, R., "The Twelve Networking Truths", RFC 1925, DOI
10.17487/RFC1925, April 1 1996, <http://www.rfc-
editor.org/info/rfc1925>.
6.2 Informative References
[RFC6951] Tuexen, M. and R. Stewart, "UDP Encapsulation of Stream
Control Transmission Protocol (SCTP) Packets for End-Host
to End-Host Communication", RFC 6951, May 2013,
<http://www.rfc-editor.org/info/rfc6951>.
[RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing,
"Session Traversal Utilities for NAT (STUN)", RFC 5389,
October 2008, <http://www.rfc-editor.org/info/rfc5389>.
[QUIC] Roskind, J., "QUIC: Multiplexed Stream Transport Over UDP",
http://www.ietf.org/proceedings/88/slides/slides-88-
Herbert, Yong Expires April 17, 2016 [Page 8]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
tsvarea-10.pdf
[I-D.hildebrand-spud-prototype] Hildebrand, J. and Trammell, B.
"Substrate Protocol for User Datagrams (SPUD) Prototype",
draft-hildebrand-spud-prototype-03 (work in preogress),
March 2015.
[I-D.ietf-nvo3-geneve] Gross, J., Sridhar, T., Garg, P., Wright, C.,
Ganga, I., Agarwal, P., Duda, K., Dutt, D., and J. Hudson,
"Geneve: Generic Network Virtualization Encapsulation",
draft-ietf-nvo3-geneve-00, May 2015.
[I-D.ietf-nvo3-vxlan-gpe] Quinn, P., Manur, R., Kreeger, L., Lewis,
D., Maino, F., Smith, M., Agarwal, P., Yong, L., Xu, X,
Elzur, U., Garg, P., and Melman, D. "Generic Protocol
Extension for VXLAN" draft-ietf-nvo3-vxlan-gpe-00draft-
quinn-vxlan-gpe-00, February 2015
[I-D.ietf-nvo3-gue] Herbert, T., Yong, L., and Zia, O., "Generic UDP
Encapsulation", draft-ietf-nvo3-gue-01 (work in progress),
June 2015.
[RFC7510] Xu, X., Sheth, N., Yong, L., Callon, R., and D. Black,
"Encapsulating MPLS in UDP", RFC 7510, April 2015,
<http://www.rfc-editor.org/info/rfc7510>.
[I-D.ietf-tsvwg-gre-in-udp-encap] Crabbe, E., Yong, L., Xu,
X., and Herbert, T. "GRE-in-UDP Encapsulation", draft-ietf-
tsvwg-gre-in-udp-encap-07, July 2015
[RFC7605] Touch, J., "Recommendations on Using Assigned Transport
Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605,
August 2015, <http://www.rfc-editor.org/info/rfc7605>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, January 2012,
<http://www.rfc-editor.org/info/rfc6347>.
[EVILBIT] Bellovin, S., "The Security Flag in the IPv4 Header",
RFC 3514, DOI 10.17487/RFC3514, April 1 2003,
<http://www.rfc-editor.org/info/rfc3514>.
[RFC5513] Farrel, A., "IANA Considerations for Three Letter
Acronyms", RFC 5513, DOI 10.17487/RFC5513, April 1 2009,
<http://www.rfc-editor.org/info/rfc5513>.
[RFC5514] Vyncke, E., "IPv6 over Social Networks", RFC 5514, DOI
10.17487/RFC5514, April 1 2009, <http://www.rfc-
Herbert, Yong Expires April 17, 2016 [Page 9]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
editor.org/info/rfc5514>.
Appendix A: Example of creating a UDP magic number
This section demonstrates how a magic can be created for a UDP
encapsulated protocol. For this example we consider Generic UDP
Encapsulation (GUE), and assume that the assigned port number is used
as the protocol type number.
The assigned port number for GUE in 6080 or 0x17c0 in hexadecimal. So
the value of the Xor'ed protocol field is:
0x17c0 ^ 0x36b4 = 0x2174
To compute the magic checksum we first sum the words of the Magic
value and the Xor'ed protocol field value computed above:
0xffd8 + 0x71a2 + 0x2174 = 0x192ee
The result is folded and then complemented:
(0x92ee + 1) ^ 0xffff = 0x6d10
So the value in the Xor'ed checksum field is:
0x6d10 ^ 0x5ce9 = 0x31f9
Thus the full 64 bit magic number value for GUE is:
0xffd871a2:0x217431f9
Appendix B: Checking magic numbers
This section provides some guidelines for how to check magic numbers.
B.1 Matching a single magic number
When a port supports precisely one protocol type there is only one
magic number to check. This will be a common case at a receiver where
magic numbers are enabled for encapsulated protocols that have
assigned ports. Receiver processing in pseudo code may be:
dataptr = UDP_payload_ptr
good_magic = false
PROTO_MAGIC_NUMBER = Pre computed 64 bit value for protocol type
if (UDP_payload_length >= 8 &&
memcmp(UDP_payload_ptr, PROTO_MAGIC_NUMBER, 8) == 0) {
Herbert, Yong Expires April 17, 2016 [Page 10]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
/* Magic number matched, skip it for further processing */
dataptr += 8
good_magic = true
}
if (good_magic || magic_numbers_are_optional)
process_packet(dataptr)
else
/* Handle bad packet */
B.2 Matching against a set of magic numbers
A host needs to check against a set of magic numbers when different
encapsulated protocols are multiplexed over a single port, and an
intermediate device checks against a set when matching magic numbers
across a range of ports. In either case, the typical method is to
check the first four bytes of the UDP payload against the constant
magic number value. If this is a match then the protocol type number
is extracted and a lookup is performed to find a context. If a
context is found, the checksum field in the packet is compared
against a precomputed value in the context. In pseudo code this is:
dataptr = UDP_payload_ptr;
good_magic = false;
if (UDP_payload_length >= 8 &&
*(u32 *)UDP_payload_ptr == 0xffd871a2) {
proto = *(u16 *)(UDP_payload_ptr + 4) ^ 0x36b4
checksum = *(u16 *)(UDP_payload_ptr + 6)
ctx = protocol_lookup(proto)
if (ctx && checksum == ctx->checksum) {
/* Protocol found and matched */
good_magic = true
dataptr += 8;
}
}
if (good_magic)
process_as_protocol(dataptr, proto);
else
/* Handle bad packet */
B.3 Magic number validation
A node can validate that a magic number is well formed for any
protocol. This requires checking the Magic value is correct and
verifying the checksum. In pseudo code this would be:
Herbert, Yong Expires April 17, 2016 [Page 11]
INTERNET DRAFT UDP Magic Numbers October 15, 2015
good_magic = false
u16 checksum(start, len) /* Checksum function */
if (UDP_payload_length >= 8 &&
*(u32 *)UDP_payload_ptr == 0xffd871a2) {
csum = checksum(UDP_payload_ptr, 6)
if (csum ^ 0x5ce9 == *(u16 *)(UDP_payload_ptr + 6))
good_magic = true
}
Authors' Addresses
Tom Herbert
Facebook
1 Hacker Way
Menlo Park, CA
US
EMail: tom@herbertland.com
Lucy Yong
Huawei USA
5340 Legacy Dr.
Plano, TX 75024
US
Email: lucy.yong@huawei.com
Herbert, Yong Expires April 17, 2016 [Page 12]
