Right after the header (at
header_length, or 72 in version 2) comes a list of header extensions,
ending with an end marker. Everything up to the backing file name must fit in the first
cluster. All numbers are big-endian.
Extension frame
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 4 | uint32 | Type | What the extension is; see below. |
4 | 4 | uint32 | Length | Bytes of data, not counting padding. |
8 | length | bytes | Data | Padded with zeros to a multiple of 8. |
| Type | Extension |
|---|---|
0x00000000 | End of the extension area |
0xE2792ACA | Backing file format name: a string such as raw or qcow2, not zero-terminated |
0x6803F857 | Feature name table |
0x23852875 | Bitmaps |
0x0537BE77 | Full disk encryption header pointer |
0x44415441 | External data file name (the letters DATA): a string, not zero-terminated |
| any other | Unknown; a reader may ignore it |
Each known extension appears at most once.
Feature name table
A list of 48-byte entries naming the feature bits, so that a program can say which unknown feature stops it.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 1 | uint8 | Type | 0 incompatible, 1 compatible, 2 autoclear. |
1 | 1 | uint8 | Bit number | 0 to 63. |
2 | 46 | text | Name | Padded with zeros; not necessarily zero-terminated. |
Bitmaps extension
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 4 | uint32 | nb_bitmaps | Number of bitmaps, at least 1. |
4 | 4 | – | Reserved | 0. |
8 | 8 | uint64 | bitmap_directory_size | Bytes in the bitmap directory. |
16 | 8 | uint64 | bitmap_directory_offset | Where the bitmap directory is. |
Encryption
Only guest data is encrypted; the header and tables never are.
- AES (
crypt_method1): AES-256 in CBC mode, the IV being the guest sector number (“plain64”). Deprecated in QEMU and kept only so old images can be converted. - LUKS (
crypt_method2): the cipher and IV method come from a LUKS header stored in the image; the IV uses the sector’s position in the file. The full disk encryption extension says where that header is:
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 8 | uint64 | Offset | Where the LUKS header starts, on a cluster boundary. |
8 | 8 | uint64 | Length | Bytes written; the space is rounded up to whole clusters and the rest is zero. |
The LUKS area starts with the 592-byte LUKS partition header, then its key material. Its key material offsets count from the start of the LUKS area; its payload offset is not used, since QCOW2’s own tables say where the data is.