Encrypt a file

The encrypt command creates a fresh AES-256-GCM encrypted file and a new K-of-N share set for its encryption key. Begin with a non-sensitive file. The important proof comes later, when you successfully recover it using K shares.

test-file.txt

FRACTUM encrypt --threshold 3 --shares 5

test-file.txt.enc

share_1.zip … share_5.zip

Each share_N.zip (one per share, N = 1…5) bundles:

that share's value
Fractum's full source code (the src/ tree)
README.md, LICENSE, requirements.txt, setup.py, .dockerignore, Dockerfile, and the bootstrap-linux.sh/macos.sh/windows.ps1 scripts, when present in the working directory
any setup/ files and packages/*.whl present, for a fully offline reinstall

By default the .enc file is not duplicated into the archives — it stays next to the tool. Pass --bundle-encrypted (-b) to also copy test-file.txt.enc into every share_N.zip, making each archive self-contained.

1. Choose K and N

N is the number of share archives created. K is the minimum number needed to reconstruct the encryption key. Fractum requires K >= 2, N >= K, and N <= 255.

Example	What it means	When it can help
2 of 3	Any two shares recover the file; one share can be lost.	A small personal recovery plan.
3 of 5	Any three shares recover the file; two can be lost.	A starting point for several independent custodians.
Higher K	More shares must meet for recovery.	Only when that still leaves a realistic recovery path.

Pick a threshold based on the people, places, and failure scenarios you can actually support. A high threshold is not useful if it makes recovery impossible after an ordinary absence or loss.

2. Run the command

From a manual installation

fractum encrypt ./test-file.txt \
  --threshold 3 \
  --shares 5 \
  --label "recovery-test" \
  --verbose

From the Docker workflow

docker run --rm -it \
  --network=none \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/shares:/app/shares" \
  fractum-secure encrypt /data/test-file.txt \
  --threshold 3 \
  --shares 5 \
  --label "recovery-test" \
  --verbose

Fractum replaces spaces in a label with underscores. --verbose prints the generated set identifier and archive paths, which makes the rehearsal easier to inspect.

If you would rather answer prompts than compose a command, start fractum --interactive and choose Encrypt a file. The interactive flow asks for the same threshold, number of shares, label, verbose mode, and metadata choice.

3. Inspect the result

For test-file.txt, the CLI writes:

test-file.txt.enc
shares/
  share_1.zip
  share_2.zip
  share_3.zip
  share_4.zip
  share_5.zip

The .enc file is the encrypted payload. Each ZIP archive is a recovery package containing one share file, plus source and setup material that was available when the archive was created; it also includes a copy of the encrypted file when --bundle-encrypted was passed. Treat both the archives and extracted share values as sensitive recovery material.

By default, a share file carries its index, share value, threshold, and an integrity hash. --full-metadata adds label, total share count, share-set ID, tool-integrity data, and Python version. That extra context can help an operator later, but it also reveals more about the share set.

4. Distribute the shares and test recovery

Move the share archives to independent custodians or locations according to your plan.
Keep a clear record of the threshold and recovery instructions without placing every share in the same record.
Recover the disposable file using any K archives before encrypting important data.
Rehearse again whenever custodians, storage locations, or tools change.

For the exact recovery command, continue to decrypting files. For the custody decisions around the command, read security best practices.

--existing-shares PATH reads compatible share files from PATH, reconstructs the existing AES key, and encrypts another file with that key. It does not create a new share set. This is an advanced compatibility mode; use it only when reusing the same recovery key is an intentional operational decision.