Reusable templates and checksum offload for CONNECT-IP

3.1. Header Definition

connect-ip-optimizations = sf-dictionary

This document defines the following optional dictionary keys:¶

templates (sf-interger):

Indicates support for reusable templates and specifies the maximum number of templates that the sender is willing to maintain for templates received from the peer. A positive integer value indicates full support for reusable templates, and the value represents an upper bound on the number of concurrently active templates that can be created by the peer. A value of 0 indicates that the sender supports reusable templates only for its own transmissions but does not accept templates created by the peer. If this member is omitted, reusable templates are not supported in either direction.¶

checksum (sf-boolean):

Indicates support for checksum offload semantics. A value of ?1 means that checksum offload is supported in both directions. A value of ?0 means that checksum offload may be used for packets sent by this endpoint but not for packets received from the peer. If this member is omitted, checksum offload is not supported in either direction.¶

Endpoints MUST ignore unknown dictionary members. The absence of a member implies that the corresponding capability is not supported by the sender.¶

3.2. Negotiation Behavior

If both peers indicate support for templates (that is, templates member is present and non-zero in both directions), either endpoint MAY create and delete Context Identifiers and their templates using capsules as described in Section 4.¶

If both peers indicate support for checksum offload (that is, checksum=?1 in both directions), either endpoint MAY install checksum offload parameters for specific Context Identifiers using capsules as described in Section 4.2.¶

Peers of endpoints that advertise support in only one direction (for example, checksum=?0 or templates=0) MUST NOT send capsules that would require those endpoints to maintain state for the corresponding capability.¶

Capabilities that were not successfully negotiated MUST NOT be used within the tunnel.¶

3.3. Example

HTTP/3 sample request (client to proxy):¶

:method = CONNECT
:protocol = connect-ip
:scheme = https
:path = /.well-known/masque/ip/*/*/
:authority = proxy.example.net
capsule-protocol = ?1
connect-ip-optimizations = templates=20000, checksum=?1

HTTP/3 sample response (proxy to client):¶

:status = 200
capsule-protocol = ?1
connect-ip-optimizations = templates=65535, checksum=?0

In this example, both peers support reusable templates, and checksum offload is supported only for packets sent from the proxy to the client.¶

After this exchange, both endpoints may define Context Identifiers and associated templates and/or checksum parameters using capsules on the reliable control stream.¶

4.1. Context ID allocation

The Context ID carried in these capsules is encoded as a QUIC variable-length integer defined in Section 16 of [QUIC]. Even-numbered CIDs are allocated by the client, and odd-numbered CIDs are allocated by the proxy, consistent with Section 4 of [CONNECT-UDP]. CID 0 is reserved for unoptimized raw packets and MUST NOT appear in these capsules.¶

4.2. CONNECT_IP_OPTIMIZATION_CREATE capsule

CONNECT_IP_OPTIMIZATION_CREATE capsule is used to create a new, immutable optimization context for the indicated CID.¶

CONNECT_IP_OPTIMIZATION_CREATE Capsule {
  Type (i) = 0x1a768469,
  Length (i),
  Context ID (i),
  Static Segments Length (i),
  Static Segment (..) ...,
  Checksum Field Offset (i)?,
  Checksum Start Offset (i)?,
}

CONNECT_IP_OPTIMIZATION_CREATE capsule contains the following fields:¶

Context ID:

Context Identifier, encoded as a variable-length integer, defined by this capsule.¶

Static Segments Length:

Aggregate length in bytes of all subsequent Static Segments. A value of 0 indicates that no template is used (that is, the payload of datagrams for the given Context ID contains a full reconstructed packet, modulo checksum finishing if configured).¶

Checksum Field Offset:

An optional field, encoded as a variable-length integer, containing byte offset of the 16-bit Internet checksum field within the reconstructed packet. This field is omitted if checksum offload is not used.¶

Checksum Start Offset:

An optional field, encoded as a variable-length integer, containing byte offset where checksum coverage begins. Coverage runs from this offset to the end of the reconstructed packet. Not included in the capsule if checksum offloading is not used.¶

The CONNECT_IP_OPTIMIZATION_CREATE capsule contains a sequence of zero or more Static Segments.¶

Static Segment {
  Segment Offset (i),
  Segment Length (i),
  Segment Payload (..),
}

Each Static Segment contains following fields:¶

Segment Offset:

Byte offset from the start of the reconstructed packet, encoded as a variable-length integer¶

Segment Length:

Number of bytes in this static segment, encoded as a variable-length integer¶

Segment Payload:

the static bytes to insert at the Segment Offset¶

4.3. CONNECT_IP_OPTIMIZATION_DELETE capsule

CONNECT_IP_OPTIMIZATION_DELETE capsule is used to indicate that a Context ID previously defined by CONNECT_IP_OPTIMIZATION_CREATE capsule will no longer be used.¶

CONNECT_IP_OPTIMIZATION_DELETE Capsule {
  Type (i) = 0x1a76846a,
  Length (i),
  Context ID (i),
}

After sending an CONNECT_IP_OPTIMIZATION_DELETE Capsule, the sender MUST NOT use the Context ID. Upon receipt, the peer retires the indicated context and releases any negotiated template budget consumed by that context if, and only if, the retired context included a template (that is, its CONNECT_IP_OPTIMIZATION_CREATE had a non-zero Static Segments Length). Retiring a context that had no template (for example, checksum-only) does not affect the template budget.¶

If an CONNECT_IP_OPTIMIZATION_DELETE capsule is received for a Context ID that was not previously and correctly defined by an CONNECT_IP_OPTIMIZATION_CREATE capsule from the peer, the receiver MUST follow the error-handling procedure defined in Section 3.3 of [HTTP-DATAGRAMS].¶

5.1. Sender behavior

For each packet sent under a Context ID, the sender constructs the datagram payload according to the context's template. If the context has no template (that is, Static Segments Length is 0), the payload MUST be a complete reconstructed packet. If the context has a template, the payload MUST be the concatenation of all variable byte ranges, taken in strictly increasing offset order, corresponding to the gaps not covered by static segments starting at offset 0.¶

When checksum offload is configured (that is, the context includes Checksum Field Offset and Checksum Start Offset), the sender MUST set the checksum field in the reconstructed packet image to the 16-bit one’s-complement sum of the appropriate pseudo-header before transmission. The two bytes at Checksum Field Offset in the reconstructed image therefore MUST contain this pseudo-header sum; these bytes originates from static bytes in the template as well as from variable bytes in the payload. The final reconstructed image MUST contain the correct preseeding value.¶

A sender uses Context ID 0 for any one-off packet that does not fit an existing context (for example, a transient change in header layout).¶

5.2. Receiver behavior

A datagram that arrives with a non-zero Context ID that has not been previously and correctly defined by an CONNECT_IP_OPTIMIZATION_CREATE capsule from the peer MUST be dropped.¶

If the CID has no template (that is, Static Segments Length is 0), the datagram payload is the complete reconstructed packet. If the CID has a template, the receiver reconstructs the packet from offset 0 upward by writing static bytes at their declared offsets and filling all remaining byte positions with bytes consumed from the datagram payload in strictly increasing offset order. Reconstruction continues until all payload bytes have been consumed. If the payload is exhausted before the offset of the last static segment have been filled, the packet MUST be dropped.¶

When Checksum Field Offset and Checksum Start Offset are present for the CID, the receiver finishes the Internet checksum as follows: it computes the checksum over the byte range starting at Checksum Start Offset and ending at the reconstructed packet length while treating the checksum field as zero during the sum; it then adds (folds) the 16-bit value currently at Checksum Field Offset, performs end-around carry, and writes the final one's-complement result back at Checksum Field Offset. If either checksum offset is greater than or equal to the reconstructed packet length for this packet, the packet MUST be dropped.¶

6.1. TCP over IPv6 with template and checksum offload

Original sample [TCP] over [IPv6] packet layout is illustrated below. In addition to basic IPv6 and TCP headers it contains Timestamp option as defined in Section 3 of [TCP-PERF].¶

Table below illustrates fields present in IPv6 and TCP headers, their offsets in bits from the beginning of the packet and whether they are likely to be static for most packets of a given traffic flow¶

Static segments model the invariant parts except for the isolated 4-bit TCP header length.¶

Resulting static segments:¶

Resulting CONNECT_IP_OPTIMIZATION_CREATE capsule with client-allocated even context id is illustrated below:¶

CONNECT_IP_OPTIMIZATION_CREATE Capsule {
  Type (i) = 0x1a768469,
  Length (i) = 58,
  Context ID (i) = 2,
  Static Segments Length (i) = 54,
  Static Segment {
    Segment Offset (i) = 0,
    Segment Length (i) = 4,
    Segment Payload = 0x6004bcde,
  },
  Static Segment {
    Segment Offset (i) = 6,
    Segment Length (i) = 38,
    Segment Payload = 0x067920010db885a3000000008a2e0370733420010db8a42b000000007c3a143a15290050d475,
  },
  Static Segment {
    Segment Offset (i) = 58,
    Segment Length (i) = 6,
    Segment Payload = 0x00000101080a,
  },
  Checksum Field Offset (i) = 56,
  Checksum Start Offset (i) = 40,
}

This template reduces per-packet overhead by omitting 48 bytes of repeated header material, increasing the effective MTU when datagrams are encapsulated in QUIC DATAGRAM frames.¶

The sender concatenates all variable regions in increasing offset order and replaces checksum field with the IPv6/TCP pseudo-header checksum. Packets that do not match this template (for example packets with IPv6 extension headers or without TCP options) are sent using Context ID 0 or associated with a new context.¶

6.2. UDP over IPv4 with template and without checksum offload

Original sample [UDP] over [IPv4] packet layout is illustrated below.¶

Table below illustrates fields present in IPv4 header and UDP, their offsets in bits from the beginning of the packet and if they are likely to be static for most packets of a given traffic flow¶

Static segments model the invariant parts:¶

Resulting CONNECT_IP_OPTIMIZATION_CREATE capsule with proxy-allocated odd Context ID is illustrated below:¶

CONNECT_IP_OPTIMIZATION_CREATE Capsule {
  Type (i) = 0x1a768469,
  Length (i) = 28,
  Context ID (i) = 3,
  Static Segments Length (i) = 26,
  Static Segment {
    Segment Offset (i) = 0,
    Segment Length (i) = 2,
    Segment Payload = 0x4502,
  },
  Static Segment {
    Segment Offset (i) = 4,
    Segment Length (i) = 6,
    Segment Payload = 0x000040004011,
  },
  Static Segment {
    Segment Offset (i) = 12,
    Segment Length (i) = 12,
    Segment Payload = 0xc0000201c0000202c1991151,
  }
}

This template omits 20 bytes of repeated header material, increasing the effective MTU when datagrams are encapsulated in QUIC DATAGRAM frames.¶

The sender concatenates all variable regions in increasing offset order. Because this template does not define checksum offload, the UDP checksum is computed by the sender as usual; the receiver does not perform checksum finishing for this context.¶

8.1. HTTP Capsule Types Registration

This specification registers the following values in the "HTTP Capsule Types" registry:¶

| Value | Capsule Type + --- + --- + | 0x1a768469 | CONNECT_IP_OPTIMIZATION_CREATE | | 0x1a76846a | CONNECT_IP_OPTIMIZATION_DELETE |¶

8.2. HTTP Field Name Registration

This specification registers the following value in the "HTTP Field Name" registry:¶

• Field Name: connect-ip-optimizations¶

• Status: provisional (permanent if approved)¶

• Structured Type: Dictionary¶

• Reference: This document¶

9.1. Normative References

[CONNECT-IP]

Pauly, T., Ed., Schinazi, D., Chernyakhovsky, A., Kühlewind, M., and M. Westerlund, "Proxying IP in HTTP", RFC 9484, DOI 10.17487/RFC9484, October 2023, <https://www.rfc-editor.org/rfc/rfc9484>.

[CONNECT-UDP]

Schinazi, D., "Proxying UDP in HTTP", RFC 9298, DOI 10.17487/RFC9298, August 2022, <https://www.rfc-editor.org/rfc/rfc9298>.

[HTTP-DATAGRAMS]

Schinazi, D. and L. Pardue, "HTTP Datagrams and the Capsule Protocol", RFC 9297, DOI 10.17487/RFC9297, August 2022, <https://www.rfc-editor.org/rfc/rfc9297>.

[INCREMENTAL-CHECKSUM]

Rijsinghani, A., Ed., "Computation of the Internet Checksum via Incremental Update", RFC 1624, DOI 10.17487/RFC1624, May 1994, <https://www.rfc-editor.org/rfc/rfc1624>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[STRUCTURED-HTTP]

Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, <https://www.rfc-editor.org/rfc/rfc8941>.

9.2. Informative References

[IPv4]

Postel, J., "Internet Protocol", STD 5, RFC 791, DOI 10.17487/RFC0791, September 1981, <https://www.rfc-editor.org/rfc/rfc791>.

[IPv6]

Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", STD 86, RFC 8200, DOI 10.17487/RFC8200, July 2017, <https://www.rfc-editor.org/rfc/rfc8200>.

[QUIC]

Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, May 2021, <https://www.rfc-editor.org/rfc/rfc9000>.

[TCP]

Eddy, W., Ed., "Transmission Control Protocol (TCP)", STD 7, RFC 9293, DOI 10.17487/RFC9293, August 2022, <https://www.rfc-editor.org/rfc/rfc9293>.

[TCP-PERF]

Borman, D., Braden, B., Jacobson, V., and R. Scheffenegger, Ed., "TCP Extensions for High Performance", RFC 7323, DOI 10.17487/RFC7323, September 2014, <https://www.rfc-editor.org/rfc/rfc7323>.

[UDP]

Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 10.17487/RFC0768, August 1980, <https://www.rfc-editor.org/rfc/rfc768>.