Crate paks 

PAKS file

The PAKS file format is a light-weight encrypted archive inspired by the Quake PAKS 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
editor.create_file(b"foo/example", include_bytes!("../tests/data/example.txt"), key);

// Finish the PAKS file and write to disk
let (blocks, _) = editor.finish(key);
std::fs::write("myfile.paks", paks::as_bytes(&blocks)).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
editor.create_file(b"foo/example", include_bytes!("../tests/data/example.txt"), 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 PAKStool 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("myfile.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

File Format

The file format starts with a Header which contains the cryptographic nonce and mac to decrypt the InfoHeader contained in the header.

The smallest addressable unit of the file format is a Block, the entire file format can be read into an array of these Blocks.

Addresses and sizes as referenced by Section objects, their 32-bit address and length fields reference blocks, not byte offsets. This limits the file format to a maximum of 64 GiB, individual files are limited to a maximum 4 GiB each.

The InfoHeader contains a section object referencing the Directory.

The directory encodes a file hierarchy in a light-weight TLV structure. The file format expects the directory to come at the end of the PAKS file.

The individual files’ data are stored in between the header and the directory in no particular order. When files are removed their data isn’t immediately reclaimed leaving behind gaps. An explicit garbage collection can rewrite the PAKS file to reclaim this unused space.

The encryption Speck128/128 and authentication CBC-MAC are not optional or configurable. These operations are performed on a per-file basis, the whole PAKS file does not need to be checked beforehand.

Structs

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.

Functions

read

Reads a PAKS file from a stream.

Type Aliases

Block

Block primitive.

Key

Key type.