What is PSZ?
PSZ, short for Project Secure Zip, is an archive format for distributing complete project directories as encrypted packages.
A PSZ project consists of an encrypted .psz archive and a matching .psz-data.lor file used by the unpacking implementation.
Project packaging
Package files and directories into one portable project archive.
Authenticated encryption
PSZ uses AES-256-GCM to protect the archived project data.
Python API
Create and open PSZ archives directly from Python applications.
Portable unpacking
A matching data file contains the information required by the unpacker.
Get started with PSZ.
The recommended way to use PSZ is through its Python package.
Installation
Install the latest version directly from GitHub:
pip install git+https://github.com/SlabyLol/psz.git
If you have cloned the repository, install it in editable mode:
git clone https://github.com/SlabyLol/psz.git cd psz pip install -e .
Usage
Creating an archive
The Python API can create a PSZ archive from a project directory:
from pathlib import Path
from psz import create_archive
create_archive(
Path("sample-project"),
Path("demo.psz")
)
Opening an archive
Open an existing PSZ archive and extract its contents into an output directory:
from pathlib import Path
from psz import open_archive
open_archive(
Path("demo.psz"),
Path("demo.psz-data.lor"),
Path("out")
)
Listing archive members
Archive members can be inspected through list_archive_members:
from pathlib import Path
from psz import list_archive_members
members = list_archive_members(
Path("demo.psz"),
Path("demo.psz-data.lor")
)
for member in members:
print(member)
PSZ1 format
PSZ version 1 uses a compact binary container. The archive starts with the PSZ magic value and stores encrypted TAR data.
| Offset | Size | Field |
|---|---|---|
| 0 | 4 bytes | PSZ1 magic |
| 4 | 1 byte | Format version |
| 5 | 12 bytes | AES-GCM nonce |
| 17 | Variable | Encrypted TAR + authentication tag |
Binary structure
+--------+---------+--------------+----------------------+ | PSZ1 | Version | Nonce (12B) | Encrypted TAR + Tag | | 4 B | 1 B | | | +--------+---------+--------------+----------------------+
The encrypted payload is authenticated using AES-GCM. Modifying the ciphertext or authentication data causes decryption to fail.
Project files
A typical PSZ project produces two related files.
.psz
The main PSZ archive. It contains the encrypted project data.
.psz-data.lor
The accompanying unpacker/data file associated with the PSZ archive.
Keep the matching data file together with the archive when the archive needs to be opened using the generated unpacking information.
Python API reference
create_archive()
Creates a PSZ archive from a project directory.
create_archive(
source: Path,
output: Path
)
open_archive()
Opens a PSZ archive using its matching data file and writes the resulting project to the output path.
open_archive(
archive: Path,
data_file: Path,
output: Path
)
list_archive_members()
Returns the members contained in the archive.
list_archive_members(
archive: Path,
data_file: Path
)
Complete example
from pathlib import Path
from psz import (
create_archive,
open_archive,
list_archive_members
)
source = Path("sample-project")
archive = Path("demo.psz")
data_file = Path("demo.psz-data.lor")
output = Path("out")
create_archive(
source,
archive
)
members = list_archive_members(
archive,
data_file
)
for member in members:
print(member)
open_archive(
archive,
data_file,
output
)
Security model
PSZ uses authenticated encryption rather than plain compression or obfuscation.
AES-256
The archive payload is encrypted using AES with a 256-bit key.
GCM authentication
AES-GCM provides authenticated encryption, allowing modified archives to be detected.
Nonce
Each archive uses a 12-byte AES-GCM nonce as part of its encrypted payload.
TAR payload
Project files are packaged into TAR data before encryption.
Encryption does not protect a key that is distributed alongside the archive. Treat the matching key/unpacker data as sensitive when confidentiality is required.
Source code
PSZ is open source. Find the implementation, issues and project information on GitHub.