[PATCH] 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 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.

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 <nathaniel.mccallum@amd.com>
Signed-off-by: Amanda Liem <Amanda.Liem@amd.com>
---
 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