Skip to main content

Crate paks

Crate paks 

Source
Expand description

§PAKS file

The PAKS file format is a light-weight encrypted archive inspired by the Quake PAK format.

§Getting started

PAKS files can be inspected with the standard file IO with FileReader and FileEditor, or from memory with MemoryReader and MemoryEditor.

§Creating PAKS files

Using a MemoryEditor instance:

// Create a new memory editor and choose your encryption keys
let ref key = paks::Key::default();
let mut editor = paks::MemoryEditor::new();

// Add content to the PAKS file
let content = include_bytes!("../tests/data/example.txt");
editor.create_file(b"foo/example", content, key);

// Finish the PAKS file and write to disk
editor.write("myfile.paks", key).unwrap();

Using a FileEditor instance:

// Create a new file editor and choose your encryption keys
let ref key = paks::Key::default();
let mut editor = paks::FileEditor::create_new("myfile.paks", key).unwrap();

// Add content to the PAKS file
let content = include_bytes!("../tests/data/example.txt");
editor.create_file(b"foo/example", content, key);

// Finish writing the PAKS file
editor.finish(key).unwrap();

// If the editor is dropped without calling finish
// any changes since creating the editor are lost

Consider using the pakscmd command-line application for bundling your assets separately.

§Reading PAKS files

Using a FileReader instance:

// Construct the key and simply open the file.
let ref key = paks::Key::default();
let reader = paks::FileReader::open("tests/data/example.paks", key).unwrap();

// Lookup the file descriptor and read its data.
let data = reader.read(b"foo/example", key).unwrap();

// If the PAKS file was tampered with without knowing the key,
// reading the file will fail with an error.

Using a bundled archive with BundleReader and static_bundle!:

paks::static_bundle!(EXAMPLE_PAKS = "../tests/data/example.paks");
let key = paks::Key::default();
let reader = paks::BundleReader::open(&EXAMPLE_PAKS, key).unwrap();

// The bundled reader keeps the directory encrypted and only decrypts
// descriptors lazily while traversing paths.
let data = reader.read(b"foo/example", reader.key()).unwrap();

§File Format

The file begins with Header, which contains the cryptographic nonce and MAC required to decrypt the embedded InfoHeader. The smallest addressable unit in the format is a Block. The entire file can be interpreted as a contiguous array of these blocks.

Section objects use 32-bit address and length fields that refer to blocks rather than byte offsets. This design imposes a maximum file size of 64 GiB, while individual files are limited to 4 GiB each.

§Metadata and Directory

The InfoHeader includes a Section that points to the Directory.

The directory represents the file hierarchy using a lightweight TLV (Type-Length-Value) structure. It is expected to be located at the end of the PAKS file.

§Data Layout

File data is stored between the header and the directory, with no enforced ordering.

When files are removed, their data is not immediately reclaimed, leaving gaps in the file. These gaps can be eliminated through an explicit garbage collection process, which rewrites the PAKS file to compact unused space.

§Encryption and Authentication

Encryption (Speck128/128) and authentication (CBC-MAC) are mandatory and not configurable.

These operations are applied on a per-file basis, meaning the entire PAKS file does not need to be processed or verified upfront.

Macros§

static_bundle
Bundles a PAKS archive as static data in the read-only section of the executable.

Structs§

BundleReader
Bundle reader.
Descriptor
The file or directory descriptor.
Directory
Directory editor.
FileEditFile
File file editor.
FileEditor
File editor.
FileReader
File reader.
Header
The file header.
InfoHeader
The info header.
MemoryEditFile
Memory file editor.
MemoryEditor
Memory editor.
MemoryReader
Memory reader.
Name
The descriptor name buffer.
Section
Section object.
TreeArt
Art used to render the directory structure.

Functions§

parse_key
Parses a hexadecimal string into a Key.
read
Reads a PAKS file from a stream.

Type Aliases§

Block
Block primitive.
Key
Key type.