[Qemu-devel] [PATCH] specs: mandate qcow2 v2 end-of-extensions in v3 header

[Eric Blake]

At least libvirt 0.10.2 has a bug where it can be provoked
into attempting to search for extension headers (in particular,
the backing file format header) without first validating that
a particular file is qcow2 version 2.  Fortunately, to date,
this probe always ends early when feeding a version 3 file to
this version of libvirt: the version 2 file treats bytes 72-75
as the magic number for an extension header, while version 3
treats it as the upper half of the 8-byte incompatible_features
field.  As long as we don't have that many incompatible
features, these bytes are always 0, which aligns with the
end-of-extension magic number, and forces the broken libvirt to
quit looking for other headers in its v2 view of the world.
But as future extensions may conceivably contain contents that
would cause broken libvirt to misbehave if it kept looking for
headers, it is better to codify this into the qcow2 v3
specification.

No qemu code changes are required by this doc patch - anyone
setting bits within bytes 72-75 already causes the file to
be rejected as an invalid qcow2 v3 file by all current v3
implementations.  And cutting the field from 8 bytes to 4
has no real serious consequence - if we ever have that many
incompatible bits in the future, we can always declare bit 31
as an incompatible feature bit that says where else to look
for any further needed incompatible feature bits.

[If we had a time machine, I would propose that we make bytes
72-79 of the version 3 header resemble a well-formed extension
header of version 2, and move incompatible_features to offset
80 or later - but that's what we get for having hindsight.]

* docs/specs/qcow2.txt: Formally define what happened to be an
accidental feature protecting us from buggy v2 clients.

Signed-off-by: Eric Blake <address@hidden>
---
 docs/specs/qcow2.txt | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt
index f19536a..3acb46e 100644
--- a/docs/specs/qcow2.txt
+++ b/docs/specs/qcow2.txt
@@ -71,9 +71,23 @@ If the version is 3 or higher, the header has the following 
additional fields.
 For version 2, the values are assumed to be zero, unless specified otherwise
 in the description of a field.

-         72 -  79:  incompatible_features
+         72 -  75:  zero
+                    This field must be 0; it occupies the same
+                    position as the first extension header in version
+                    2 files, and using all 0 contents minimizes the
+                    damage done by buggy v2 clients that fail to check
+                    the version field, since they will stop trying to
+                    look for other extension headers.
+
+         76 -  79:  incompatible_features
                     Bitmask of incompatible features. An implementation must
                     fail to open an image if an unknown bit is set.
+                    Note that this field is only 4 bytes, while the
+                    other feature fields are 8 bytes; but if more than
+                    31 incompatible features are ever defined, it is
+                    trivial to define the final bit of this field as
+                    an incompatible feature that says where to look
+                    for other incompatible feature bits.

                     Bit 0:      Dirty bit.  If this bit is set then refcounts
                                 may be inconsistent, make sure to scan L1/L2
@@ -85,7 +99,9 @@ in the description of a field.
                                 be written to (unless for regaining
                                 consistency).

-                    Bits 2-63:  Reserved (set to 0)
+                    Bits 2-31:  Reserved (set to 0).  Note that this
+                                field
+

          80 -  87:  compatible_features
                     Bitmask of compatible features. An implementation can
-- 
1.8.4.2