.\"	$OpenBSD: mbuf_tags.9,v 1.43 2021/05/15 08:07:20 yasuoka Exp $
.\"
.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu)
.\"
.\" Copyright (c) 2001 Angelos D. Keromytis
.\"
.\" Permission to use, copy, and modify this software with or without
.\" fee is hereby granted, provided that this entire notice is included
.\" in all source code copies of any software which is or includes a copy
.\" or modification of this software.
.\"
.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
.\" PURPOSE.
.\"
.Dd $Mdocdate: May 15 2021 $
.Dt M_TAG_GET 9
.Os
.Sh NAME
.Nm m_tag_get ,
.Nm m_tag_find ,
.Nm m_tag_prepend ,
.Nm m_tag_delete ,
.Nm m_tag_copy ,
.Nm m_tag_delete_chain ,
.Nm m_tag_init ,
.Nm m_tag_copy_chain ,
.Nm m_tag_first ,
.Nm m_tag_next
.Nd a framework for generic packet attributes
.Sh SYNOPSIS
.In sys/mbuf.h
.Ft "struct m_tag *"
.Fn m_tag_get "int type" "int len" "int flags"
.Ft "struct m_tag *"
.Fn m_tag_find "struct mbuf *mbuf" "int type" "struct m_tag *tag"
.Ft void
.Fn m_tag_prepend "struct mbuf *mbuf" "struct m_tag *tag"
.Ft void
.Fn m_tag_delete "struct mbuf *mbuf" "struct m_tag *tag"
.Ft "struct m_tag *"
.Fn m_tag_copy "struct m_tag *tag"
.Ft void
.Fn m_tag_delete_chain "struct mbuf *mbuf"
.Ft void
.Fn m_tag_init "struct mbuf *mbuf"
.Ft int
.Fn m_tag_copy_chain "struct mbuf *mbuf" "struct mbuf *mbuf2"
.Ft "struct m_tag *"
.Fn m_tag_first "struct mbuf *mbuf"
.Ft "struct m_tag *"
.Fn m_tag_next "struct mbuf *mbuf" "struct m_tag *tag"
.Sh DESCRIPTION
These functions allow the manipulation of generic packet attributes.
They are used by the kernel to keep track of operations done or
scheduled to happen to packets.
These attributes are attached to
.Xr mbuf 9
packet headers.
.Pp
Mbuf tags get allocated using
.Xr pool 9 .
.Pp
.Fn m_tag_get
allocates a new tag of type
.Va type
with
.Va len
bytes of space following the tag header itself.
The
.Va flag
argument is passed directly to
.Xr pool_get 9 .
If successful,
.Fn m_tag_get
returns a memory buffer of (len + sizeof (struct m_tag)) bytes.
The first sizeof(struct m_tag) bytes contain a struct m_tag:
.Bd -literal
struct m_tag {
	SLIST_ENTRY(m_tag)	m_tag_link;	/* List of packet tags */
	u_int16_t		m_tag_id;	/* Tag ID */
	u_int16_t		m_tag_len;	/* Length of data */
};
.Ed
.Pp
The
.Va m_tag_link
field is used to link tags together (see
.Xr queue 3
for more details).
The
.Va m_tag_id
and
.Va m_tag_len
fields are set to
.Va type
and
.Va len
respectively.
Following this structure are
.Va len
bytes of space that can be used to store tag-specific information.
.Pp
The currently defined tag types are:
.Bl -tag -width PACKET_TAG_PF_REASSEMBLED
.It PACKET_TAG_IPSEC_IN_DONE
Used by
.Xr ipsec 4
to indicate successful processing performed on an input packet.
The tag contains a
.Va struct tdb_ident ,
as defined in
.Pa sys/netinet/ip_ipsp.h ,
identifying the security association under which the packet arrived.
.It PACKET_TAG_IPSEC_OUT_DONE
Used by IPsec to indicate that an output packet has been
IPsec-processed.
The tag contains a
.Va struct tdb_ident
identifying the security association applied to the packet.
This tag is primarily used to detect and avoid loops in IPsec
processing on output.
.It PACKET_TAG_IPSEC_FLOWINFO
Used by the IPv4 stack to specify the IPsec flow of an output IP packet.
The tag contains a
.Va u_int32_t
identifying the IPsec flow.
.It PACKET_TAG_WIREGUARD
Used by the
.Xr wg 4
interface to detect loops in processing.
The tag contains a pointer to the wg peer that already processed the packet.
.It PACKET_TAG_GRE
Used by the
.Xr gre 4
interface to detect loops in processing.
The tag contains a pointer to the gre interface that already processed
the packet.
.It PACKET_TAG_DLT
Used by
.Xr bpf 4
to indicate that the packet was injected.
The tag contains a
.Va u_int
identifying the data link layer type.
.It PACKET_TAG_PF_DIVERT
Indicates that the packet was diverted by
.Xr pf 4
using the
.Em divert-to
or
.Em divert-reply
directives.
The tag contains a
.Va struct pf_divert
identifying the port, address and routing domain the packet should be
diverted to.
.It PACKET_TAG_PF_REASSEMBLED
Used by
.Xr pf 4
to reassemble IPv6 fragments.
The tag contains a
.Va struct pf_fragment_tag .
.It PACKET_TAG_SRCROUTE
Used by the IPv4 stack to keep track of the source route of an incoming
IP packet, in case a protocol wants to respond over the same route.
The tag contains a
.Va struct ip_srcrt .
.It PACKET_TAG_CARP_BAL_IP
Used by
.Xr carp 4
to mark packets received in mode
.Va balancing ip .
These packets need some special treatment since they contain layer 3 unicast
inside layer 2 multicast.
The tag contains no data.
.El
.Pp
.Fn m_tag_find
finds an instance of a tag of type
.Va type
attached to packet
.Va mbuf .
If
.Va tag
is
.Dv NULL ,
the first such tag is returned.
Otherwise, the first tag of type
.Va type
after
.Va tag
is returned.
If no such tag is found,
.Dv NULL
is returned.
.Pp
.Fn m_tag_prepend
adds the new tag
.Va tag
at the head of the tag list for packet
.Va mbuf .
.Pp
.Fn m_tag_delete
removes and then de-allocates tag
.Va tag
from the list of tags of packet
.Va mbuf .
.Pp
.Fn m_tag_copy
creates an unlinked copy of tag
.Va tag .
.Pp
.Fn m_tag_delete_chain
deletes all tags attached to packet
.Va mbuf .
.Pp
.Fn m_tag_init
initializes the tag storage for packet
.Va mbuf .
.Pp
.Fn m_tag_copy_chain
copies all tags from packet
.Va mbuf
to packet
.Va mbuf2 .
On success, it returns 0.
Otherwise, it returns
.Er ENOBUFS .
.Pp
.Fn m_tag_first
returns the first tag attached to packet
.Va mbuf .
.Pp
.Fn m_tag_next
returns the tag following
.Va tag
in packet
.Va mbuf .
.Pp
The
.Fn M_MOVE_PKTHDR
and
.Fn M_MOVE_HDR
macros defined in
.Pa sys/sys/mbuf.h
move the tags from the old to the new mbuf.
.Sh CODE REFERENCES
The tag-manipulating code is contained in the file
.Pa sys/kern/uipc_mbuf2.c .
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr bridge 4 ,
.Xr gif 4 ,
.Xr gre 4 ,
.Xr ipsec 4 ,
.Xr pf 4 ,
.Xr mbuf 9
.Sh HISTORY
The packet tags first appeared in
.Ox 2.9
and were written by
.An Angelos D. Keromytis Aq Mt angelos@openbsd.org .