RE: [PATCH] virtio-net: Add VIRTIO_NET_F_LABEL for a per-instance label

> From: Amanda Liem <[email protected]>
> Sent: 18 August 2026 10:36 PM
> 
> [You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> From: Nathaniel McCallum <[email protected]>
> 
> Add an optional, feature-gated string to the network device
> configuration space: a host-provided, guest-readable label
> describing a single device instance. The field is modeled on
> VIRTIO_NET_F_MTU and lives in config space so that it is plumbed
> identically across the PCI, MMIO and CCW transports from one
> definition.

Please add the motivation for this addition describing what problem exists and how does this addition solve it.
And also have you considered querying this field via CVQ.
If yes, than please explain the motivation to place this in config space.

> 
> Two read-only fields are appended to struct virtio_net_config,
> present only when VIRTIO_NET_F_LABEL is negotiated: label_len
> (0..VIRTIO_NET_LABEL_MAX) and a fixed VIRTIO_NET_LABEL_MAX (64)
> octet label buffer holding length-delimited, well-formed UTF-8
> that is not NUL-terminated. A fixed buffer (not a flexible array)
> keeps future fields appendable; existing offsets are unchanged.
> 
> Device requirements: offer the bit only when the fields are
> populated; keep label_len <= MAX; emit well-formed UTF-8; keep the
> value stable for the device lifetime with no config-change
> interrupt; and never emit NUL, C0, DEL/C1, U+2028 or U+2029.
> 
> Driver requirements: do not touch the fields unless negotiated;
> read label_len first and treat a value above MAX as a device error
> with no out-of-bounds read; read exactly label_len octets; and make
> no routing, identity or trust decision from the value, derive no
> interface name from it, and assume no uniqueness or persistence.
> 
> Comparison is byte-wise and never normalized or case-folded; the
> spec guarantees no uniqueness. Bidirectional and zero-width
> characters remain permitted because their hazard is contextual; an
> informative section places sanitization at the rendering layer and
> notes that on an untrusted host the label is attacker-controlled.
> 
> The feature uses net device-specific bit 71, the next free bit
> (0-70 are in use).
> 
> Signed-off-by: Nathaniel McCallum <[email protected]>
> Signed-off-by: Amanda Liem <[email protected]>
> ---
>  acknowledgements.tex             |   1 +
>  device-types/net/description.tex | 113 +++++++++++++++++++++++++++++++
>  2 files changed, 114 insertions(+)
> 
> diff --git a/acknowledgements.tex b/acknowledgements.tex
> index 9a9f8b4..3394bbc 100644
> --- a/acknowledgements.tex
> +++ b/acknowledgements.tex
> @@ -22,6 +22,7 @@ \subsection*{Participants}
>  Martin Kröning, Eonerc \newline
>  Matias Ezequiel Vara Larsen, Red Hat \newline
>  Michael S. Tsirkin, Red Hat \newline
> +Nathaniel McCallum, AMD \newline
>  Laura Loghin, Amazon \newline
>  Lei He, Bytedance \newline
>  Paolo Abeni, Red Hat \newline
> diff --git a/device-types/net/description.tex b/device-types/net/description.tex
> index 9f85bf4..f1d1474 100644
> --- a/device-types/net/description.tex
> +++ b/device-types/net/description.tex
> @@ -146,6 +146,12 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits
>   when VIRTIO_NET_F_IPSEC is negotiated. When a device offers IPsec feature, it SHOULD
>   also offer the VIRTIO_NET_F_OUT_NET_HEADER feature.
> 
> +\item[VIRTIO_NET_F_LABEL(71)] The device provides a label string
> +    describing this instance. If offered by the device, the device
> +    advises the driver of a host-provided, human-readable label for
> +    this network device instance through the \field{label_len} and
> +    \field{label} configuration fields.
> +
>  \end{description}
> 
>  \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements}
> @@ -220,9 +226,15 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
>          le16 rss_max_indirection_table_length;
>          le32 supported_hash_types;
>          le32 supported_tunnel_types;
> +        le16 label_len;
> +        u8 label[VIRTIO_NET_LABEL_MAX];
>  };
>  \end{lstlisting}
> 
> +\begin{lstlisting}
> +#define VIRTIO_NET_LABEL_MAX     64
> +\end{lstlisting}
> +
>  The \field{mac} address field always exists (although it is only
>  valid if VIRTIO_NET_F_MAC is set).
> 
> @@ -276,6 +288,42 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
>  Encapsulation types are defined in \ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets /
>  Hash calculation for incoming packets / Encapsulation types supported/enabled for inner header hash}.
> 
> +The following two fields, \field{label_len} and \field{label}, only
> +exist if VIRTIO_NET_F_LABEL is set. Together they convey a
> +host-provided, human-readable label describing this network device
> +instance.
> +
> +\field{label_len} specifies the length, in octets, of the label
> +value, between 0 and VIRTIO_NET_LABEL_MAX inclusive.
> +
> +\field{label} contains the label value as exactly \field{label_len}
> +octets of well-formed UTF-8 text. The value is length-delimited and
> +is not NUL-terminated; octets of \field{label} beyond \field{label_len}
> +are unused and have no meaning. The remaining octets of the
> +VIRTIO_NET_LABEL_MAX-octet buffer are reserved.
> +
> +The label is descriptive only. It carries no semantics defined by
> +this specification: it does not name a network, identify a tenant,
> +or establish trust, and the device does not guarantee that it is
> +unique or that it persists across reboot or migration. Two device
> +instances MAY present identical labels.
> +
> +Labels are compared octet-by-octet: two labels are equal if and only
> +if their \field{label_len} values are equal and their first
> +\field{label_len} octets are equal. Labels are never normalized or
> +case-folded before comparison. The UTF-8 encoding of the value and
> +the octet-wise rule for comparing values are independent: a consumer
> +that requires Unicode normalization or case-insensitive matching
> +performs it itself, and a consumer that requires labels to be unique
> +enforces uniqueness itself.
> +
> +The value MAY contain bidirectional or zero-width characters, which
> +are legitimate in many scripts. The hazard such characters pose is
> +contextual to how the value is later rendered and is addressed at the
> +rendering layer (see \ref{sec:Device Types / Network Device / Device configuration layout / Label security considerations}),
> +not by restricting the value itself; the value-level restrictions
> +below cover only context-free hazards.
> +
>  \devicenormative{\subsubsection}{Device configuration layout}{Device Types / Network Device / Device configuration layout}
> 
>  The device MUST set \field{max_virtqueue_pairs} to between 1 and 0x8000 inclusive,
> @@ -326,6 +374,27 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
>  The device SHOULD NOT offer VIRTIO_NET_F_CTRL_RX_EXTRA if it
>  does not offer VIRTIO_NET_F_CTRL_VQ.
> 
> +The device MUST NOT offer VIRTIO_NET_F_LABEL unless it populates
> +\field{label_len} and \field{label}.
> +
> +If it offers VIRTIO_NET_F_LABEL, the device MUST set \field{label_len}
> +to between 0 and VIRTIO_NET_LABEL_MAX inclusive.
> +
> +If it offers VIRTIO_NET_F_LABEL, the device MUST set the first
> +\field{label_len} octets of \field{label} to well-formed UTF-8.
> +
> +If it offers VIRTIO_NET_F_LABEL, the device MUST NOT include in the
> +first \field{label_len} octets of \field{label} any of the following:
> +the NUL character (U+0000); any C0 control character (U+0000 to
> +U+001F); the DEL character (U+007F) or any C1 control character
> +(U+0080 to U+009F); the line separator (U+2028); or the paragraph
> +separator (U+2029).
> +
> +The device MUST NOT modify \field{label_len} or \field{label} once
> +VIRTIO_NET_F_LABEL has been negotiated; the value is stable for the
> +lifetime of the device, and the device MUST NOT signal a configuration
> +change for these fields.
> +
>  \drivernormative{\subsubsection}{Device configuration layout}{Device Types / Network Device / Device configuration layout}
> 
>  The driver MUST NOT write to any of the device configuration fields.
> @@ -367,6 +436,50 @@ \subsection{Device configuration layout}\label{sec:Device Types / Network Device
>  A driver SHOULD NOT negotiate VIRTIO_NET_F_CTRL_RX_EXTRA if it
>  does not negotiate VIRTIO_NET_F_CTRL_VQ.
> 
> +The driver MUST NOT read \field{label_len} or \field{label} unless
> +VIRTIO_NET_F_LABEL has been negotiated.
> +
> +If the driver negotiates VIRTIO_NET_F_LABEL, it MUST read
> +\field{label_len} before reading \field{label}, and it MUST treat a
> +\field{label_len} greater than VIRTIO_NET_LABEL_MAX as a device error
> +and MUST NOT read \field{label} beyond VIRTIO_NET_LABEL_MAX octets.
> +
> +If the driver reads \field{label}, it MUST read exactly
> +\field{label_len} octets.
> +
> +The driver MUST NOT make any routing, identity, or trust decision
> +based on \field{label}, MUST NOT derive the network interface name
> +from it, and MUST NOT assume that the value is unique or that it
> +persists across reboot or migration.
> +
> +\subsubsection{Label security considerations}\label{sec:Device Types / Network Device / Device configuration layout / Label security
> considerations}
> +
> +\begin{note}
> +This section is informative.
> +
> +The label is supplied by the host and is not measured. Whether it can
> +be trusted is a property of the deployment, not of the field. Where the
> +host is part of the guest's trusted computing base (a conventional
> +virtual machine), the value may be used as provided. Where the host is
> +outside that boundary (for example, a confidential virtual machine
> +whose memory and execution are protected from the host), the label is
> +attacker-controlled: on its own it is evidence of nothing. It carries
> +weight only insofar as the guest corroborates it against state the host
> +cannot influence; how to corroborate it, and how far to trust the
> +result, are concerns of the guest's design and are out of scope here.
> +This specification only defines how the value is conveyed; trust
> +decisions are made by software layered above the driver.
> +
> +Any layer that renders the label to a text sink sanitizes it first: it
> +drops control and separator characters and renders the value in
> +isolation so that bidirectional formatting characters within it cannot
> +reorder surrounding text. The value-level restrictions on the device
> +(above) remove only context-free hazards; bidirectional and zero-width
> +characters remain permitted because their hazard depends on the
> +rendering context and is therefore addressed where the value is
> +rendered.
> +\end{note}
> +
>  \subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout /
> Legacy Interface: Device configuration layout}
>  \label{sec:Device Types / Block Device / Feature bits / Device configuration layout / Legacy Interface: Device configuration layout}
>  When using the legacy interface, transitional devices and drivers
> --
> 2.43.0
>