catarmor

A command-line file encryption tool with configurable symmetric ciphers, hash algorithms, and key derivation functions.

Getting Started

Requires Python 3.10+, Poetry

# Install dependencies
poetry install

# Activate the virtual env
eval $(poetry env activate)

Usage and Options

catarmor encrypt SOURCE DEST [ARGS]

Encrypt

Encrypt a single file

catarmor encrypt file.txt -o file.txt.catarmor

Encrypt multiple files

catarmor encrypt file1.txt file1.txt -o encrypted_dir/

Encrypt a directory

catarmor encrypt dir/ -o encrypted_dir/

Encrypt a directory with 8 parallel workers and 1 concurrent KDF derivations

catarmor encrypt dir/ -o encrypted_dir/ -j 8 --parallel-kdfs 1

Decrypt

Decrypt a single file

catarmor decrypt file.txt.catarmor -o file.txt

Decrypt a directory

catarmor decrypt encrypted_dir/ -o dir/

General Options:

--help (-h)  Display this message and exit.
--version    Display application version.

Encryption Options:

SOURCE --source -i           The file(s) or directory to encrypt. 
  --empty-source             a directory is specified, all files
                             within the directory will be encrypted
                             [required]
DEST --dest -o               The output file or directory. If a
                             directory is specified, the encrypted
                             files will retain the same directory
                             structure as the source. [required]
PASSWORD --password -p       The password used to derive encryption
                             and HMAC keys. If not specified, the
                             password will be prompted for.
                             [default: ""]
JOBS --jobs -j               The number of parallel processes to
                             use. If 0, the number of available CPU
                             cores will be used. [default: 4]
FORCE --force -f --no-force  Overwrite existing file(s). [default:
                             False]
CIPHER --cipher              The symmetric encryption algorithm for
                             encrypting the file contents. [choices
                             aes, camellia, cha-cha20, sm4]
                             [default: aes]
HMAC --hmac                  The cryptographic hash function for
                             message authentication (HMAC).
                             [choices: sha1, sha512-224, sha512-256
                             sha224, sha256, sha384, sha512,
                             sha3-224, sha3-256, sha3-384, sha3-512
                             shake128, shake256, md5, blake2b,
                             blake2s, sm3] [default: sha512]
KDF --kdf                    The key derivation function for
                             deriving the encryption and HMAC keys
                             from the input password. [choices:
                             argon2id, pbkdf2-hmac, scrypt]
                             [default: argon2id]
KEY-LENGTH --key-length      The length of the derived key in bytes
                             Use 0 to automatically select the best
                             key length. [default: 0]
SALT-LENGTH --salt-length    The length of the salt in bytes.
                             Recommended to be at least 16 bytes.
                             [default: 32]
PARALLEL-KDFS                [default: 1]
  --parallel-kdfs
ARGON2-ITERATIONS            Also known as passes, this is used to
  --argon2-iterations        tune the running time independently of
                             the memory size. [default: 1]
ARGON2-LANES --argon2-lanes  The number of lanes (parallel threads)
                             to use. Also known as parallelism.
                             [default: 4]
ARGON2-MEMORY                The amount of memory to use in
  --argon2-memory            kibibytes. 1 kibibyte (KiB) is 1024
                             bytes. This must be at minimum 8 *
                             lanes. [default: 2097152]
PBKDF2-ALGORITHM             The hash algorithm to use. [choices:
  --pbkdf2-algorithm         sha1, sha512-224, sha512-256, sha224,
                             sha256, sha384, sha512, sha3-224,
                             sha3-256, sha3-384, sha3-512, shake128
                             shake256, md5, blake2b, blake2s, sm3]
                             [default: sha3-512]
PBKDF2-ITERATIONS            The number of iterations to perform of
  --pbkdf2-iterations        the hash function. This can be used to
                             control the length of time the
                             operation takes. Higher numbers help
                             mitigate brute force attacks against
                             derived keys. [default: 1000000]
SCRYPT-N --scrypt-n          CPU/Memory cost parameter. It must be
                             larger than 1 and be a power of 2.
                             [default: 1048576]
SCRYPT-R --scrypt-r          Block size parameter. [default: 8]
SCRYPT-P --scrypt-p          Parallelization parameter. [default: 1
LOGFILE --logfile

Decryption Options:

SOURCE --source -i           The file(s) or directory to encrypt. If
  --empty-source             a directory is specified, all files
                             within the directory will be encrypted.
                             [required]
DEST --dest -o               The output file or directory. If a
                             directory is specified, the encrypted
                             files will retain the same directory
                             structure as the source. [required]
PASSWORD --password -p       The password used to derive encryption
                             and HMAC keys. If not specified, the
                             password will be prompted for.
                             [default: ""]
JOBS --jobs -j               The number of parallel processes to
                             use. If 0, the number of available CPU
                             cores will be used. [default: 4]
FORCE --force -f --no-force  Overwrite existing file(s). [default:
                             False]
PARALLEL-KDFS                [default: 1]
  --parallel-kdfs
LOGFILE --logfile

Development

Running tests

poetry run pytest

Run type checks

mypy .

Format files:

ruff format

File Spec

See docs/format.md for the file format specification.