--- 1/draft-ietf-intarea-gue-extensions-00.txt 2017-05-18 16:13:11.945476499 -0700 +++ 2/draft-ietf-intarea-gue-extensions-01.txt 2017-05-18 16:13:12.009478040 -0700 @@ -1,22 +1,22 @@ INTERNET-DRAFT T. Herbert Intended Status: Proposed Standard Quantonium -Expires: November 11, 2017 L. Yong +Expires: November 19, 2017 L. Yong Huawei F. Templin Boeing - May 10, 2017 + May 18, 2017 Extensions for Generic UDP Encapsulation - draft-ietf-intarea-gue-extensions-00 + draft-ietf-intarea-gue-extensions-01 Abstract This specification defines a set of the fundamental optional extensions for Generic UDP Encapsulation (GUE). The extensions defined in this specification are the group identifier, security option, payload transform option, checksum option, fragmentation option, and the remote checksum offload option. Status of this Memo @@ -63,54 +63,54 @@ 3.1. Extension field format . . . . . . . . . . . . . . . . . . 6 3.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Security option . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. Extension field format . . . . . . . . . . . . . . . . . . 6 4.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3. Cookies . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.4. HMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.4.1. Extension field format . . . . . . . . . . . . . . . . 8 4.4.2. Selecting a hash algorithm . . . . . . . . . . . . . . 9 4.4.3. Pre-shared key management . . . . . . . . . . . . . . . 9 - 4.5. Interaction with other optional extensions . . . . . . . . 9 + 4.5. Interaction with other optional extensions . . . . . . . . 10 5. Fragmentation option . . . . . . . . . . . . . . . . . . . . . 10 5.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.3. Extension field format . . . . . . . . . . . . . . . . . . 12 5.4. Fragmentation procedure . . . . . . . . . . . . . . . . . 13 5.5. Reassembly procedure . . . . . . . . . . . . . . . . . . . 15 5.6. Security Considerations . . . . . . . . . . . . . . . . . 17 6. Payload transform option . . . . . . . . . . . . . . . . . . . 17 6.1. Extension field format . . . . . . . . . . . . . . . . . . 17 6.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 18 - 6.3. Interaction with other optional extensions . . . . . . . . 18 + 6.3. Interaction with other optional extensions . . . . . . . . 19 6.4. DTLS transform . . . . . . . . . . . . . . . . . . . . . . 19 - 7. Remote checksum offload option . . . . . . . . . . . . . . . . 19 + 7. Remote checksum offload option . . . . . . . . . . . . . . . . 20 7.1. Extension field format . . . . . . . . . . . . . . . . . . 20 - 7.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 20 - 7.2.1. Transmitter operation . . . . . . . . . . . . . . . . . 20 + 7.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 7.2.1. Transmitter operation . . . . . . . . . . . . . . . . . 21 7.2.2. Receiver operation . . . . . . . . . . . . . . . . . . 21 7.3. Security Considerations . . . . . . . . . . . . . . . . . 22 8. Checksum option . . . . . . . . . . . . . . . . . . . . . . . 22 - 8.1. Extension field format . . . . . . . . . . . . . . . . . . 22 + 8.1. Extension field format . . . . . . . . . . . . . . . . . . 23 8.2. Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 8.3. GUE checksum pseudo header . . . . . . . . . . . . . . . . 23 8.4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.4.1. Transmitter operation . . . . . . . . . . . . . . . . . 25 8.4.2.Receiver operation . . . . . . . . . . . . . . . . . . . 25 8.5. Security Considerations . . . . . . . . . . . . . . . . . 26 9. Processing order of options . . . . . . . . . . . . . . . . . 26 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 11. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 28 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 - 12.1. Normative References . . . . . . . . . . . . . . . . . . 28 - 12.2. Informative References . . . . . . . . . . . . . . . . . 29 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 12.1. Normative References . . . . . . . . . . . . . . . . . . 29 + 12.2. Informative References . . . . . . . . . . . . . . . . . 30 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 1. Introduction Generic UDP Encapsulation (GUE) [I.D.ietf-gue] is a generic and extensible encapsulation protocol. This specification defines a fundamental set of optional extensions for version 0 of GUE. These extensions are the group identifier, security option, payload transform option, checksum option, fragmentation option, and the remote checksum offload option. @@ -152,39 +152,38 @@ The contents of the UDP header are described in [I.D.ietf-gue]. The GUE header consists of: o Ver: Version. Set to 0 to indicate GUE encapsulation header. Note that version 1 does not allow options. o C: C-bit. Indicates the GUE payload is a control message when set, a data message when not set. GUE optional extensions can be used with either control or data messages unless otherwise - specified in the option definition. + specified in the extension definition. o Hlen: Length in 32-bit words of the GUE header, including optional extension fields but not the first four bytes of the header. Computed as (header_len - 4) / 4. The length of the encapsulated packet is determined from the UDP length and the Hlen: encapsulated_packet_length = UDP_Length - 12 - 4*Hlen. o Proto/ctype: If the C-bit is not set this indicates IP protocol - number for the packet in the payload; if the C bit is not set - this is the type of control message in the payload. The next - header begins at the offset provided by Hlen. When the payload - transform option or fragmentation option is used this field may + number for the packet in the payload; if the C bit is set this + is the type of control message in the payload. The next header + begins at the offset provided by Hlen. When the payload + transform option or fragmentation option is used this field MAY be set to protocol number 59 for a data message, or zero for a control message, to indicate no next header for the payload. o G: Indicates the the group identifier extension field is - present. The group identifier extensions is described in section - 3. + present. The group identifier option is described in section 3. o SEC: Indicates security extension field is present. The security option is described in section 4. o F: Indicates fragmentation extension field is present. The fragmentation option is described in section 5. o T: Indicates payload transform extension field is present. The payload transform option is described in section 6. @@ -272,91 +271,113 @@ o 010b - 128 bit security field o 011b - 256 bit security field o 100b - 388 bit security field (HMAC) o 101b, 110b, 111b - Reserved values 4.2. Usage - The GUE security field should be used to provide integrity and + The GUE security option is used to provide integrity and authentication of the GUE header. Security parameters (interpretation of security field, key management, etc.) are expected to be negotiated out of band between two communicating hosts. Two security algorithms are defined below. 4.3. Cookies The security field may be used as a cookie. This would be similar to the cookie mechanism described in L2TP [RFC3931], and the general - properties should be the same. A cookie may be used to validate the + properties should be the same. A cookie MAY be used to validate the encapsulation. The cookie is a shared value between an encapsulator - and decapsulator which should be chosen randomly and may be changed - periodically. Different cookies may used for logical flows between + and decapsulator which SHOULD be chosen randomly and may be changed + periodically. Different cookies MAY be used for logical flows between the encapsulator and decapsulator, for instance packets sent with different VNIs in network virtualization [I.D.hy-nvo3-gue-4-nvo] - might have different cookies. Cookies may be 64, 128, or 256 bits in - size. + might have different cookies. Cookies can b be 64, 128, or 256 bits + in size. 4.4. HMAC Key-hashed message authentication code (HMAC) is a strong method of checking integrity and authentication of data. This sections defines a GUE security option for HMAC. Note that this is based on the HMAC TLV description in "IPv6 Segment Routing Header (SRH)" [I.D.previdi- 6man-sr-header]. 4.4.1. Extension field format - The HMAC option is a 288 bit field (36 octets). The security flags - are set to 100b to indicates the presence of a 288 bit security + The HMAC option is a 320 bit field (40 octets). The security flags + are set to 100b to indicates the presence of a 320 bit security field. The format of the field is: 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | HMAC Key-id | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Payload offset | Payload length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ HMAC (256 bits) ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Fields are: o HMAC Key-id: opaque field to allow multiple hash algorithms or key selection + o Payload offset: offset in payload that indicates the first octet + of payload data included in the HMAC. + + o Payload length: length of payload data starting from the payload + offset to be included in the HMAC calculation. Zero + indicates no payload data in used in the + calculation. + o HMAC: Output of HMAC computation The HMAC field is the output of the HMAC computation (per [RFC2104]) using a pre-shared key identified by HMAC Key-id and of the text which consists of the concatenation of: o The IP addresses o The GUE header including all optional extensions except for the security option + o Optionally some or all of GUE payload. The portion of payload + covered is indicated by an offset into the payload and a length + relative to the offset. + The purpose of the HMAC option is to verify the validity, the - integrity and the authentication of the GUE header itself. + integrity and the authentication of the GUE header itself and + optionally some or all of the GUE payload. The HMAC Key-id field allows for the simultaneous existence of several hash algorithms (SHA-256, SHA3-256 ... or future ones) as well as pre-shared keys. The HMAC Key-id field is opaque, i.e., it has neither syntax nor semantic. Having an HMAC Key-id field allows for pre-shared key roll-over when two pre-shared keys are supported for a while when GUE endpoints converge to a fresher pre-shared key. + A portion of the GUE payload MAY be included in the HMAC calculation. + The payload coverage is indicated in the option in the payload offset + and payload length fields. If no payload data is included in the HMAC + then the payload length field is set to zero. On reception, if the + sum of the payload offset and the payload length is greater than the + total length of the payload, then the packet MUST be dropped. + 4.4.2. Selecting a hash algorithm The HMAC field in the HMAC option is 256 bit wide. Therefore, the HMAC MUST be based on a hash function whose output is at least 256 bits. If the output of the hash function is 256 bits, then this output is simply inserted in the HMAC field. If the output of the hash function is larger than 256 bits, then the output value is truncated to 256 bits by taking the least-significant 256 bits and inserting them in the HMAC field. @@ -398,21 +418,21 @@ processed separately at tunnel end points. A GUE tunnel can use both functions or use one of them. Section 6.3 details handling for when both are used in a packet. 5. Fragmentation option The fragmentation option allows an encapsulator to perform fragmentation of packets being ingress to a tunnel. Procedures for fragmentation and reassembly are defined in this section. This specification adapts the procedures for IP fragmentation and - reassembly described in [RFC0791] and [RFC2460]. Fragmentation may be + reassembly described in [RFC0791] and [RFC2460]. Fragmentation can be performed on both data and control messages in GUE. 5.1. Motivation This section describes the motivation for having a fragmentation option in GUE. MTU and fragmentation issues with In-the-Network Tunneling are described in [RFC4459]. Considerations need to be made when a packet is received at a tunnel ingress point which may be too large to @@ -446,28 +466,29 @@ For alternative #1, fragmentation and reassembly at the tunnel endpoints, there are two possibilities: encapsulate the large packet and then perform IP fragmentation, or segment the packet and then encapsulate each segment (a non-IP fragmentation approach). Performing IP fragmentation on an encapsulated packet has the same issues as that of normal IP fragmentation. Most significant of these is that the Identification field is only sixteen bits in IPv4 which introduces problems with wraparound as described in [RFC4963]. - Alternative #2 follows the suggestion expressed in [RFC2764] and the - fragmentation feature described in the AERO protocol [I.D.templin- - aerolink], that is for the tunneling protocol itself to incorporate a - segmentation and reassembly capability that operates at the tunnel - level. In this method fragmentation is part of the encapsulation and - an encapsulation header contains the information for reassembly. This - differs from IP fragmentation in that the IP headers of the original - packet are not replicated for each fragment. + The second possibility of alternative #1 follows the suggestion + expressed in [RFC2764] and the fragmentation feature described in the + AERO protocol [I.D.templin-aerolink]; that is for the tunneling + protocol itself to incorporate a segmentation and reassembly + capability that operates at the tunnel level. In this method + fragmentation is part of the encapsulation and an encapsulation + header contains the information for reassembly. This differs from IP + fragmentation in that the IP headers of the original packet are not + replicated for each fragment. Incorporating fragmentation into the encapsulation protocol has some advantages: o At least a 32 bit identifier can be defined to avoid issues of the 16 bit Identification in IPv4. o Encapsulation mechanisms for security and identification, such as virtual network identifiers, can be applied to each segment. @@ -502,21 +523,21 @@ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Identification | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The fields of the option are: o Fragment offset: This field indicates where in the datagram this fragment belongs. The fragment offset is measured in units of 8 octets (64 bits). The first fragment has offset zero. - o Res: Two bit reserved field. Must be set to zero for + o Res: Two bit reserved field. MUST be set to zero for transmission. If set to non-zero in a received packet then the packet MUST be dropped. o M: More fragments bit. Set to 1 when there are more fragments following in the datagram, set to 0 for the last fragment. o Orig-proto: The control type (when the C-bit in the GUE header is set) or the IP protocol (when C-bit is not set) of the fragmented packet. @@ -539,21 +560,21 @@ field. 5.4. Fragmentation procedure If an encapsulator determines that a packet must be fragmented (eg. the packet's size exceeds the Path MTU of the tunnel) it should divide the packet into fragments and send each fragment as a separate GUE packet, to be reassembled at the decapsulator (tunnel egress). For every packet that is to be fragmented, the source node generates - an Identification value. The Identification must be different than + an Identification value. The Identification MUST be different than that of any other fragmented packet sent within the past 60 seconds (Maximum Segment Lifetime) with the same tunnel identification-- that is the same outer source and destination addresses, same UDP ports, same orig-proto, and same virtual network identifier if present. The initial, unfragmented, and unencapsulated packet is referred to as the "original packet". This will be a layer 2 packet, layer 3 packet, or the payload of a GUE control message: +-------------------------------//------------------------------+ @@ -592,42 +613,42 @@ o +------------------+----------------+-----------------------+ | IP/UDP header | GUE header | last | | | w/ frag option | fragment | +------------------+----------------+-----------------------+ Each fragment packet is composed of: (1) Outer IP and UDP headers as defined for GUE encapsulation. - o The IP addresses and UDP ports must be the same for all + o The IP addresses and UDP ports MUST be the same for all fragments of a fragmented packet. (2) A GUE header that contains: o The C-bit which is set to the same value for all the fragments of a fragmented packet based on whether a control message or data message was fragmented. o A proto/ctype. In the first fragment this is set to the value corresponding to the next header of the original packet and will be either an IP protocol or a control type. For subsequent fragments, this field is set to 0 for a fragmented control message or 59 (no next header) for a fragmented data message. o The F bit is set and fragment extension field is present. o Other GUE options. Note that options apply to the individual GUE packet. For instance, the security option would be validated before reassembly. The group identifier option - must be set to the save value for all fragments. + MUST be set to the same value for all fragments. (3) The GUE fragmentation option. The contents of the extension field include: o Orig-proto specifies the protocol of the original packet. o A Fragment Offset containing the offset of the fragment, in 8-octet units, relative to the start of the of the original packet. The Fragment Offset of the first ("leftmost") fragment is 0. @@ -650,68 +671,69 @@ +------------------------------//-------------------------------+ The following rules govern reassembly: The IP/UDP/GUE headers of each packet are retained until all fragments have arrived. The reassembled packet is then composed of the decapsulated payloads in the GUE packets, and the IP/UDP/GUE headers are discarded. When a GUE packet is received with the fragment extension, the - proto/ctype field in the GUE header must be validated. In the + proto/ctype field in the GUE header MUST be validated. In the case that the packet is a first fragment (fragment offset is - zero), the proto/ctype in the GUE header must equal the orig- + zero), the proto/ctype in the GUE header MUST equal the orig- proto value in the fragmentation option. For subsequent fragments (fragment offset is non-zero) the proto/ctype in the GUE header must be 0 for a control message or 59 (no-next-hdr) for a data message. If the proto/ctype value is invalid for a received packet it MUST be dropped. An original packet is reassembled only from GUE fragment packets that have the same outer source address, destination address, UDP source port, UDP destination port, GUE header C-bit, group identifier if present, orig-proto value in the fragmentation option, and Fragment Identification. The protocol type or control message type (depending on the C-bit) for the reassembled packet is the value of the GUE header proto/ctype field in the first fragment. - The following error conditions may arise when reassembling fragmented + The following error conditions can arise when reassembling fragmented packets with GUE encapsulation: If insufficient fragments are received to complete reassembly of a packet within 60 seconds (or a configurable period) of the reception of the first-arriving fragment of that packet, - reassembly of that packet must be abandoned and all the - fragments that have been received for that packet must be + reassembly of that packet MUST be abandoned and all the + fragments that have been received for that packet MUST be discarded. If the payload length of a fragment is not a multiple of 8 octets and the M flag of that fragment is 1, then that fragment - must be discarded. + MUST be discarded. If the length and offset of a fragment are such that the payload length of the packet reassembled from that fragment would exceed - 65,535 octets, then that fragment must be discarded. + 65,535 octets, then that fragment MUST be discarded. If a fragment overlaps another fragment already saved for reassembly then the new fragment that overlaps the existing fragment MUST be discarded. If the first fragment is too small then it is possible that it does not contain the necessary headers for a stateful firewall. + Sending small fragments like this has been used as an attack on IP fragmentation. To mitigate this problem, an implementation - should ensure that the first fragment contains the headers of + SHOULD ensure that the first fragment contains the headers of the encapsulated packet at least through the transport header. - A GUE node must be able to accept a fragmented packet that, + A GUE node MUST be able to accept a fragmented packet that, after reassembly and decapsulation, is as large as 1500 octets. This means that the node must configure a reassembly buffer that is at least as large as 1500 octets plus the maximum-sized encapsulation headers that may be inserted during encapsulation. Implementations may find it more convenient and efficient to configure a reassembly buffer size of 2KB which is large enough to accommodate even the largest set of encapsulation headers and provides a natural memory page size boundary. 5.6. Security Considerations @@ -765,24 +786,24 @@ 0x01: for DTLS [RFC6347] 0x80~0xFF: for private payload transform types A private payload transform type can be used for experimental purpose or vendor proprietary mechanisms. P_C_type: Indicates the protocol or control type of the untransformed payload. When payload transform option is - present, proto/ctype in the GUE header should set to 59 ("No + present, proto/ctype in the GUE header is set to 59 ("No next header") for a data message and zero for a control message. The IP protocol or control message type of the - untransformed payload must be encoded in this field. + untransformed payload MUST be encoded in this field. The benefit of this rule is to prevent a middle box from inspecting the encrypted payload according to GUE next protocol. The assumption here is that a middle box may understand GUE base header but does not understand GUE option flag definitions. Data: A field that can be set according to the requirements of each payload transform type. If the specification for a payload transform type does not specify how this field is to @@ -792,64 +813,65 @@ The payload transform option provides a mechanism to transform or interpret the payload of a GUE packet. The Type field provides the method used to transform the payload, and the P_C_type field provides the protocol or control message type of the of payload before being transformed. The payload transformation option is generic so that it can have both security related uses (such as DTLS) as well as non security related uses (such as compression, CRC, etc.). An encapsulator performs payload transformation before transmission, - and a decapsulator must perform the reverse transformation before + and a decapsulator performs the reverse transformation before accepting a packet. For example, if an encapsulator transforms a - payload by encrypting it, the peer decaspsulator must decrypt the + payload by encrypting it, the peer decaspsulator MUST decrypt the payload before accepting the packet. If a decapsulator fails to perform the reverse transformation or cannot validate the transformation it MUST discard the packet and MAY generate an alert to the management system. 6.3. Interaction with other optional extensions + If GUE fragmentation (section 5) is used in concert with the GUE transform option, the transform option processing is performed after fragmentation at the encapsulator and before reassembly at the decapsulator. If the payload transform changes the size of the data being fragmented this must be taken into account during fragmentation. If both the security option and the payload transform are used in a - GUE packet, an encapsulator must perform the payload transformation + GUE packet, an encapsulator MUST perform the payload transformation first, set the payload transform option in the GUE header, and then create the security option. A decapsulator does processing in reverse-- the security option is processed (GUE header is validated) and then the reverse payload transform is performed. In order to get flow entropy from the payload, an encapsulator should derive the flow entropy before performing a payload transform. 6.4. DTLS transform The payload of a GUE packet can be secured using Datagram Transport Layer Security [RFC6347]. An encapsulator would apply DTLS to the GUE payload so that the payload packets are encrypted and the GUE header remains in plaintext. The payload transform option is set to indicate - that the payload should be interpreted as a DTLS record. + that the payload is interpreted as a DTLS record. The payload transform option for DLTS is: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 1 | P_C_type | 0 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ DTLS [RFC6347] provides packet fragmentation capability. To avoid packet fragmentation performed multiple times, a GUE encapsulator SHOULD only perform the packet fragmentation at packet encapsulation - process, i.e., not in payload encryption process. + process, i.e., not in the payload encryption process. DTLS usage [RFC6347] is limited to a single DTLS session for any specific tunnel encapsulator/decapsulator pair (identified by source and destination IP addresses). Both IP addresses MUST be unicast addresses - multicast traffic is not supported when DTLS is used. A GUE tunnel decapsulator implementation that supports DTLS can establish DTLS session(s) with one or multiple tunnel encapsulators, and likewise a GUE tunnel encapsulator implementation can establish DTLS session(s) with one or multiple decapsulators. @@ -860,21 +882,21 @@ in most Network Interface Card (NIC) devices. Many NIC implementations can only offload the outer UDP checksum in UDP encapsulation. Remote checksum offload is described in [UDPENCAP]. In remote checksum offload the outer header checksum, that in the outer UDP header, is enabled in packets and, with some additional meta information, a receiver is able to deduce the checksum to be set for an inner encapsulated packet. Effectively this offloads the computation of the inner checksum. Enabling the outer checksum in encapsulation has the additional advantage that it covers more of the - packet than the inner checksum including the encapsulation headers. + packet, including the encapsulation headers, than an inner checksum. 7.1. Extension field format The presence of the GUE remote checksum offload option is indicated by the R bit in the GUE header. The format of remote checksum offload field is: 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 @@ -967,21 +989,21 @@ 6) Checksum is verified at the transport layer using normal processing. This should not require any checksum computation over the packet since the complete checksum has already been provided. 7.3. Security Considerations Remote checksum offload allows a means to change the GUE payload before being received at a decapsulator. In order to prevent misuse - of this mechanism, a decapsulator should apply security checks on the + of this mechanism, a decapsulator MUST apply security checks on the GUE payload only after checksum remote offload has been processed. 8. Checksum option The GUE checksum option provides a checksum that covers the GUE header, a GUE pseudo header, and optionally part or all of the GUE payload. The GUE pseudo header includes the corresponding IP addresses as well as the UDP ports of the encapsulating headers. This checksum should provide adequate protection against address corruption in IPv6 when the UDP checksum is zero. Additionally, the @@ -1008,34 +1030,34 @@ The fields of the option are: o Checksum: Computed checksum value. This checksum covers the GUE header (including fields and private data covered by Hlen), the GUE pseudo header, and optionally all or part of the payload (encapsulated packet). o Payload coverage: Number of bytes of payload to cover in the checksum. Zero indicates that the checksum only covers the GUE header and GUE pseudo header. If the value is greater than the - encapsulated payload length, the packet must be dropped. + encapsulated payload length, the packet MUST be dropped. 8.2. Requirements - The GUE header checksum should be set on transmit when using a zero + The GUE header checksum SHOULD be set on transmit when using a zero UDP checksum with IPv6. - The GUE header checksum should be used when the UDP checksum is zero + The GUE header checksum SHOULD be used when the UDP checksum is zero for IPv4 if the GUE header includes data that when corrupted can lead to misdelivery or other serious consequences, and there is no other mechanism that provides protection (no security field that checks integrity for instance). - The GUE header checksum should not be set when the UDP checksum is + The GUE header checksum SHOULD NOT be set when the UDP checksum is non-zero. In this case the UDP checksum provides adequate protection and this avoids convolutions when a packet traverses NAT that does address translation (in that case the UDP checksum is required). 8.3. GUE checksum pseudo header The GUE pseudo header checksum is included in the GUE checksum to provide protection for the IP and UDP header elements which when corrupted could lead to misdelivery of the GUE packet. The GUE pseudo header checksum is similar to the standard IP pseudo header defined @@ -1075,22 +1097,22 @@ Note that the GUE pseudo header does not include payload length or protocol as in the standard IP pseudo headers. The length field is deemed unnecessary because: o If the length is corrupted this will usually be detected by a checksum validation failure on the inner packet. o Fragmentation of packets in a tunnel should occur on the inner packet before being encapsulated or GUE fragmentation (section - 4) may be performed at tunnel ingress. GUE packets are not - expected to be fragmented when using IPv6. See RFC6936 for + 4) MAY be performed at tunnel ingress. GUE packets are not + expected to be fragmented when using IPv6. See [RFC6936] for considerations of payload length and IPv6 checksum. o A corrupted length field in itself should not lead to misdelivery of a packet. o Without the length field, the GUE pseudo header checksum is the same for all packets of flow. This is a useful property for optimizations such as TCP Segment Offload (TSO). 8.4. Usage @@ -1118,21 +1140,21 @@ enabled (payload coverage field is non-zero). If the length of the payload coverage is odd, logically append a single zero byte for the purposes of checksum calculation. 5) Add and fold the computed checksums for the GUE header, GUE pseudo header and payload coverage. Set the bitwise not of the result in the GUE checksum field. 8.4.2.Receiver operation - If the GUE checksum option is present, the receiver must validate the + If the GUE checksum option is present, the receiver MUST validate the checksum before processing any other fields or accepting the packet. The procedure for verifying the checksum is: 1) If the payload coverage length is greater than the length of the encapsulated payload then drop the packet. 2) Calculate the checksum of the GUE header from the start of the header to the end as indicated by Hlen. @@ -1140,75 +1162,81 @@ 4) Calculate the checksum of payload if payload coverage is enabled (payload coverage is non-zero). If the length of the payload coverage is odd logically append a single zero byte for the purposes of checksum calculation. 5) Sum the computed checksums for the GUE header, GUE pseudo header, and payload coverage. If the result is all 1 bits (-0 in 1's complement arithmetic), the checksum is valid and the packet is accepted; otherwise the checksum is considered - invalid and the packet must be dropped. + invalid and the packet MUST be dropped. 8.5. Security Considerations The checksum option is only a mechanism for corruption detection, it is not a security mechanism. To provide integrity checks or - authentication of the GUE header, the GUE security option should be + authentication of the GUE header, the GUE security option SHOULD be used. 9. Processing order of options - Options must be processed in a specific order for both sending and + Options MUST be processed in a specific order for both sending and receive. Note that some options, such as the checksum option, depend on other fields in the GUE header to be set. The order of processing options to send a GUE packet are: 1) Set group identifier option. - 2) Fragment if necessary and set fragmentation option. Group - identifier is copied into each fragment. Note that if payload - transformation will increase the size of the payload that must - be accounted for when deciding how to fragment + 2) Fragment if necessary and set fragmentation option. If the + group identifier is present it is copied into each fragment. + Note that if payload transformation will increase the size of + the payload that MUST be accounted for when deciding how to + fragment 3) Perform payload transform (potentially on a fragment) and set payload transform option. 4) Set Remote checksum offload. - 5) Set security option. + 5) Set security option. If the checksum option field is also + present, the checksum value and the payload coverage MUST be + set to zero if computing an HMAC over the GUE header. 6) Calculate GUE checksum and set checksum option. On reception the order of actions is reversed. 1) Verify GUE checksum. - 2) Verify security option. + 2) Verify security option. If the GUE checksum is also present and + HMAC computation is being done over the GUE header, set the + checksum and payload fields in the checksum option to zero + before computing the HMAC. 3) Adjust packet for remote checksum offload. - 4) Perform payload transformation (i.e. decrypt payload) + 4) Perform payload transformation (i.e. decrypt payload). 5) Perform reassembly. 6) Process packet (take group identifier into account if present). Note that the relative processing order of private fields is unspecified. 10. Security Considerations Encapsulation of network protocol in GUE should not increase security risk, nor provide additional security in itself. GUE requires that - the source port for UDP packets should be randomly seeded to mitigate + the source port for UDP packets SHOULD be randomly seeded to mitigate some possible denial service attacks. If the integrity and privacy of data packets being transported through GUE is a concern, GUE security option and payload encryption using the the transform option SHOULD be used to remove the concern. If the integrity is the only concern, the tunnel may consider use of GUE security only for optimization. Likewise, if privacy is the only concern, the tunnel may use GUE encryption function only. If GUE payload already provides secure mechanism, e.g., the payload @@ -1243,23 +1271,50 @@ and complexity. For example, fragmentation will be done twice. As the result, a GUE tunnel SHOULD use the security mechanisms specified in this document to provide secure transport over an IP network or Internet when it is needed. GUE encapsulation can be used as a secure transport mechanism over an IP network and Internet. 11. IANA Consideration IANA is requested to assign flags for the extensions defined in this - specification. Specifically, an assignment is requested for the G, - SEC, F, T, R, and K flags in the "GUE flag-fields" registry (proposed - in [I.D.ietf-gue]). + specification. Specifically, an assignment is requested for the Group + Identfier, Security, Fragmentation, Payload Transform, Remote + Checksum Offload, and Checksum extensions in the "GUE flag-fields" + registry. + + +-------------+---------------+-------------+--------------------+ + | Flags bits | Field size | Description | Reference | + +-------------+---------------+-------------+--------------------+ + | Bit 0 | 4 bytes | Group | This document | + | | | identifier | | + | | | | | + | Bit 1..3 | 001->8 bytes | Security | This document | + | | 010->16 bytes | | | + | | 011->32 bytes | | | + | | 100->40 bytes | | | + | | | | | + | Bit 4 | 8 bytes | Fragmen- | This document | + | | | tation | | + | | | | | + | Bit 5 | 4 bytes | Payload | This document | + | | | transform | | + | | | | | + | Bit 6 | 4 bytes | Remote | This document | + | | | checksum | | + | | | offload | | + | | | | | + | Bit 7 | 4 bytes | Checksum | This document | + | | | | | + | Bit 8..15 | | Unassigned | | + +-------------+---------------+-------------+--------------------+ IANA is requested to set up a registry for the GUE payload transform types. Payload transform types are 8 bit values. New values for control types 1-127 are assigned via Standards Action [RFC5226]. +----------------+------------------+---------------+ | Transform type | Description | Reference | +----------------+------------------+---------------+ | 0 | Reserved | This document | | | | | @@ -1270,91 +1325,104 @@ | 128..255 | User defined | This document | +----------------+------------------+---------------+ 12. References 12.1. Normative References [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. + [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 + (IPv6) Specification", RFC 2460, December 1998. + [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - Communication Layers", STD 3, RFC 1122, October 1989. [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 1980. - [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 - (IPv6) Specification", RFC 2460, December 1998. + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI + 10.17487/RFC5226, May 2008, . [I.D.ietf-gue] T. Herbert, L. Yong, and O. Zia, "Generic UDP Encapsulation" draft-ietf-intarea-gue-01 12.2. Informative References - [RFC1071] Braden, R., Borman, D., and C. Partridge, "Computing the - Internet checksum", RFC1071, September 1988. + [RFC3931] Lau, J., Townsley, W., et al, "Layer Two Tunneling Protocol + - Version 3 (L2TPv3)", RFC3931, 1999 - [RFC1624] Rijsinghani, A., Ed., "Computation of the Internet Checksum - via Incremental Update", RFC1624, May 1994. + [RFC2104] Kent, S. and R. Atkinson, "Security Architecture for the + Internet Protocol" , RFC 2401, DOI 10.17487/RFC2401, + November 1998, . - [RFC1936] Touch, J. and B. Parham, "Implementing the Internet - Checksum in Hardware", RFC1936, April 1996. + [RFC6407] Weis, B., Rowles, S., and T. Hardjono, "The Group Domain of + Interpretation" , RFC 6407, DOI 10.17487/RFC6407, October + 2011, . - [RFC4459] MTU and Fragmentation Issues with In-the-Network Tunneling. - P. Savola. April 2006. + [RFC4459] Savola, P., "MTU and Fragmentation Issues with In-the- + Network Tunneling", RFC 4459, DOI 10.17487/RFC4459, April + 2006, . [RFC4963] Heffner, J., Mathis, M., and B. Chandler, "IPv4 Reassembly Errors at High Data Rates", RFC 4963, DOI 10.17487/RFC4963, July 2007, . [RFC2764] B. Gleeson, A. Lin, J. Heinanen, G. Armitage, A. Malis, "A Framework for IP Based Virtual Private Networks", RFC2764, February 2000. [RFC4301] Kent, S. and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, December 2005. [RFC1858] Ziemba, G., Reed, D., and P. Traina, "Security Considerations for IP Fragment Filtering", RFC 1858, October 1995. [RFC3128] Miller, I., "Protection Against a Variant of the Tiny Fragment Attack (RFC 1858)", RFC 3128, June 2001. - [RFC3931] Lau, J., Townsley, W., et al, "Layer Two Tunneling Protocol - - Version 3 (L2TPv3)", RFC3931, 1999 - - [RFC5925] Touch, J., et al, "The TCP Authentication Option", RFC5925, - June 2010. - [RFC6347] Rescoria, E., Modadugu, N., "Datagram Transport Layer Security Version 1.2", RFC6347, 2012. + [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC + 793, DOI 10.17487/RFC0793, September 1981, . + + [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement + for the Use of IPv6 UDP Datagrams with Zero Checksums", RFC + 6936, DOI 10.17487/RFC6936, April 2013, . + + [RFC1071] Braden, R., Borman, D., and C. Partridge, "Computing the + Internet checksum", RFC1071, September 1988. + [I.D.hy-nvo3-gue-4-nvo] Yong, L., Herbert, T., "Generic UDP Encapsulation (GUE) for Network Virtualization Overlay" draft-hy-nvo3-gue-4-nvo-03 - [I.D.draft-mathis-frag-harmful] M. Mathis, J. Heffner, and B. - Chandler, "Fragmentation Considered Very Harmful" - [I.D.previdi-6man-sr-header] Previdi S. et al, "IPv6 Segment Routing Header (SRH) draft-ietf-6man-segment-routing-header-02 [I.D.templin-aerolink] F. Templin, "Transmission of IP Packets over AERO Links" draft-templin-aerolink-62 - [I.D. [UDPENCAP] T. Herbert, "UDP Encapsulation in Linux", http://people.netfilter.org/pablo/netdev0.1/papers/UDP- Encapsulation-in-Linux.pdf + [FIPS180-4] Secure Hash Standard (SHS), Nation Institute of Standards + and Technology, 8/2015 + Authors' Addresses Tom Herbert Quantonium 4701 Patrick Henry Dr. Santa Clara, CA USA EMail: tom@herbertland.com