IOAM Data Fields for Firewall and Security Metadata

Introduction The In-situ Operations, Administration, and Maintenance (IOAM) framework provides a mechanism for collecting operational and telemetry information within the packet as it traverses the network. While IOAM defines data fields for performance metrics like timestamp, queue depth, and node identifiers, it does not currently define fields specific to security enforcement. In modern overlay networks, verifying that traffic has traversed a specific chain of security functions (e.g., firewalls, IDPS) and enforcing policy based on the state of upstream devices is critical. This document extends IOAM to support these security use cases by defining a new IOAM Namespace for "Security Metadata" and a set of data fields to carry information such as Filter IDs, Actions, Threat Levels, and Policy IDs. The primary contribution of this document is the model these fields enable, not the fields alone: by carrying a per-EP, verifiable record of the action taken, the data path itself becomes evidence that policy was executed as provisioned. This validates execution and complements the control or management plane -- the centralized system(s) that provision and distribute security policy to each Enforcement Point, such as an SDN controller, orchestrator, or security policy manager -- which validates intent (that the correct policy was provisioned). In particular, it supports detection of policy bypasses (an expected attestation is absent) and detection of action divergence scoped by Policy ID (Enforcement Points that should agree record conflicting actions). By leveraging the IOAM framework, this proposal benefits from IOAM's existing encapsulation mechanisms and the proposed integrity protection mechanisms , avoiding the need for a bespoke security metadata protocol.

Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

IOAM Security Namespace This document defines a new IOAM Namespace:

Namespace-ID: TBD (To be assigned by IANA)
Name: Security_Metadata
Description: A namespace for carrying data fields related to security enforcement, policy verification, and threat signaling.

IOAM nodes operating within this namespace MUST support the data fields defined in (#fields). The set of Enforcement Points that share key material and namespace configuration for this metadata is referred to as the Security Metadata Domain. The domain boundary is an operational decision: the operator defines which EPs participate by provisioning them, and any Validator, with the symmetric key material used for integrity protection ((#integrity)). Each participating node has its own unique key, as required by . An EP that has not been provisioned with the relevant key material is outside the Security Metadata Domain and MUST NOT be expected to produce or verify attestations. Membership in the Security Metadata Domain is scoped to the Security_Metadata Namespace-ID: a node MAY simultaneously participate in other IOAM namespaces (for example, performance monitoring or path tracing), and it reacts to this metadata only for packets carrying the Security_Metadata Namespace-ID for which it has been provisioned. This concept is analogous to the "IOAM-Domain" defined in .

Data Fields for Security Namespace The following data fields are defined for use within the Security_Metadata namespace. This section defines the semantics and natural size of each field. How these fields are encoded on the wire as IOAM-Data-Fields -- including how short fields are packed to meet IOAM's 4-octet alignment, and which fields are carried in each encoding -- is defined separately in (#encoding). Unless a specific encoding states otherwise (for example, the compact profile in (#enc-b)), the natural sizes given below apply.

Filter Node ID (32-bit) A 32-bit opaque identifier for the enforcement point that inserted the metadata. The value is unique within the administrative domain and assigned via the management plane. Note that while IOAM defines a node_id, this field allows for a specific identifier for the security function if distinct from the forwarding node.

Filter ID (32-bit) A 32-bit identifier for the specific filter or policy rule that was matched by the packet.

Filter Action (8-bit) An 8-bit value indicating the action taken by the firewall. Examples include:

0: Allow
1: Deny/Drop
2: Rate-Limit
3: Log
4: Forward (e.g., to a different service chain)

Timestamp (64-bit) A 64-bit timestamp in NTP format indicating when the action was taken. This format is a 64-bit unsigned fixed-point number, with the integer part in the first 32 bits and the fractional part in the last 32 bits.

Policy ID (32-bit) A 32-bit opaque identifier that links the enforcement action to a named security profile. While the Filter ID identifies a specific rule on a node (the "what"), the Policy ID identifies the security profile that the rule is part of (the "why"). This is critical for auditing and compliance. For example, this ID could represent a profile named pci-dss-v4.0, tenant-blue-web-tier, or iot-device-isolation. A central management system would be responsible for mapping these opaque 32-bit IDs back to their meaningful profile names.

Session ID (64-bit, OPTIONAL) A 64-bit unique identifier for the flow or session to which the packet belongs. This allows for easier correlation of metadata across multiple packets of the same flow. This identifier is typically a 64-bit hash of the packet's 5-tuple (source/destination addresses, protocol, and source/destination ports). The specific hash function is implementation-dependent; the resulting ID is treated as an opaque value used for correlation. Session ID is OPTIONAL. It provides explicit per-flow correlation, which is most valuable for forensic correlation of benign (non-threat) traffic, where no Threat ID is present to group on. Threat ID ((#threat-id)) and Session ID correlate different things and do not substitute for one another: Threat ID groups packets by which threat they match, while Session ID groups packets by which flow they belong to. In encodings where space is constrained (the compact trace-bit profile, (#enc-b)), Session ID MAY be omitted; in that case per-flow correlation falls back to the existing IOAM flow context and the underlay 5-tuple, and DDoS aggregation relies on the Threat ID in the DDoS word.

Threat ID (32-bit) A 32-bit identifier if the packet is associated with a known threat (e.g., from a threat intelligence feed).

Severity (8-bit) An 8-bit unsigned integer representing the aggregate severity, or intensity, of an event along the path. Severity expresses magnitude ("how significant is this"), complementing the Threat ID (which identifies which threat) and the Filter Action (which records the response taken). A value of 0 is informational; 255 is critical. Severity is intended to be computed by aggregation rather than set from a single node's subjective opinion. An Enforcement Point MAY raise the Severity it records when it observes corroborating evidence from multiple upstream EPs for the same flow -- for example, multiple distinct Filter Node IDs each reporting a Policer State of "red" ((#policer-state)) for the same Session ID or Threat ID. In this way Severity escalates monotonically along the path as evidence accumulates, giving downstream nodes and collectors a ready-made gradient of how distributed and intense an event is, without each node having to re-derive it. An EP that raises the Severity MUST do so by appending its own data fields with the new value; it MUST NOT alter the fields contributed by an upstream EP, so that the integrity of each EP's contribution ((#integrity)) is preserved.

Policer State (8-bit) An 8-bit enumerated value reflecting the instantaneous congestion state of a policer or rate-limiter at the enforcing node. Unlike Severity, this is an objective, locally-measured fact about a single node:

0: Green (normal; within the configured rate)
1: Yellow (approaching the configured rate limit)
2: Red (exceeding the configured rate limit)

Values 3 through 255 are reserved.

Handling Metadata Overflow This namespace does not define specific data fields for indicating metadata space exhaustion. Instead, implementations MUST utilize the standard Trace Option-Type Flag: Bit 0 (Overflow) as defined in , Section 4.2. When an IOAM node cannot add its security metadata due to lack of space in the packet, it MUST set this Overflow flag to indicate that the trace data is incomplete.

IOAM Encoding of Security Metadata (#fields) defines the security metadata fields and their natural sizes. Because does not provide a TLV container for IOAM trace data -- IOAM-Data-Fields are fixed-format, and their presence is signaled by bits in the IOAM-Trace-Type bitmap -- the security metadata must be mapped onto an IOAM-compatible encoding. This section defines three candidate encodings, all compatible with the integrity protection described in (#integrity) except where noted. The first two encodings carry the security metadata as IOAM-Data-Fields within a Trace Option-Type. This is deliberate: it is the Trace Option-Types whose Integrity-Protected variants chain the Integrity Check Value (ICV) hop by hop ((#integrity)), which is exactly the cumulative "Chain of Custody" this document relies on. To satisfy IOAM's requirement that data be aligned on 4-octet boundaries, the three single-octet fields (Filter Action, Severity, and Policer State) are packed into a single 32-bit word, used by all encodings:

Encoding A: Opaque State Snapshot This document specifies the IOAM "Opaque State Snapshot" field defined in (signaled by IOAM-Trace-Type bit 22) as the primary encoding. This field exists to carry arbitrary, schema-defined per-node state, and consists of a 1-octet Length, a 24-bit Schema ID, and a variable-length opaque data block. Because bit 22 is already defined, this encoding consumes no new Trace-Type bits. It is carried as part of each node's node-data within a Trace Option-Type, so it inherits the hop-by-hop ICV chaining of (#integrity) for free, and its variable-length block can carry the full-size fields of (#fields), including the 64-bit Session ID. The one consideration it introduces is schema distribution. leaves Schema ID distribution to an out-of-band mechanism, so the metadata is not self-describing on the wire. To make it interoperable rather than operator-private, this document defines a single fixed schema for the Security_Metadata namespace and seeks a Schema ID assignment for it ((#iana-schema)); within the Security Metadata Domain the schema is provisioned alongside the namespace configuration and per-node keys that are already required. The schema places the fields in the following order: Filter Node ID, Filter ID, Policy ID, the packed Action/Severity/Policer word, Timestamp, Threat ID, and -- when present -- Session ID.

Encoding B: Packed IOAM-Trace-Type Bits (Compact Profile) This encoding defines new IOAM-Trace-Type bits (from those available for assignment via the IETF Review process ), each signaling a fixed 4-octet word of security data:

Firewall word 1: Filter Node ID (32 bits).
Firewall word 2: Filter ID (32 bits).
Firewall word 3: Filter Action (8 bits) + Policy ID (24 bits).
DDoS word: Threat ID (16 bits) + Severity (8 bits) + Policer State (8 bits).

Timestamp reuses the existing IOAM timestamp data fields . Session ID is omitted ((#session-id)); per-flow correlation falls back to the IOAM flow context and the underlay 5-tuple, and DDoS aggregation uses the Threat ID. The profile therefore requires four new Trace-Type bits (or three, if the deployment reuses the existing IOAM node_id in place of a distinct Filter Node ID). It is compact and fixed-format, suiting high-rate hardware data paths, and inherits the ICV chaining of (#integrity). Its principal cost is that it permanently consumes scarce, globally shared Trace-Type bits, giving it the highest IANA and working-group cost of the three. To avoid spending a new bit on the DDoS word, an implementation MAY instead carry it in the existing IOAM "namespace specific data" field , at the cost of consuming that single namespace slot.

Encoding C: Dedicated Option-Type or Sub-TLV Structure This encoding defines a dedicated, TLV-structured carriage for the security metadata, analogous to the Sub-TLV design in the companion Geneve specification. Each field or group of fields is a type-length-value element, making it self-describing on the wire via an IANA type registry, supporting optional and variable fields (including the full-size Session ID), and avoiding any Trace-Type bits. Its cost is the heaviest standardization effort of the three: it requires a new IOAM Option-Type or an agreed sub-TLV structure plus an associated IANA registry. A new, custom Option-Type is also not automatically covered by the Integrity-Protected Option-Types of ; to retain the integrity leverage it would need to be registered in that document's "IOAM Integrity Protection Methods" registry, and until then does not inherit the hop-by-hop ICV chaining for free.

Comparison and Discussion The three encodings trade standardization cost against flexibility. Encoding A consumes no new Trace-Type bits, can carry all fields at full width, and inherits the integrity chain-of-custody of (#integrity) for free; its main cost is schema distribution, for which this document defines a fixed schema whose registration mechanism is left to working-group discussion ((#iana-schema)). Encoding B offers a compact, fixed-format hardware encoding at the cost of new, globally shared Trace-Type bits and reduced field widths. Encoding C offers self-describing, registry-based interoperability at the cost of the heaviest standardization effort. For concreteness, this document specifies Encoding A in full and uses it as the primary encoding. The authors believe it offers the best balance for an initial specification, but the choice among the three -- and whether more than one should ultimately be standardized -- is left open for working-group discussion, and a future revision will record the resulting consensus.

Use Cases

Firewall Use Case The primary use case for this metadata is to allow an Enforcement Point (EP) to embed a verifiable attestation of a packet's security disposition within the packet itself. This allows downstream nodes to verify and audit that security context. Each EP MUST apply its own security policy independently; the metadata enables cross-correlation and auditing of those independent decisions, not delegation of enforcement. These enforcement points (EPs) can take several forms:

Virtual Switches (vSwitches) with integrated firewalling
Cloud-native firewalls (e.g., security groups)
SmartNICs/DPUs offloading security functions
Service-chained virtual or physical firewalls

Each of these nodes can inspect the packet and insert IOAM data fields indicating the action taken (e.g., allow, deny, log), the policy that was applied, and its own identity. As is inherent to IOAM trace data, each EP appends its own fields, so a downstream node sees the accumulated attestations of all EPs on the path and can correlate them. A downstream node (e.g., the destination host, a network tap, or another firewall) can then be programmed to inspect this metadata. The downstream node does not trust the upstream decision in place of its own; it enforces its own policy and uses the metadata to verify and audit consistency across EPs. This mechanism complements, rather than replaces, the centralized control or management plane. The management plane validates intent (that the correct policy was provisioned to each EP); this metadata validates execution (that the policy was actually applied on the data path). This is valuable because:

Intent may be provisioned correctly while execution diverges (e.g., a software bug, stale rule, or hardware fault).
Out-of-band validation of execution is costly (packet sampling, log analysis), less reliable (clock skew and race conditions when correlating events across EPs), and incomplete (bounded by the sampling rate).

This enables several key security capabilities:

Verification of Enforcement: The downstream node can verify that the packet has been stamped by all expected security nodes, proving it passed through all required checkpoints. This differs from proof-of-transit mechanisms (such as the IOAM POT Option-Type ), which prove only that a packet traversed a predefined set of nodes: a node can satisfy proof-of-transit while its security function is disabled, fail-open, or applying a stale rule. By attesting the action actually taken (the Filter Action and Policy ID), this metadata validates that the security function executed and records what it decided, not merely that the node was on the path.
Detection of Policy Bypasses: If a packet arrives missing a TLV from an expected enforcement point, it indicates a potential bypass due to misconfiguration, a policy routing error, implementation failure, or a malicious attack. This capability enables alarms such as:
Detection of Action Mismatches: The metadata allows for the detection of conflicting actions, scoped by the Policy ID ((#policy-id)). Divergence is interpreted as follows:
- Same Policy ID, different Action -> ALARM. If two EPs both reference the same Policy ID but record conflicting actions for the same packet (e.g., one ALLOW, one DENY), this indicates that two EPs that SHOULD agree do not -- typically due to a failed configuration push, stale rules, or compromise. This is reported as a POLICY_ACTION_MISMATCH: "Policy violation detected: Mismatching action from node 0x192A44B1 (FW02-Datacenter-Core) (allowed a packet which should have been dropped) -- POLICY_ACTION_MISMATCH."
- Different Policy ID, different Action -> no alarm. If the EPs reference different Policy ID values, they are applying different policies at different points in the hierarchy (e.g., a perimeter allow policy and a downstream microsegmentation policy). An ALLOW/DENY divergence here is intentional policy layering and does NOT trigger an alarm.
Auditing and Compliance: The collected metadata can be stored for subsequent analysis, enabling cross-vendor auditing, compliance verification, and supporting zero-trust security models.

In cases of detected policy bypass or action mismatch, the Enforcement Point can utilize IOAM Direct Export to immediately send the conflicting packet headers and metadata to a security collector for forensic analysis, even if the packet itself is subsequently dropped.

DDoS Use Case

Inband Metadata-Driven Mitigation: Because the threat metadata travels inband with the packets themselves, a downstream node can act directly on each marked packet, using the embedded signal to drive its own resource-allocation, scheduling, and state-retention decisions for that traffic.
Distributed DDoS "Heat Map" and Real-time Mitigation: The metadata can be used to create a distributed "heat map" of a DDoS attack. An EP acting as a policer/rate-limiter, when experiencing a high rate of traffic (above configured allowed limits), can embed its Filter Node ID, its Policer State (e.g., "red"), Threat ID, and Session ID into the metadata of the (allowed) packets it forwards. This provides a granular, per-packet signal about network stress. The division of labor across these fields is deliberate: Threat ID identifies what the traffic is, Policer State is each node's objective report of its own congestion, and Severity is the aggregate magnitude a downstream node computes from many such reports. This enables a powerful two-tiered analysis model:
- Tactical Mitigation: A downstream aggregation EP can monitor this metadata. If it observes a "red" Policer State from multiple distinct upstream Filter Node IDs for the same flow (e.g., matching the same Session ID, Filter ID, or Threat ID), it can raise the Severity accordingly ((#severity)) and perform immediate, localized mitigation, such as shunting the flow to a scrubbing appliance or applying a more aggressive filter. Because Severity escalates as corroborating reports accumulate, a single threshold on Severity lets further-downstream nodes act without re-counting the underlying reports.
- Strategic Analysis: Concurrently, this metadata can be exported via telemetry (e.g., using IOAM Direct Export ) or packet mirroring to a central controller, which aggregates the data from all EPs to build a global, real-time visualization of the attack's path and intensity, enabling strategic response and detailed forensic analysis. This provides a valuable piece of telemetry to the central controller. The message can effectively say, "A distributed attack with Threat ID 123 has been detected, originating from sources A, B, and C, and flowing towards target Y." This provides the central controller with a real-time "attack path," allowing it to construct a global "attack graph" and make more intelligent, strategic decisions.
Intelligent Load Balancing: Downstream load balancers and routing nodes can utilize the Policer State or Severity metadata to dynamically route traffic away from stressed security nodes or congested paths. This enables both security and routing elements to use the security signal as a routing metric, optimizing network performance and resilience by steering traffic toward less-stressed or alternate routes. This allows for real-time, distributed, and autonomous mitigation of DDoS and overload scenarios.

Enforcement Model: Verify-or-Drop Each enforcement point (EP) MUST apply its own security policy independently. Verification of upstream security metadata is an additional capability layered on top of independent enforcement; it is not a prerequisite for, nor a replacement of, an EP's own inspection. An EP never delegates its enforcement decision to an upstream EP based on the metadata it carries. A key property of this model is that the absence of an expected attestation is itself a security event. When an EP cannot verify the metadata it expects (because the attestation is missing, was stripped in transit, or fails the integrity check defined in (#integrity)), its behavior is determined by local policy:

Strict mode ("Verify-or-Drop"): Unverifiable or missing expected metadata is treated as absent, triggering a POLICY_VIOLATION_BYPASS alarm and, optionally, a packet drop. This is appropriate for high-security environments (e.g., PCI compliance zones).
Permissive mode: The EP logs the event, enforces its own policy independently, and forwards the packet. This is appropriate during migration, key rotation, or in multi-tenant environments where not all EPs are provisioned for all security domains.
Non-participant nodes: An EP that has never been provisioned with the relevant key material simply forwards the packet with the metadata intact. The metadata passes through opaquely, as any other IOAM data field would.

In all cases, the EP enforces its own security policy regardless of whether it can verify the metadata.

Integrity Protection The security metadata defined in this document is sensitive. If modified by an attacker, it could allow malicious traffic to bypass security checks or trigger false alarms. Because the data path may traverse untrusted or semi-trusted segments, the authenticity and integrity of these attestations MUST be protected. Therefore, implementations of this namespace MUST carry the Security_Metadata data fields within one of the Integrity-Protected Option-Types defined in , rather than within an unprotected IOAM Option-Type. That document does not add an "integrity flag" to an existing header. Instead, it defines new Integrity-Protected Option-Types -- corresponding to the Pre-allocated Trace, Incremental Trace, POT, and E2E Option-Types of -- and inserts an Integrity Protection header between the IOAM Option-Type header and the IOAM-Data-Fields. The Integrity Protection header carries:

a Method ID identifying the integrity method;
a Nonce (12 octets); and
an Integrity Check Value (ICV).

The integrity method is AES-GMAC (Method ID 0), and the ICV is the full 16-octet GMAC authentication tag; it MUST NOT be truncated. The 12-octet nonce is constructed from a Key ID, the Encapsulating Node ID, and a per-packet counter, so that a key-nonce pair is never reused. Each participating node uses its own unique symmetric key, distributed only to that node and to any Validator that must verify its contribution. When the Integrity-Protected Pre-allocated Trace or Incremental Trace Option-Type is used, each Enforcement Point folds the security data fields it appends into the ICV by computing the GMAC over the received ICV concatenated with its own immutable data fields. This produces a cumulative, hop-by-hop chain that a Validator can verify to confirm that the attestation contributed by each Enforcement Point on the path is intact and was not altered by a later node. This is the cryptographic realization of the "Chain of Custody" described in this document. The Direct Export (DEX) Option-Type carries no IOAM-Data-Fields and is explicitly out of scope for this integrity mechanism; security metadata that must be integrity protected therefore MUST NOT rely on DEX as its carrier. DEX retains its role in exporting already-collected metadata to a collector ((#firewall)). The scope of this verifiability is bounded by the Security Metadata Domain ((#namespace)): only nodes provisioned with the relevant key material can produce or verify these attestations. Operators SHOULD scope key material to the smallest practical domain (for example, per-tenant or per-security-zone) rather than using a single global key for the entire deployment, which would create a single point of compromise.

IANA Considerations This document makes the following requests of IANA.

IOAM Namespace-ID IANA is requested to assign a new IOAM Namespace-ID for "Security_Metadata" from the "IOAM Namespace-ID" registry.

Security Metadata Schema ID (Encoding A) For the Opaque State Snapshot encoding ((#enc-a)), IANA is requested to assign a Schema ID identifying the fixed Security_Metadata schema defined in this document (the field order given in (#enc-a)). Because scopes Schema IDs to an IOAM-Namespace and does not define a global Schema ID registry, the exact registration mechanism is an open item for working-group discussion; one option is to record the assignment within the Security_Metadata namespace definition.

IOAM-Trace-Type Bits (Encoding B) If the compact trace-bit profile ((#enc-b)) is adopted, IANA is requested to assign new bits in the "IOAM Trace-Type" registry, via the IETF Review process, for the firewall and DDoS words defined in (#enc-b).

Security Metadata Type Registry (Encoding C) If the dedicated TLV encoding ((#enc-c)) is adopted, IANA is requested to create a "Security Metadata Type" registry enumerating the field types defined in (#fields); and -- to retain integrity protection -- a corresponding entry would be required in the "IOAM Integrity Protection Methods" registry defined in .

Security Considerations This document defines IOAM data fields that influence security enforcement, so the authenticity and integrity of these fields is paramount. Forgery, tampering, and replay are addressed by carrying the Security_Metadata fields within an Integrity-Protected Option-Type as described in (#integrity); that mechanism, defined in , provides the AES-GMAC authentication, the per-node ICV chaining, and the nonce-based replay protection on which this document relies. This document does not define its own cryptography and does not restate those guarantees. The scope of any compromise is bounded by the Security Metadata Domain ((#namespace)). Because each participating node uses its own unique symmetric key, the disclosure of one node's key allows an attacker to forge only that node's contribution, not the attestations of other nodes on the path. Operators SHOULD scope key material to the smallest practical domain (for example, per-tenant or per-security-zone) rather than provisioning a single global key, which would create a single point of compromise. The data fields themselves are opaque, locally scoped identifiers (for example, Filter Node ID, Policy ID, and Threat ID) and are carried without encryption, as is normal for IOAM data fields. Without the operator's out-of-band mapping, an on-path observer cannot derive their semantics; the residual exposure is limited to correlation (observing that flows share a classification) and is no greater than that of ordinary IOAM telemetry. The aggregate Severity value ((#severity)) is computed by a node from many upstream reports; integrity protection ensures it is not altered in transit, but downstream nodes that act on it inherently trust the originating and aggregating nodes to report it honestly, which is why all participating nodes must be members of the same Security Metadata Domain.