wash/ec3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: document tags and tag types

Browse Source
This commit is contained in:
max 🍓
2024-11-03 20:00:49 +00:00
parent adabec8b8f
commit 749178d303
1 changed files with 138 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
doc/format.txt
View File

@@ -202,7 +202,7 @@ version: 1.0
provides other features to defend against malicious modifications. 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. The Image Header can be found at the beginning of every EC3 image file.
@@ -216,24 +216,24 @@ version: 1.0
the image. the image.
3.1 Image Header Layout 5.1 Image Header Layout
─────────────────────── ───────────────────────
Offset Description Type Offset Description Type
───────────────────────────────────────────── ────────────────────────────────────────
0x00 Signature uint32 0x00 Signature uint32
0x04 Format Version uint16 0x04 Format Version uint16
0x06 Chunk Size uint16 0x06 Chunk Size uint16
0x08 Tag Table Offset uint64 0x08 Tag Table Offset uint64
0x10 Tag Count uint64 0x10 Tag Count uint64
0x18 Application Magic 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 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 all integer types, is stored in big-endian. It always has the value
0x45433358 (or 'EC3X' is ASCII). 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 This specifies which version of the EC3 Image file format
the rest of the file conforms to. Only the Signature and Format Version 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. 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 the minor version of the format version. For example, version 3.2 would
be encoded as 0x0302. 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 This specifies the size of all data chunks stored within the image, before
any transformation operations such as compression or encryption are any transformation operations such as compression or encryption are
applied. applied.
@@ -264,65 +264,172 @@ version: 1.0
0x05 524,288 512 0x05 524,288 512
0x06 1,048,576 1,024 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 This specifies the offset in bytes from the beginning of the image file
to the beginning of the tag table. 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. 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 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 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 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. 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
══════════
6 Volumes
═════════
6.1 Filesystem Tree
─────────────────── ───────────────────
6.2 Clusters 7 Manifest
══════════
8 Volumes
═════════
8.1 Filesystem Tree
───────────────────
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
═════════════ ═════════════