From 749178d30314893e1ae911475b83c293415a57b9 Mon Sep 17 00:00:00 2001 From: Max Wash Date: Sun, 3 Nov 2024 20:00:49 +0000 Subject: [PATCH] doc: document tags and tag types --- doc/format.txt | 169 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 138 insertions(+), 31 deletions(-) diff --git a/doc/format.txt b/doc/format.txt index 9fa6eca..df7f1d7 100755 --- a/doc/format.txt +++ b/doc/format.txt @@ -202,7 +202,7 @@ version: 1.0 provides other features to defend against malicious modifications. -3 Image Header +5 Image Header ══════════════ The Image Header can be found at the beginning of every EC3 image file. @@ -216,24 +216,24 @@ version: 1.0 the image. - 3.1 Image Header Layout + 5.1 Image Header Layout ─────────────────────── - Offset Description Type - ───────────────────────────────────────────── - 0x00 Signature uint32 - 0x04 Format Version uint16 - 0x06 Chunk Size uint16 - 0x08 Tag Table Offset uint64 - 0x10 Tag Count uint64 - 0x18 Application Magic uint64 + Offset Description Type + ──────────────────────────────────────── + 0x00 Signature uint32 + 0x04 Format Version uint16 + 0x06 Chunk Size uint16 + 0x08 Tag Table Offset uint64 + 0x10 Tag Count uint64 + 0x18 Application Magic uint64 - 3.1.1 Signature + 5.1.1 Signature The Signature is found at the very beginning of the image file. It, like all integer types, is stored in big-endian. It always has the value 0x45433358 (or 'EC3X' is ASCII). - 3.1.2 Format Version + 5.1.2 Format Version This specifies which version of the EC3 Image file format the rest of the file conforms to. Only the Signature and Format Version header items are guaranteed to be the same across all format versions. @@ -247,7 +247,7 @@ version: 1.0 the minor version of the format version. For example, version 3.2 would be encoded as 0x0302. - 3.1.3 Chunk Size + 5.1.3 Chunk Size This specifies the size of all data chunks stored within the image, before any transformation operations such as compression or encryption are applied. @@ -264,65 +264,172 @@ version: 1.0 0x05 524,288 512 0x06 1,048,576 1,024 - 3.1.4 Tag Table Offset + 5.1.4 Tag Table Offset This specifies the offset in bytes from the beginning of the image file to the beginning of the tag table. - 3.1.5 Tag Count + 5.1.5 Tag Count This specifies the number of entries in the tag table. - 3.1.6 Application Magic + 5.1.6 Application Magic This is an application-defined value. The creator of an EC3 image can set this to any arbitrary value. Any generic EC3 manipulation tools should preserve the value of this field and, if the tool supports creating EC3 images, allow the user to specify the value to store in this field. -4 Tags +6 Tags ══════ - 4.1 The Tag Table + Tags are the fundamental units of data storage in an EC3 image. Every image + contains one or more tags. A tag is essentially a contiguous range of data + within an image, with an associated type, identifier, and flags. Various + data processing layers can be applied to the contents of a tag, such as + encryption or compression. Every tag within an image can be referenced either + by its index within the tag table or by an optional 64-bit identifier. + + + 6.1 The Tag Table ───────────────── - 4.2 Tag Types + The Tag Table describes all of the tags in an image. Its location and size + can be found by parsing the Image Header. The Tag Table consists of a number + of entries, one for each tag in the image. + + Each entry in the Tag Table has the following layout: + + Offset Description Type + ──────────────────────────────────────── + 0x00 Tag Type uint32 + 0x04 Flags uint32 + 0x08 Checksum uint32 + 0x1C Reserved uint32 + 0x20 Identifier uint64 + 0x28 Offset uint64 + 0x30 Size uint64 + 0x38 Reserved uint64 + + 6.1.1 Tag Type + A 32-bit integer indicating the type of the tag. EC3 defines a range + of different tag types, which can be found in Section 4.2 + + 6.1.2 Flags + Flags describing certain attributes of a tag, such as whether the tag + is compressed, encrypted, or signed. The full set of flags can be found + in Section 6.3 + + 6.1.3 Checksum + A checksum of the tag data, calculated on the raw data as it appears + on-disk, after any data processing layers (compression, encryption, etc) + have been applied. This checksum should be checked before the tag data is + processed any further. The checksum is calculated using the algorithm + described in Section 4.3 + + 6.1.4 Identifier + An arbitrary 64-bit integer that can be used to identify a tag. Every tag + within an image must have a unique identifier. The only exception is the + identifier value 0x00, which any number of tags can use as their + identifier and is used to indicate that a tag has no identifier. + + 6.1.5 Offset and Size + The offset from the beginning of the image file to the beginning of the + tag data, and the length of the tag data. Both values are measured in + bytes. + + + 6.2 Tag Types + ───────────── + + The type of a tag determines the format of the data contained within it. + + 6.2.1 VOLU: Volume + Volume tags contain the filesystem tree and file/directory metadata for a + single volume within the container. + + 6.2.2 CTAB: Chunk Table + The Chunk Table contains the file data chunks for all volumes within the + container. + + 6.2.3 XATR: Extended Attributes Table + The Extended Attributes table contains any extended attributes referenced + by any file or directory stored in any of the volumes in the container. + + 6.2.4 STAB: String Table + The String Table contains all of the strings used as file/directory names + for all files and directores stored in the container. + + 6.2.5 MFST: Manifest + The manifest is a key-value data store that holds information describing + the container. Apart from a few required keys, any arbitrary keys and + values can be stored in the manifest. + + 6.2.6 BLOB: Binary Data + Binary blobs are contiguous buffers of arbitrary binary data. EC3 places + no requirements on the length or layout of this data, so these tags can + be used for any application-defined purpose. + + 6.2.7 EXEC: Executable + Executable tags are used to store embedded executable files. For certain + executable file formats, these tags can also include auxiliary information + about the executable file to allow readers to load and run the executable + without having to implement a parser for the executable file format. + + 6.2.8 CERT: Digital Certificate + If any part of the image is digitally signed, it will also contain one or + more Digital Certificate tags. These tags contain either: + + a) the certificate used to sign the container; or + b) (optionally) any intermediate certificates needed to link the + signing certificate back to a trusted root certificate. + + 6.2.9 CSIG: Digital Signature + If any part of the image is digitally signed, this tag contains the actual + signature data. + + + 6.3 Tag Flags ───────────── -5 Manifest + 6.4 Tag Identifiers + ─────────────────── + + +7 Manifest ══════════ -6 Volumes +8 Volumes ═════════ - 6.1 Filesystem Tree + 8.1 Filesystem Tree ─────────────────── - 6.2 Clusters + 8.2 Clusters ──────────── - 6.3 String Table + 8.3 String Table ──────────────── - 6.4 Extended Attributes + 8.4 Extended Attributes ─────────────────────── -7 Binary Blobs +9 Binary Blobs ══════════════ -8 Embedded Executables -══════════════════════ +10 Embedded Executables +═══════════════════════ -9 Signature Verification -════════════════════════ +11 Signature Verification +═════════════════════════ -10 Encryption +12 Encryption ═════════════