pit

README

pit - encrypted containers
==========================

pit creates, opens and closes single-file containers backed by LUKS.
Code is small enough to read and has no scripting layer.

features
--------
- containers are plain files formatted as ext4 through dm-crypt/LUKS
- key files hold a random 256-bit master key wrapped with a password
- memory for secrets is page aligned, locked and wiped
- "panic" kills processes using pit mounts and detaches everything

usage
-----

    # create 100 MB container file and matching key
    pit dig vault.pit 100
    pit key vault.key

    # open and close (needs root for the dm/luks operations)
    pit open vault.pit vault.key
    pit close vault.pit

    # emergency close every mount and mapper entry
    pit panic

A key file is bound to the container that was first formatted with it.
Reuse only if you intentionally want identical LUKS keys.

security notes
--------------
- AES-XTS with a libsodium-derived key (Argon2) protects the container
- master key never touches disk outside the encrypted key file
- stdin echo is disabled while entering passwords
- program aborts if secure memory cannot be locked

security limits
---------------
- assumes your swap, firmware and boot chain are trusted
- does not prevent physical attacks or hardware keyloggers
- losing the key file or password means permanent data loss

requirements
------------

- libcryptsetup
- libsodium
- a privilege escalation helper (sudo or doas) for non-root use

build
-----

    make
    sudo make install