--- 1/draft-ietf-intarea-gue-extensions-01.txt 2018-01-02 10:13:31.920628595 -0800 +++ 2/draft-ietf-intarea-gue-extensions-02.txt 2018-01-02 10:13:32.000630478 -0800 @@ -1,30 +1,27 @@ INTERNET-DRAFT T. Herbert Intended Status: Proposed Standard Quantonium -Expires: November 19, 2017 L. Yong +Expires: July 6, 2018 L. Yong Huawei F. Templin Boeing - May 18, 2017 + January 2, 2018 Extensions for Generic UDP Encapsulation - draft-ietf-intarea-gue-extensions-01 + draft-ietf-intarea-gue-extensions-02 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. + extensions for Generic UDP Encapsulation (GUE). 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. @@ -35,144 +32,166 @@ 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) 2017 IETF Trust and the persons identified as the + Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. GUE header format with optional extensions . . . . . . . . . . 4 - 3. Group identifier option . . . . . . . . . . . . . . . . . . . 5 + 3. Group identifier option . . . . . . . . . . . . . . . . . . . 6 3.1. Extension field format . . . . . . . . . . . . . . . . . . 6 3.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Security option . . . . . . . . . . . . . . . . . . . . . . . 6 - 4.1. Extension field format . . . . . . . . . . . . . . . . . . 6 + 4.1. Extension field format . . . . . . . . . . . . . . . . . . 7 4.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4.3. Cookies . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 4.3. Cookies . . . . . . . . . . . . . . . . . . . . . . . . . 8 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.4.3. Pre-shared key management . . . . . . . . . . . . . . . 10 4.5. Interaction with other optional extensions . . . . . . . . 10 5. Fragmentation option . . . . . . . . . . . . . . . . . . . . . 10 - 5.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 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.1. Extension field format . . . . . . . . . . . . . . . . . . 18 6.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 18 6.3. Interaction with other optional extensions . . . . . . . . 19 6.4. DTLS transform . . . . . . . . . . . . . . . . . . . . . . 19 7. Remote checksum offload option . . . . . . . . . . . . . . . . 20 7.1. Extension field format . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . 23 8.2. Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 - 8.3. GUE checksum pseudo header . . . . . . . . . . . . . . . . 23 + 8.3. GUE checksum pseudo header . . . . . . . . . . . . . . . . 24 8.4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.4.1. Transmitter operation . . . . . . . . . . . . . . . . . 25 8.4.2.Receiver operation . . . . . . . . . . . . . . . . . . . 25 + 8.6. Corrupted flags . . . . . . . . . . . . . . . . . . . . . . 26 8.5. Security Considerations . . . . . . . . . . . . . . . . . 26 - 9. Processing order of options . . . . . . . . . . . . . . . . . 26 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 - 11. IANA Consideration . . . . . . . . . . . . . . . . . . . . . . 28 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 12.1. Normative References . . . . . . . . . . . . . . . . . . 29 - 12.2. Informative References . . . . . . . . . . . . . . . . . 30 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 + 9. NAT checksum address option . . . . . . . . . . . . . . . . . 26 + 9.1. Extension field format . . . . . . . . . . . . . . . . . . 26 + 9.3. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 9.3.1. Transmitter operation . . . . . . . . . . . . . . . . . 27 + 9.3.2. Receiver operation . . . . . . . . . . . . . . . . . . 28 + 10. Alternative checksum option . . . . . . . . . . . . . . . . . 28 + 10.1. Extension field format . . . . . . . . . . . . . . . . . 28 + 10.1.1. 16-bit CRC alternate checksum . . . . . . . . . . . . 29 + 10.1.2. 32-bit CRC alternate checksum . . . . . . . . . . . . 30 + 10.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 10.2.1. Transmitter operation . . . . . . . . . . . . . . . . 30 + 10.2.2. Receiver operation . . . . . . . . . . . . . . . . . . 31 + 10.3. Corrupted flags . . . . . . . . . . . . . . . . . . . . . 31 + 10.4. Security Considerations . . . . . . . . . . . . . . . . . 32 + 11. Processing order of options . . . . . . . . . . . . . . . . . 32 + 11.1. Processing order when sending . . . . . . . . . . . . . . 32 + 11.2. Processing order when receiving . . . . . . . . . . . . . 33 + 12. Security Considerations . . . . . . . . . . . . . . . . . . . 33 + 13. IANA Consideration . . . . . . . . . . . . . . . . . . . . . 34 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 35 + 14.2. Informative References . . . . . . . . . . . . . . . . . 36 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 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. + extensions are the group identifier, security, fragmentation, payload + transform, remote checksum offload, checksum, NAT address checksum, + and alternate checksum. 2. GUE header format with optional extensions - The format of a version 0 GUE header with the optional extensions - defined in this specification is: + The format of a version 0 GUE header with optional extensions 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\ | Source port | Destination port | UDP +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+/ | Length | Checksum | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | 0 |C| Hlen | Proto/ctype |G| SEC |F|T|R|S| Rsvd Flags | + | 0 |C| Hlen | Proto/ctype |G| SEC |F|T|R|K|N|ACS| Rsvd | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Group identifier (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Security (optional) ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + Fragmentation (optional) + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Payload transform (optional | + | Payload transform (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Remote checksum offload (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Checksum (optional) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | NAT Address Checksum (optional) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + ~ Alternate checksum (optional) ~ + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | ~ Private data (optional) ~ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - 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 Variant: Set to 0 to indicate GUE encapsulation header. Note + that variant 1 (direct IP encapsulation) 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 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. + optional extension fields and private data 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 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 @@ -186,20 +205,26 @@ o T: Indicates payload transform extension field is present. The payload transform option is described in section 6. o R: Indicates the remote checksum extension field is present. The remote checksum offload option is described in section 7. o K: Indicates checksum extension field is present. The checksum option is described in section 8. + o N: Indicates NAT address checksum field is present. The NAT + address checksum option is described in section 9. + + o ACS: Indicates alternative checksum field is present. The + alternative checksum option is described in section 10. + o Private data is described in [I.D.ietf-gue]. 3. Group identifier option The group identifier classifies packet that logically belong to the same group. Groups are arbitrarily defined for different purposes and their definition is shared between the communicating end nodes. 3.1. Extension field format @@ -220,22 +245,24 @@ 3.2. Usage The group identifier is set by an encapsulator to indicate to the decapsulator that a packet belongs to a group. Groups may be arbitrarily defined to classify packets. Specific use cases of the group identifier may be defined in other documents ([I.D.hy-nvo3-gue- 4-nvo] defines a use of this field to contain a virtual networking identifier for implementing network virtualization). - Intermediate nodes SHOULD NOT attempt to infer the meaning or - semantics of group identifiers. + Intermediate nodes MAY apply semantics to group identifiers if group + identifier information is shared and made global within a network. + For instance, a firewall could block packets based on a group + identifier that serves as a virtual identifier for a tenant. 4. Security option The GUE security option provides origin authentication and integrity protection of the GUE header at tunnel end points to guarantee isolation between tunnels and mitigate Denial of Service attacks. 4.1. Extension field format The presence of the GUE security option is indicated in the SEC flag @@ -265,58 +292,57 @@ The values in the SEC flags are: o 000b - No security field o 001b - 64 bit security field o 010b - 128 bit security field o 011b - 256 bit security field - o 100b - 388 bit security field (HMAC) + o 100b - 320 bit security field (HMAC) o 101b, 110b, 111b - Reserved values 4.2. Usage 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 encapsulation. The cookie is a shared value between an encapsulator - and decapsulator which SHOULD be chosen randomly and may be changed + 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 can b be 64, 128, or 256 bits - in size. + might have different cookies. Cookies can 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 320 bit field (40 octets). The security flags - are set to 100b to indicates the presence of a 320 bit security - field. + are set to 100b to indicate 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -418,21 +445,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 can be + reassembly described in [RFC0791] and [RFC8200]. 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 @@ -470,34 +497,34 @@ 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]. 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 + 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. + as group identifiers, can be applied to each segment. o This allows the possibility of using alternate fragmentation and reassembly algorithms (e.g. fragmentation with Forward Error Correction). o Fragmentation is transparent to the underlying network so it is unlikely that fragmented packet will be unconditionally dropped as might happen with IP fragmentation. 5.2. Scope @@ -564,21 +591,21 @@ 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 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. + same orig-proto, and same group 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: +-------------------------------//------------------------------+ | Original packet | | (e.g. an IPv4, IPv6, Ethernet packet) | +------------------------------//-------------------------------+ @@ -782,21 +809,21 @@ Type: Payload Transform Type or Code point. Each payload transform mechanism must have one code point registered in IANA. This document specifies: 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. + experimental purposes or 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 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. The benefit of this rule is to prevent a middle box from inspecting the encrypted payload according to GUE next @@ -1054,21 +1081,21 @@ 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 - in [RFC0768] and [RFC0793] for IPv4, and in [RFC2460] for IPv6. + in [RFC0768] and [RFC0793] for IPv4, and in [RFC8200] for IPv6. The GUE pseudo header for IPv4 is: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Destination Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source port | Destination port | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -1088,39 +1115,26 @@ + + | | + Destination Address + | | + + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source port | Destination port | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - 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 - 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). + 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 a corrupted length field should not cause mis- + delivery, the GUE checksum is applied after GUE fragmentation, and + without the length field the GUE pseudo header checksum is the same + for all packets of flow. 8.4. Usage The GUE checksum is computed and verified following the standard process for computing the Internet checksum [RFC1071]. Checksum computation may be optimized per the mathematical properties including parallel computation and incremental updates. 8.4.1. Transmitter operation @@ -1164,75 +1178,375 @@ 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. +8.6. Corrupted flags + + Note that the GUE checksum does not protect against the checksum flag + (K flag) being corrupted. If an encapsulator sets the checksum flag + and option but the K bit flips to be zero, then a decapsulator will + incorrectly process the GUE packet as not having a checksum field. + + To mitigate this issue an encapsulator and depcapsulator might agree + that checksum is always required. This agreement could be established + by configuration or GUE capability negotiation. + 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 used. -9. Processing order of options +9. NAT checksum address option + + The NAT address checksum (NAC) option contains the checksum computed + over the IP addresses of the packet. The computed value can be used + by a receiver to adjust a transport layer checksum that was affect by + NAT changing the IP addresses. This option is only useful when GUE + encapsulates a transport layer packet with a checksum with a pseudo + header that includes the IP addresses (such as TCP or UDP). + +9.1. Extension field format + + The presence of the NAT checksum address option is indicated by the N + bit in the GUE header. + + The format of the NAT checksum address extension 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Checksum | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + The fields of the option are: + + o Checksum: Computed checksum value. This checksum covers the + outer IP addresses. + + o Reserved: Must be zero on transmit. + +9.3. Usage + + The NAT address address extension SHOULD be set on transmit when + encapsulating a transport layer protocol whose checksum might be + affected by NAT being performed on the outer IP header. If this + option is used then the UDP checksum MUST be used (sent with non-zero + value). + + The NAT address checksum is computed using the Internet checksum + [RFC1071]. + +9.3.1. Transmitter operation + + An encapsulator computes the checksum value over the IP addresses in + the IP header. + + For IPv4 the checksum is computed over: + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source Address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination Address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + For IPv6 the checksum is computed over: + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + + + | | + + Source Address + + | | + + + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + + + | | + + Destination Address + + | | + + + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +9.3.2. Receiver operation + + 1) Validate the UDP checksum is correct + + 2) Compute the checksum over the IP address in the received packet + + 3) Subtract the value in step #1 from the NAC value. If the + difference is non-zero then NAT has changed the addresses + + 4) When processing a transport layer containing a checksum + affected by NAT on the IP addresses, add the difference into + the checksum calculation when verify the packet. + + In pseudo codes this is: + + actual = checksum(IP addresses) + diff = actual - NAC_value + verify = checksum(transport packet) + checksum(pseudo header) + + diff + + if (verify == 0) + packet is good + +10. Alternative checksum option + + The alternative checksum option contains a checksum over the GUE + header and optionally all or part of the GUE payload. The alternative + checksum can provide stronger protection against data corruption than + provided by the one's complement checksum used in the UDP checksum or + the GUE checksum (section 8). + + The alternative checksum flags are two bits which allow three methods + to be defined. This specification proposes two: a 16-bit CRC method + and a 32-bit CRC method. + +10.1. Extension field format + + The format of the alternate checksum option 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + ~ Alternate checksum ~ + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + The fields of the option are: + + o Alternate checksum (variable length). Contains the checksum + information. + + The presence of the alternate checksum option is indicated by the ACS + bits in the GUE header. + + The values in the ACS flags are: + + o 00b - No alternate checksum field + + o 01b - 16-bit CRC + + o 10b - 32-bit CRC + + 0 11b - Reserved + +10.1.1. 16-bit CRC alternate checksum + + The format of the 16-bit CRC alternative checksum 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | CRC | Payload coverage | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + The fields of the option are: + + o CRC: Computed CRC value. This CRC covers the GUE header + (including fields and private data covered by Hlen) and + optionally all or part of the payload (encapsulated packet). + + o Payload coverage: Number of bytes of payload to cover in the CRC + calculation. Zero indicates that the checksum only covers the + GUE header. If the value is greater than the encapsulated + payload length, the packet MUST be dropped. + + The 16-bit alternative checksum does not include a pseudo header + containing IP addresses or ports. The CRC is calculated using CRC- + CCITT algorithm (x^16 + x^12 + x^5 + 1 or polynomial 0x1021). + +10.1.2. 32-bit CRC alternate checksum + + The format of the 32-bit CRC alternative checksum 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved | Payload coverage | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | CRC | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + The fields of the option are: + + o CRC: Computed CRC value. This CRC covers the GUE header + (including fields and private data covered by Hlen) and + optionally all or part of the payload (encapsulated packet). + + o Payload coverage: Number of bytes of payload to cover in the CRC + calculation. Zero indicates that the checksum only covers the + GUE header. If the value is greater than the encapsulated + payload length, the packet MUST be dropped. + + The 16-bit alternative checksum does not include a pseudo header + containing IP addresses or ports. The CRC is calculated using CRC-32 + algorithm (x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +x ^10 + x^2 + x^7 + + x^5 + x^4 +x^2 + x + 1 or polynomial 0x04C11DB7). + +10.2. Usage + + The usage of the alternate checksum is the same for both the 16-bit + CRC and the 32-bit CRC methods except that the output CRC values have + different size. + +10.2.1. Transmitter operation + + The procedure for setting the GUE alternative checksum on transmit + is: + + 1) Create the GUE header including the alternative checksum field. + The CRC field is initialized to zero. + + 2) Calculate the alternative checksum (either a 16-bit or 32-bit + CRC) from the start of the GUE header through the its length as + indicated in GUE Hlen. + + 3) Continue the calculation to cover the payload portion if + payload coverage is enabled (payload coverage field is non- + zero). If the length of the payload coverage is not aligned per + the algorithm (four bytes for CRC-32 and two bytes for CRC-16), + logically append zero bytes up to the necessary alignment for + the purposes of CRC calculation. + + 4) Set the resultant value in the CRC field. + +10.2.2. Receiver operation + + If the GUE alternative checksum option is present, the receiver MUST + validate the checksum before processing any other fields or accepting + the packet. + + The procedure for verifying the alternate checksum is: + + 1) If the payload coverage length is greater than the length of + the encapsulated payload then drop the packet. + + 2) Note value in the CRC field and set the CRC field to zero. + + 3) Calculate the alternative checksum (either a 16-bit or 32-bit + CRC) from the start of the GUE header through the its length as + indicated in GUE Hlen. + + 4) Continue the calculation to cover the payload portion if + payload coverage is enabled (payload coverage field is non- + zero). If the length of the payload coverage is not aligned per + the algorithm (four bytes for CRC-32 and two bytes for CRC-16), + logically append zero bytes up to the necessary alignment for + the purposes of CRC calculation. + + 5) Compare the computed value with the original value of the CRC + field. If they are equal then that packet is accepted, if they + are not equal then verification filed and the packet MUST be + dropped. + + 6) Restore the CRC field to its original value. + +10.3. Corrupted flags + + Similar to GUE checksum properties, the GUE alternate checksum does + not protect against the alternative checksum flags (ACS flags) being + corrupted. If an encapsulator sets the alternative checksum flags and + option but the ACS bits flips to be zero, then a decapsulator will + incorrectly process that packet as not having an alternate checksum + field. + + To mitigate this issue an encapsulator and depcapsulator might agree + that an alternate checksum is always required. This agreement could + be established by configuration or GUE capability negotiation. + +10.4. Security Considerations + + The alternate 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 used. + +11. Processing order of options 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. +11.1. Processing order when sending + + When setting the security option (HMAC option in particular), the + checksum option, and the alternate checksum option-- all the GUE + fields being used must be present and properly set in the header. The + checksum value in the checksum option or alternate checksum option + MUST be initialized to zero to ensure consistent HMAC and checksum + calculation. + The order of processing options to send a GUE packet are: 1) Set group identifier option. 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 + group identifier is present it is copied into each fragment. 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. 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. + 5) Set NAT address checksum option. - 6) Calculate GUE checksum and set checksum option. + 6) Set security option per cookie or HMAC calculation. + + 7) Calculate GUE checksum and set checksum option. + + 8) Calculate GUE alternate checksum and set the alternate checksum + option. + +11.2. Processing order when receiving On reception the order of actions is reversed. - 1) Verify GUE checksum. + 1) Verifiy GUE alternate checksum. - 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. + 2) Verify GUE checksum. If the alternate checksum option is + present, set the checksum fields to zero for computing the GUE + checksum. After computation, restore the GUE checksum value. - 3) Adjust packet for remote checksum offload. + 3) Verify security option. If the GUE checksum option or alternate + checksum option is also present and HMAC computation is being + done over the GUE header, then set the checksum fields to zero + for computing the HMAC. After computation, restore the checksum + values. - 4) Perform payload transformation (i.e. decrypt payload). + 4) Save the NAT address checksum value. It will be applied when + processing the encapsulated packet. - 5) Perform reassembly. + 5) Adjust packet for remote checksum offload. - 6) Process packet (take group identifier into account if present). + 6) Perform payload transformation (i.e. decrypt payload). - Note that the relative processing order of private fields is - unspecified. + 7) Perform reassembly. -10. Security Considerations + 8) Process packet (take group identifier into account if present). + + The relative processing order of GUE extensions and private fields is + unspecified in this specification. + +12. 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 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 @@ -1244,22 +1558,22 @@ security. GUE may rely on other secure tunnel mechanisms such as DTLS [RFC6347] over the whole UDP payload for securing the whole GUE packet or IPsec [RFC4301] to achieve the secure transport over an IP network or Internet. IPsec [RFC4301] was designed as a network security mechanism, and therefore it resides at the network layer. As such, if the tunnel is secured with IPsec, the UDP header would not be visible to - intermediate routers in either IPsec tunnel or transport mode. The - big drawback here prohibits intermediate routers to perform load + intermediate routers in either IPsec tunnel or transport mode. This + is a drawback since it prohibits intermediate routers to perform load balancing based on the flow entropy in UDP header. In addition, this method prohibits any middle box function on the path. By comparison, DTLS [RFC6347] was designed with application security and can better preserve network and transport layer protocol information than IPsec [RFC4301]. Using DTLS over UDP to secure the GUE tunnel, both GUE header and payload will be encrypted. In order to differentiate plaintext GUE header from encrypted GUE header, the destination port of the UDP header between two must be different, which essentially requires another standard UDP port for GUE with @@ -1268,21 +1582,21 @@ Use of two independent tunnel mechanisms such as GUE and DTLS over UDP to carry a network protocol over an IP network adds some overlap 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 +13. IANA Consideration IANA is requested to assign flags for the extensions defined in this 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 | +-------------+---------------+-------------+--------------------+ @@ -1299,64 +1613,73 @@ | | | | | | 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 | | + | Bit 8 | 4 bytes | NAT | This document | + | | | checksum | | + | | | address | | + | | | | | + | Bit 9..10 | 01->4 bytes | Alternate | This document | + | | 10->8 bytes | checksum | | + | | | | | + | Bit 11..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 | | | | | | 1 | DTLS | This document | | | | | | 2..127 | Unassigned | | | | | | | 128..255 | User defined | This document | +----------------+------------------+---------------+ -12. References +14. References -12.1. Normative References +14.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. + [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 + (IPv6) Specification", STD 86, RFC 8200, DOI + 10.17487/RFC8200, July 2017, . [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. [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 +14.2. Informative References [RFC3931] Lau, J., Townsley, W., et al, "Layer Two Tunneling Protocol - Version 3 (L2TPv3)", RFC3931, 1999 [RFC2104] Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol" , RFC 2401, DOI 10.17487/RFC2401, November 1998, . [RFC6407] Weis, B., Rowles, S., and T. Hardjono, "The Group Domain of Interpretation" , RFC 6407, DOI 10.17487/RFC6407, October