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

[Amanda Liem <Amanda.Liem@amd.com>]

From: Nathaniel McCallum <nathaniel.mccallum@amd.com>

Add an optional, feature-gated label to the virtio-net device
configuration space: a short, read-only string describing a single device
instance. This field is modeled on VIRTIO_NET_F_MTU - it is static and
read at device initialization, without a control virtqueue.

Two read-only fields are appended to struct virtio_net_config, present
only when VIRTIO_NET_F_LABEL (net feature bit 71) is negotiated: label_len
(1..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. Two reserved octets follow, keeping a later appended field
64-bit aligned. A fixed buffer (not a flexible array) keeps future fields
appendable; existing offsets are unchanged.

A guest with several virtio-net devices uses the label to find which one
plays a role it requires - for example the device that receives inbound
connections on port 443 from the internet, which it cannot tell from the
device itself. The label names an out-of-band contract the guest expects.
The guest matches the presented label against the one the contract calls
for, so the label only locates a device and conveys no trust. A wrong
label can only deny the guest its device, a denial of service that is
always possible. It cannot make the guest trust a device the contract
would reject. A contract and its enforcement are outside the scope of this
specification.

Signed-off-by: Nathaniel McCallum <nathaniel.mccallum@amd.com>
Signed-off-by: Amanda Liem <Amanda.Liem@amd.com>
---

Link: https://lore.kernel.org/virtio-comment/20260818170552.2127-1-Amanda.Liem@amd.com/ [v1]
Link: https://lore.kernel.org/virtio-comment/20260924153024.3362-1-Amanda.Liem@amd.com/ [v2]
Link: https://lore.kernel.org/virtio-comment/20261027154836.13778-1-Amanda.Liem@amd.com/ [v3]

v1 -> v2: add motivation and config-space-vs-CVQ rationale; fix the
  feature-bit note (Parav)
v2 -> v3: require label_len 1..MAX; spell out the over-length error as a
  device error with FAILED (Matias)
v3 -> v4:
  - Reframe: explain the purpose - the label names an out-of-band contract
    the guest expects and matches against to find its device - and that the
    label conveys no trust and need not be unique (Michael)
  - Drop the acknowledgements.tex change (Michael)
  - Remove "host" from the spec text; the device provides the label
    (Michael)
  - Pad struct virtio_net_config with 2 reserved octets so a field
    appended after the label stays 64-bit aligned (Michael)
  - Reword the comparison text as driver-side matching, drop "consumer"
    (Michael)
  - Note identical labels may occur in the same guest or in different
    guests (Matias)
  - Remove the informative security-considerations note; its one normative
    rule (no routing/identity/trust decision from the label) already lives
    in the driver requirements (Michael, Matias)
 device-types/net/description.tex | 92 ++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/device-types/net/description.tex b/device-types/net/description.tex
index 9f85bf4..e8419f7 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 for this
+    device instance through the \field{label_len} and \field{label}
+    configuration fields. A driver uses the label to identify which
+    device matches a value it expects. The label is human-readable, and
+    its meaning is defined outside this specification.
+
 \end{description}
 
 \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements}
@@ -220,9 +226,16 @@ \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];
+        u8 padding[2];
 };
 \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 +289,45 @@ \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 fields, \field{label_len}, \field{label}, and
+\field{padding}, only exist if VIRTIO_NET_F_LABEL is set.
+\field{label_len} and \field{label} together convey a human-readable
+label that identifies this device instance, which a driver matches
+against a value it expects.
+
+\field{label_len} specifies the length, in octets, of the label
+value, between 1 and VIRTIO_NET_LABEL_MAX inclusive. A device with no
+label for an instance does not offer VIRTIO_NET_F_LABEL for that
+instance rather than offering an empty value.
+
+\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.
+
+\field{padding} has no meaning and is reserved for future use. This is
+set to zero by the device. It keeps a field appended after \field{label}
+64-bit aligned.
+
+The specification defines no semantics for the label: 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 can present identical labels,
+whether in the same guest or in different guests.
+
+A driver that matches the label against a value it expects compares
+the two octet-by-octet: they are equal if and only if they have the
+same length and the same octets. The device does not normalize or
+case-fold the value, so a driver that needs Unicode normalization or
+case-insensitive matching performs that itself.
+
+The value can contain bidirectional or zero-width characters, which
+are legitimate in many scripts. The device does not emit control or
+separator characters, but a driver that displays the label can render
+it in isolation so that any bidirectional characters cannot reorder
+surrounding text.
+
 \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 +378,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 1 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 +440,25 @@ \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}. A compliant device
+sets \field{label_len} within range, so a \field{label_len} greater
+than VIRTIO_NET_LABEL_MAX indicates a device error: the driver MUST NOT
+read \field{label} beyond VIRTIO_NET_LABEL_MAX octets, MUST NOT use the
+label value, and SHOULD set the FAILED \field{device status} bit (see
+\ref{sec:Basic Facilities of a Virtio Device / Device Status Field}).
+
+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{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.34.1