SPICE Capabilities¶
This document describes the capability negotiation system used by the SPICE protocol. Capabilities are exchanged during the link handshake to determine which features both client and server support.
Capability Negotiation¶
During the SPICE link handshake, both client and server exchange capability bitmaps. A feature is only enabled if both sides advertise support for it. Capabilities are organized into:
- Common capabilities: Apply to all channel types
- Channel-specific capabilities: Apply only to specific channels
Capabilities Through the Proxy¶
Kerbside negotiates capabilities twice: as a server, answering the client's link, and as a client, linking to the hypervisor backend. The two directions are deliberately not symmetric.
Offered to the client. The link reply carries the RSA key the client
encrypts its ticket to, and the ticket is what selects the backend, so the
reply has to be sent before Kerbside knows which hypervisor the session will
reach. The capabilities in it are therefore a fixed table per channel type
(caps::reply_channel_caps in rust/kerbside-proxy/src/caps.rs), taken from
what spice-server itself advertises for that channel type — the table cites
the spice-server source for every bit — and reduced to what Kerbside relays.
The offered set is tabulated per channel in
Proxy Architecture, and a client
whose common capabilities lack MiniHeader or AuthSelection is refused at link
time, as the link protocol
describes.
Forwarded to the backend. The channel capabilities the client advertised
go to the backend verbatim, through caps::backend_channel_caps, which
backend::run in rust/kerbside-proxy/src/backend.rs calls for every relayed
channel. That is what lets spice-server pick image compression, stream codecs
and drawing operations for the client actually connected, rather than for
whatever the proxy's own SPICE client would ask for. The common capabilities
are forwarded too, except for the authentication bits, which describe
Kerbside's own ticket exchange with the backend rather than the client's:
AuthSpice is set and AuthSASL cleared, since the backend authenticates
Kerbside and Kerbside only performs SPICE ticket authentication. Forwarding a
client's AuthSASL would make a SASL-enabled spice-server skip the ticket key
pair Kerbside's ticket is encrypted to, for which caps.rs cites the
spice-server source. The experimental transcoding feature is the one
exception: a transcoded display channel is read by the proxy's renderer
instead of by the client, so it is dialled with the renderer's capabilities.
The Reply Mask Is Not a Security Boundary¶
The reply table bounds what Kerbside advertises as a server. It does not bound
what the session can carry. Because the client's channel capabilities reach
the backend unmasked, a client can negotiate a spice-server feature Kerbside
never offered, and spice-server will then send the messages that feature
enables. The display channel is the standing example: the reply does not offer
SizedStream, but a client that advertises it has it forwarded, and the
firewall admits the display channel's stream_data_sized (316), which
only that capability enables. A unit test in caps.rs
(unoffered_client_cap_still_admits_its_server_message) pins that case, so
this is checked rather than asserted.
Masking the forwarded capabilities down to the offered set was considered and declined, because it would be wrong on both counts:
- It would break real clients. A capability is effective only where both
ends advertise it, which is exactly why forwarding the client's set is what
makes spice-server encode for the client connected. Ryll's own default
display set (
DEFAULT_DISPLAYin itsshakenfist-spice-protocol) asks for SizedStream, Composite, A8Surface, LZ4Compression, MultiCodec and the MJPEG and H.264 codec bits, none of which the reply table offers. Clamping them would drop every guest to a slower software render path and give up LZ4 on static regions — on every session, not some unusual one. - It would buy no enforcement. The firewall's L1 allowlist classifies by opcode and never by the negotiated capability set, and on a channel whose grammar it models it is fail-closed: an opcode that grammar does not hold is a violation, which the firewall observes or terminates on according to the configured verdict. A capability cannot talk a message past it. Message bodies are not checked at all, but that is a separate layer and the reply mask would not change it either way.
Two consequences do follow from the asymmetry, and neither of them is about containment.
The first is the one to watch. Because the client's capabilities reach the backend unmasked, spice-server may send an opcode gated behind a capability Kerbside never offered, and fail-closed means an opcode the allowlist does not model would terminate a legitimate session. That is safe only because the L1 table is derived from ryll's complete per-channel message-type tables rather than from the reply table, so the opcodes an unoffered capability can enable are modelled already. If one ever is not, the fix is to model the opcode in the table; it is never to widen a verdict so the traffic passes.
The second is resource cost on the hypervisor. Forwarding a capability Kerbside never offered also lets a client turn on backend work — a video encoder, for instance — that the proxy did not advertise, so what a session costs the hypervisor is set by what the client asks for and not by the reply table.
Common Capabilities¶
These capabilities apply to all SPICE channels.
| Bit | Capability | Description |
|---|---|---|
| 0 | AuthSelection | Client can select authentication mechanism |
| 1 | AuthSpice | SPICE ticket-based authentication supported |
| 2 | AuthSASL | SASL authentication supported |
| 3 | MiniHeader | Use compact 6-byte message headers instead of 16-byte |
Mini Header Format¶
When both sides support MiniHeader, messages use a compact format:
Standard Header (16 bytes):
Offset Size Type Field
------ ---- ------ -----------
0 8 uint64 serial
8 2 uint16 type
10 4 uint32 size
14 4 uint32 sub_list
Mini Header (6 bytes):
Main Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | SemiSeamlessMigrate | Semi-seamless VM migration support |
| 1 | NameAndUuid | Server sends VM name and UUID to client |
| 2 | AgentConnectedTokens | Token-based agent connection tracking |
| 3 | SeamlessMigrate | Seamless VM migration support |
Display Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | SizedStream | Stream data messages include dimensions |
| 1 | MonitorsConfig | Multi-monitor configuration support |
| 2 | Composite | Composite drawing operations supported |
| 3 | A8Surface | 8-bit alpha-only surfaces supported |
| 4 | StreamReport | Stream quality/performance reporting |
| 5 | LZ4Compression | LZ4 image compression supported |
| 6 | PrefCompression | Client compression preference |
| 7 | GLScanout | GPU acceleration via DMA-buf scanout |
| 8 | MultiCodec | Multiple video codec support |
| 9 | CodecMJPEG | MJPEG video codec |
| 10 | CodecVP8 | VP8 video codec |
| 11 | CodecH264 | H.264/AVC video codec |
| 12 | PrefVideoCodecType | Client video codec preference |
| 13 | CodecVP9 | VP9 video codec |
| 14 | CodecH265 | H.265/HEVC video codec |
| 15 | GLScanout2 | GL scanout with multiple planes |
GL Scanout¶
When GLScanout is supported, the server can send GPU-rendered frames directly
to the client using DMA-buf file descriptors, bypassing software rendering.
GL Scanout Message (ID 133):
Offset Size Type Field
------ ---- ------ -----------
0 4 int32 fd (DMA-buf file descriptor)
4 4 uint32 width
8 4 uint32 height
12 4 uint32 stride
16 4 uint32 drm_fourcc (DRM pixel format)
20 4 uint32 flags (1=Y0_TOP)
Inputs Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | KeyScancode | Raw scancode input supported (key_scancode message) |
Playback Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | CELT_0_5_1 | CELT 0.5.1 audio codec (deprecated) |
| 1 | Volume | Per-channel volume control |
| 2 | Latency | Audio latency reporting |
| 3 | Opus | Opus audio codec |
Record Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | CELT_0_5_1 | CELT 0.5.1 audio codec (deprecated) |
| 1 | Volume | Per-channel volume control |
| 2 | Opus | Opus audio codec |
SpiceVMC Channel Capabilities¶
| Bit | Capability | Description |
|---|---|---|
| 0 | DataCompressLZ4 | LZ4 compression for VMC data |
Capability Bitmap Encoding¶
Capabilities are transmitted as a bitmap where each bit position corresponds to a specific capability. The bitmap is sent as an array of 32-bit words.
# Example: Check if capability N is supported
def has_capability(caps_bitmap, cap_num):
word_index = cap_num // 32
bit_index = cap_num % 32
return (caps_bitmap[word_index] >> bit_index) & 1
# Example: Set capability N
def set_capability(caps_bitmap, cap_num):
word_index = cap_num // 32
bit_index = cap_num % 32
caps_bitmap[word_index] |= (1 << bit_index)
Recommended Capability Set¶
For a modern SPICE client, the recommended minimum capabilities are:
Common: - AuthSelection (0) - AuthSpice (1) - MiniHeader (3)
Display: - SizedStream (0) - MonitorsConfig (1) - StreamReport (4) - LZ4Compression (5) - MultiCodec (8) - CodecMJPEG (9) - CodecVP8 (10) - CodecH264 (11)
Playback/Record: - Volume (1) - Opus (3/2)
Inputs: - KeyScancode (0)
Related Documentation¶
- Link Protocol - Capability exchange during handshake
- Protocol Overview - High-level protocol structure
- Channel Protocols - Per-channel message formats
- Keyboard Scancodes - KeyScancode capability usage
- Compression Protocols - LZ4/GLZ compression details
- Proxy Architecture - The capabilities Kerbside offers per channel, and the opcode allowlist that does the enforcing the reply mask does not