G3FC (G3 File Container) File Format Specification

Status of This Memo

This is the final technical specification for version 1.0¶

¶

¶

¶

Copyright Notice

Copyright (c) 2025 G3Pix - Lucas Guimaraes. All rights reserved.¶

https://g3pix.com.br/g3fc/
https://github.com/guimaraeslucas/g3fc/¶

Table of Contents

2. Overall File Structure

A G3FC archive consists of a main index file (with a .g3fc extension) and zero or more data block files (with .g3fc<n> extensions). A non-split archive contains all components within the single .g3fc file.¶

The logical structure of a non-split archive is as follows:¶

1. Main Header: A fixed-size block containing essential metadata about the container.¶
2. File Index: A catalog of all files and directories stored in the archive.¶
3. File Data Block: The actual content of the archived files, concatenated.¶
4. Data FEC Block (Optional): Parity data for the File Data Block section.¶
5. Metadata FEC Block: Parity data protecting the Main Header and the uncompressed File Index.¶
6. Footer: A fixed-size block at the end of the file for quick access to key structures.¶

In a split archive, the .g3fc file contains the Header, File Index, Metadata FEC Block, and Footer. The File Data is stored in separate data block files (e.g., archive.g3fc0, archive.g3fc1).¶

3. Main Header

The Main Header is a fixed-size block of 331 bytes located at the beginning of the .g3fc file. It MUST NOT be compressed or encrypted. The fields are aligned sequentially with 1-byte packing.¶

4. File Index

The File Index is a data block containing a catalog of all files and directories. The index SHALL be serialized using Concise Binary Object Representation (CBOR) [RFC8949]. The root object is a CBOR array, where each element is a CBOR map representing a file entry.¶

The entire serialized CBOR byte stream is then compressed using Zstandard [RFC8878] and MAY be encrypted.¶

5. Data Blocks

The File Data section contains the actual content of the files. Its structure depends on whether the archive is split.¶

Non-Split Archive:

All file data is concatenated into one large data block. This block is then subject to global compression and encryption as specified in the header. It is located between the File Index and the Data FEC Block.¶

Split Archive:

The file data is chunked and written to separate files named <archive_name>.g3fc0, .g3fc1, etc. Each of these data block files is independently compressed and encrypted according to the global settings. The File Index entry's `block_file_index`, `data_offset`, and `data_size` fields are used to locate a specific chunk of data.¶

6. Compression

The G3FC format uses Zstandard (Zstd) for compression [RFC8878].¶

Per-File Compression:

If the header's `global_compression` flag is 0, each file can be compressed individually before being added to the data block. The `compression` field in the file's index entry indicates if it was compressed.¶

Global Compression:

If `global_compression` is 1, the entire data block (either the concatenated data in a single archive or each split block file) is compressed as a whole with Zstd. In this mode, the per-file `compression` flag is ignored.¶

7. Data Integrity and Recovery

8. Security and Encryption

+------------------+--------------------------+------------------+
| Nonce (12 bytes) | Authentication Tag (16B) | Ciphertext (...) |
+------------------+--------------------------+------------------+

9. Footer

A fixed-size footer of 40 bytes is located at the very end of the .g3fc file. Its purpose is to allow an application to quickly find the File Index and Metadata FEC block without scanning the entire file. This is crucial for efficient operation, as it means the application can read the last 40 bytes, validate the footer's integrity, and then seek directly to the File Index location without needing to read or decompress the (potentially very large) file data block that precedes it.¶

10. File Operations

Deletion: To mark a file or directory as deleted, its `status` field in the File Index SHALL be changed to 2. The actual file data is not removed from the data blocks. This allows for "undelete" functionality. A separate "compact" or "purge" operation MAY be implemented by an application to physically remove data marked as deleted and reclaim space.¶

11. IANA Considerations

This document requests the registration of a new media type in the "application" tree, as follows:¶

Type name:

application¶

Subtype name:

vnd.g3pix.g3fc¶

Required parameters:

N/A¶

Optional parameters:

N/A¶

Encoding considerations:

binary¶

Security considerations:

See Section 12 of this document.¶

Interoperability considerations:

This document specifies format version 1.0. All fields use little-endian byte order.¶

Published specification:

This document.¶

Applications that use this media type:

G3FC Archiver Tool and other compatible archiving utilities.¶

Fragment identifier considerations:

N/A¶

Additional information:

Magic number(s):

The first 4 bytes are 0x47 0x33 0x46 0x43 (ASCII "G3FC").¶

File extension(s):

.g3fc, .g3fc<n>¶

Macintosh file type code(s):

N/A¶

Person & email address to contact for further information:

g3fc@g3pix.com.br¶

Intended usage:

COMMON¶

Restrictions on usage:

None¶

Author:

Lucas Guimaraes¶

Change controller:

G3Pix¶

12. Security Considerations

Implementers of this specification should be aware of the following security aspects:¶

• Password Strength: The security of an encrypted archive is entirely dependent on the strength of the user's password. Implementations SHOULD encourage or enforce strong password policies.¶
• KDF Iterations: The number of PBKDF2 iterations (`kdf_iterations`) is critical for resisting brute-force attacks. The recommended value of 100,000 is a baseline and SHOULD be increased over time as computing power grows.¶
• Salt: The use of a unique, randomly generated salt for each archive is crucial to prevent rainbow table attacks. The `read_salt` MUST be cryptographically random.¶
• Authenticated Encryption: The use of AES-256-GCM is REQUIRED as it provides authenticated encryption, protecting against certain types of attacks that can be performed on unauthenticated ciphers (e.g., bit-flipping attacks).¶
• Metadata Protection: While the file content is protected, some metadata in the Main Header is not encrypted. This includes timestamps and the name of the creating software. Users should be aware that this information is visible even in an encrypted archive.¶
• Path Traversal: Implementations that extract files MUST validate and sanitize the `path` field from the File Index to prevent path traversal attacks (e.g., writing files outside the intended destination directory). Paths containing ".." or absolute paths SHOULD be rejected or handled with extreme care.¶
• Compression: The media type employs Zstandard compression. As with any format that uses compression, G3FC files are susceptible to "compression bomb" denial-of-service attacks, where a small file decompresses to an extremely large size, potentially exhausting system memory or disk space. Implementations that parse this format SHOULD mitigate this risk by first checking the uncompressed_size field in the file's metadata index and enforcing reasonable limits on resource allocation before attempting decompression.¶
• Executable content: The media type does not contain any active or executable content. The G3FC format is a container for passive data files and metadata only.¶

Contributors

The G3FC format relies on several established technologies. The authors of the specifications for these technologies are acknowledged for their foundational work.¶

Author's Address