Common Procedures for Encapsulating IOAM Data Fields in Transport Protocols

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 5 January 2027.¶

Copyright Notice

Copyright (c) 2026 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 (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

In Situ Operations, Administration, and Maintenance (IOAM) [RFC9197] collects telemetry information by embedding IOAM Data-Fields into live data packets while they traverse a network path. The IOAM Data-Fields themselves are defined independently of any specific transport protocol. This design allows IOAM to be carried within various encapsulations such as IPv6 [RFC9486], NSH [RFC9452], GRE, and Geneve.¶

Each transport protocol that carries IOAM defines its own encapsulation specification, describing how IOAM Option-Types map into that protocol's extension mechanisms. While the data field definitions remain the same across protocols, the encapsulation documents each independently describe similar operational steps: how to identify where in the packet IOAM data should be placed, how to expand the packet to accommodate the additional data, and how to update the enclosing headers to reflect the modified packet structure.¶

This redundancy creates practical challenges. First, implementations supporting multiple transport protocols must encode logically equivalent procedures in protocol-specific code paths, increasing development and verification effort. Second, the absence of a shared procedural framework can lead to inconsistent behavior across encapsulations, particularly in areas such as Maximum Transmission Unit (MTU) handling, header field updates, and error handling. Third, as new transport protocols emerge, the effort required to specify IOAM encapsulation for each protocol remains unnecessarily high.¶

This document addresses these challenges by defining a set of common encapsulation procedures for IOAM Data-Fields. The central concept is that the insertion point for IOAM data within a packet is expressed as a configurable byte offset from a well-defined reference position in the encapsulating header. This approach enables a single encapsulation procedure to handle multiple transport protocols: the protocol-specific knowledge is confined to the provisioning of the correct offset value, while the insertion operation itself is uniform across all protocols.¶

2. Terminology

This document uses the IOAM terminology defined in [RFC9197] and [RFC9378]. The following additional terms are used:¶

Insertion Point:

The byte position within a packet at which IOAM Data-Fields are to be placed. The insertion point is determined by adding a configured insertion offset to the reference position.¶

Reference Position:

A well-defined, unambiguous byte position within the encapsulating protocol header from which the insertion offset is measured. Typical reference positions include the start of the network-layer (Layer 3) header or the start of a specific extension header.¶

Insertion Offset:

A non-negative integer value, expressed in octets, that specifies the displacement from the reference position to the insertion point. The insertion offset is provisioned per IOAM Encapsulation Profile and depends on the transport protocol in use.¶

Base Header:

The fixed-length portion of the encapsulating protocol header that precedes the area where IOAM Data-Fields can be inserted.¶

Header Consistency Update:

The process of modifying header fields in the encapsulating protocol and any outer encapsulations to accurately reflect the change in packet size and structure resulting from the insertion or removal of IOAM Data-Fields.¶

Transport Constraints:

Protocol-specific limitations that restrict the size, alignment, or placement of IOAM Data-Fields within a given transport protocol.¶

IOAM Encapsulation Profile:

A configuration object that associates a set of flow-matching criteria with the IOAM encapsulation parameters to be applied, including the IOAM Option-Types to insert, the insertion offset, and protocol-specific constraint parameters.¶

3. Scope and Relationship to Existing Specifications

This document is intended to complement, not replace, the existing IOAM encapsulation specifications. [RFC9197] defines the IOAM Data-Fields and their formats. This document does not modify or extend those definitions. [RFC9378] provides deployment guidance for IOAM. This document focuses on encapsulation procedures rather than deployment considerations. [RFC9617] defines a YANG data model for IOAM configuration. The IOAM Encapsulation Profile concept defined in this document is compatible with the configuration structures in [RFC9617].¶

Protocol-specific encapsulation documents (e.g., [RFC9486] for IPv6, [RFC9452] for NSH) define how IOAM Option-Types are mapped into specific protocol header structures. This document abstracts the common operational steps shared across those specifications and provides a framework for specifying IOAM encapsulation in future transport protocols.¶

The common procedures defined in this document are informational for existing encapsulations and normative for future transport protocol encapsulations that choose to reference this document.¶

4. Overview of Common Encapsulation Procedures

The process of encapsulating IOAM Data-Fields into a transit packet can be decomposed into the following general steps, regardless of the specific transport protocol:¶

• Step 1 - Flow Matching and Profile Selection: Match the incoming packet against the configured flow-matching criteria and select the associated IOAM Encapsulation Profile, which provides the insertion offset and IOAM Option-Type parameters.¶
• Step 2 - Insertion Point Calculation: Compute the insertion point as the sum of the reference position and the provisioned insertion offset.¶
• Step 3 - Constraint Validation: Verify that the IOAM Data-Fields to be inserted satisfy the transport-specific constraints (e.g., maximum option size, alignment requirements, MTU limits).¶
• Step 4 - Data-Field Insertion: Expand the packet at the computed insertion point and write the IOAM Option-Type header and associated IOAM Data-Fields.¶
• Step 5 - Header Consistency Update: Update all affected header fields in the encapsulating protocol and any outer encapsulations to reflect the new packet size and structure.¶
• Step 6 - Integrity Verification: Recompute any checksums or integrity fields that cover the modified portions of the packet.¶

5. Insertion Point Provisioning

The insertion point for IOAM Data-Fields is not determined through runtime parsing of the transport protocol header. Instead, it is provisioned as part of the IOAM Encapsulation Profile, which is configured on the IOAM encapsulating node. This approach confines all protocol-specific knowledge to the configuration plane, enabling the data plane insertion procedure to operate uniformly across different transport protocols.¶

6. Insertion Point Calculation

At runtime, when a packet matches the flow-matching criteria of an IOAM Encapsulation Profile, the encapsulating node computes the insertion point: Insertion_Point = Reference_Position + Insertion_Offset. The reference position is typically the byte position of the start of the Layer 3 (network layer) header. For tunneled packets, the reference position corresponds to the start of the outermost encapsulating header that is relevant to the IOAM-Domain.¶

The insertion offset MUST satisfy the following requirements: (a) it MUST point to a location within the legitimate extension area of the transport protocol; (b) it MUST account for any alignment requirements imposed by the transport protocol (e.g., IPv6 IOAM options require 4-octet alignment as specified in [RFC9486]); (c) it MUST NOT point into the immutable fixed-length portion of the transport header or into the packet payload beyond the transport header's extension area. If the computed insertion point does not satisfy these requirements, the encapsulating node MUST NOT insert IOAM Data-Fields and SHOULD increment an error counter.¶

7. Constraint Validation

Before inserting IOAM Data-Fields, the encapsulating node MUST verify that the insertion will not violate any transport-specific constraints.¶

8. IOAM Data-Field Insertion

Once the insertion point has been computed and constraints have been validated, the encapsulating node performs the actual insertion.¶

9. Header Consistency Update

After IOAM Data-Fields have been inserted, the enclosing protocol headers must be updated to reflect the modified packet structure. The encapsulating node MUST update all length fields affected by the insertion (IPv6 Payload Length and Hdr Ext Len for IPv6; NSH Length field for NSH; outer IP Total Length for GRE; UDP Length plus tunnel-specific length for UDP-encapsulated protocols). Length fields in any outer encapsulation layers MUST also be updated.¶

The encapsulating node MUST recompute checksums covering modified packet portions. If IOAM is within a UDP-encapsulated protocol and the UDP checksum is non-zero, it MUST be recomputed. If the IOAM Data-Fields include a Checksum Complement field [RFC9197], the node MAY perform a checksum-neutral update. If an outer IPv4 header Total Length was updated, the IPv4 header checksum MUST be recomputed.¶

When IOAM Data-Fields are inserted using a shim header or new extension header, the encapsulating node MUST update the relevant next-header or next-protocol pointers. For IPv6, the Next Header field of the preceding header MUST point to the new extension header. For NSH, the Next Protocol field MUST indicate IOAM. For EtherType-based shim headers (GRE, Geneve), the Protocol Type or EtherType field MUST be set to the IOAM shim value, and the IOAM shim's Next Protocol field MUST indicate the original inner protocol.¶

10. IOAM Data-Field Removal

The IOAM decapsulating node reverses the encapsulation process: (1) identify the IOAM Data-Fields based on protocol-specific indicators; (2) extract and process the IOAM Data-Fields; (3) remove the IOAM Option-Type header, Data-Fields, and associated padding, shifting subsequent octets toward the beginning of the packet; (4) perform the header consistency update in reverse: decrement length fields, recompute checksums, and restore next-header/protocol pointers. The removal MUST be performed atomically. IOAM-Domain boundary nodes MUST remove IOAM Data-Fields before forwarding packets outside the IOAM-Domain [RFC9378].¶

11. Applicability to Existing and Future Protocols

For IPv6 [RFC9486]: reference position is the start of the IPv6 header; insertion offset points to the options area within the Hop-by-Hop or Destination Options header; alignment requirement is 4 octets; maximum option size is 255 octets; header consistency update covers IPv6 Payload Length and Hdr Ext Len.¶

For NSH [RFC9452]: reference position is the start of the NSH Base Header; insertion offset points past the Service Path Header; IOAM is indicated through the Next Protocol field; header consistency update covers the NSH Length field.¶

For EtherType-Based Encapsulations (GRE, Geneve): reference position is the start of the outer IP header; insertion offset spans the outer IP header, any UDP header, and the tunnel header; IOAM is indicated through the Protocol Type or EtherType value; header consistency update covers outer IP length fields and any applicable UDP checksum.¶

When specifying IOAM encapsulation for a new transport protocol, the specification SHOULD reference this document and provide: (a) the reference position for IOAM insertion, (b) the method for indicating IOAM presence in the header chain, (c) protocol-specific size, alignment, or ordering constraints, and (d) the header fields requiring update. This approach enables new encapsulation specifications to be concise.¶

12. Security Considerations

The common procedures inherit all security considerations from [RFC9197] and [RFC9378].¶

An incorrectly configured insertion offset could cause IOAM data to overwrite critical header fields or payload data, leading to packet corruption, forwarding failures, or information leakage. Implementations MUST validate that the computed insertion point falls within the legitimate extension area before performing insertion. Implementations MUST reject offset configurations that would place IOAM data outside protocol-defined boundaries. Operators SHOULD validate offset configurations in a controlled environment before production deployment.¶

The procedures in this document MUST only be performed within an IOAM-Domain [RFC9197]. Domain boundary nodes MUST ensure IOAM packets do not leak outside the domain. The filtering requirements in [RFC9486] and [RFC9378] apply to all transport protocols using these procedures.¶

An attacker influencing IOAM configuration might configure excessively large IOAM Data-Fields or incorrect offsets, causing packet drops or malformed packets. The constraint validation step mitigates this by requiring pre-insertion checks. Because the insertion offset is provisioned through the configuration plane, unauthorized modification could cause widespread packet corruption. Operators MUST protect the configuration channel using authentication and access control. The YANG module security considerations in [RFC9617] apply to IOAM Encapsulation Profile configuration.¶

13. IANA Considerations

This document has no IANA actions. It defines common operational procedures for existing IOAM Data-Fields and Option-Types defined in [RFC9197] and introduces no new protocol identifiers or registry entries.¶

Acknowledgements

The authors would like to thank the members of the IPPM Working Group for their review and feedback. The existing body of IOAM encapsulation specifications, particularly the work by Frank Brockners, Shwetha Bhandari, Tal Mizrahi, and their collaborators, provided the foundation upon which these common procedures are defined.¶

Authors' Addresses