Security Architecture

This page describes the Fractum 1.4.0 documentation baseline, not an independent security audit. It is intentionally limited to behaviour visible in the source repository and its tests. Review the source and test recovery with non-sensitive data before relying on Fractum for material you cannot replace.

Encryption and authenticated metadata

Fractum encrypts the input file with a fresh 32-byte key and AES-256-GCM through PyCryptodome. The encrypted file stores these fields in order:

4 bytes Metadata length

Variable JSON metadata

16 bytes GCM nonce

16 bytes GCM tag

Variable Ciphertext

The JSON metadata is supplied as AES-GCM additional authenticated data. Changing the ciphertext, tag, nonce, or authenticated metadata causes decryption to fail. The decryptor also rejects incomplete headers, oversized metadata, missing nonce or tag values, incompatible versions, and empty ciphertext.

The key material comes from Python's os.urandom(). Fractum does not add a custom entropy-mixing layer.

The 32-byte AES key is split into two 16-byte halves, then each half is processed with PyCryptodome's Shamir implementation in GF(2^128). Fractum combines the two resulting share values into one share per index.

32-byte AES key

2 × 16-byte halves

Shamir GF(2^128) K-of-N split, per half

N combined shares

The threshold K must be at least 2.
The total number of shares N must be at least K and no greater than 255.
Reconstruction rejects fewer than K shares and duplicate share indices.
Under the security properties of the Shamir scheme, fewer than K valid shares do not reveal the shared AES key.

Fractum encrypts the file first and shares the encryption key. It does not split the plaintext file itself.

A share file contains a share index and a Base64-encoded share value. Depending on the selected metadata mode, it can also carry a threshold, label, version, share-set identifier, tool-integrity data (a SHA-256 hash of the installed package's __init__.py, plus a hash of any local dependency wheels), and Python version.

During file-based recovery, Fractum first groups shares by the share-set identifier recorded in the encrypted file's metadata, when present. If no identifier match is found, it instead tries each available label in turn, reconstructing a candidate key and accepting it only once that key successfully decrypts and authenticates the actual ciphertext — a cryptographic check, not a metadata comparison. If a share file carries a SHA-256 hash, Fractum verifies it against the share bytes before attempting reconstruction. Reconstruction itself rejects fewer than K shares and duplicate share indices. Recovery does not independently cross-check that every supplied share file declares the same version or threshold as its peers; that stricter check exists in the codebase but is only exercised when reusing an existing share set with encrypt --existing-shares, not during recovery. These checks help detect malformed or mixed inputs; they do not replace trusted distribution and custody procedures.

Offline and portable operation

The encryption and decryption paths operate locally and do not depend on a remote Fractum service. The generated ZIP archives can include the encrypted file, share file, source files, bootstrap scripts, Dockerfile, and local dependency wheels when those files are available at archive creation time.

For a Docker workflow, --network=none is an operator-selected Docker flag that prevents the container from using a network. It is not enforced automatically by the Fractum CLI. Installation scripts may need network access unless the packaged local dependencies are used.

Memory handling

Fractum makes best-effort attempts to reduce the lifetime of mutable sensitive buffers:

SecureMemory overwrites bytearray buffers with several patterns and then zeros them.
SecureContext attempts mlock for its mutable buffer and calls its cleanup path on exit.
Failures of mlock are deliberately non-fatal.

Python immutable objects, interpreter copies, operating-system behaviour, swap configuration, crash dumps, and hardware side channels mean this is not a guarantee of secret erasure or swap prevention. A host already compromised at the OS or hardware level can still observe key material while it exists in memory, regardless of this cleanup.

Limits and operator responsibility

Fractum is not a hardware security module, a key-management service, or a substitute for an independent security review. The repository does not claim formal verification, a formal side-channel assessment, creator authentication for shares, or forward secrecy.

The practical security of a share set still depends on the chosen threshold, trusted custodians, physical storage, recovery instructions, host integrity, and the release you run. Read the security best practices before deploying a real share set.

Known limitations

The encrypted-file metadata currently carries the application version rather than an independent file-format version. Before changing versions in a long-lived recovery plan, verify compatibility with a disposable file and retain the release material needed for recovery.
Encryption and decryption process the complete file in memory. Fractum is intended for critical files, not large streaming backups.
ZIP share archives are extracted when file-based recovery reads them. Do not feed archives from an untrusted source into a sensitive recovery machine without considering the storage and extraction risk.
--existing-shares deliberately reconstructs and reuses an existing AES key to encrypt another file. This is an advanced compatibility path, not the default way to create independent backups.