Windham

Windham is a libre software for disk encryption, an implementation of its own specification, based on the Linux kernel's dm-crypt module.

Readme Translation: Simplified Chinese, French

 

NOTE: Windham is currently under active development. Future versions, although unlikely, may introduce an incompatible on-disk format; use at your on risk!!!!.

 

Supported features:

• Transparent and on-the-fly disk (or partition) encryption.
• Plausible deniability: completely signature-less & cryptographically random on-disk format. In another word, no one can 100% prove that a partition is encrypted using windham instead of garbage random data. Optionally supports Decoy Partition (stenography) -- hiding itself under a plaintext filesystem.
• Passphrases management: supports registering multiple passphrases, passfile and/or key (up to 16 in total)
• Fast: thanks to its cryptographically random on-disk format, the unlock time does not depend on the number of passphrase registered; it is always as fast as only if one passphrase has been registered.
• Tamper resistance: on-disk format is designed to prevent malicious tampering.
• Self-correlated metadata: Windham will entangle each change to multiple indirect regions to vastly reduce the usefulness of extracting information by comparing the on-disk format before and after each modification.

Windham combines the flexibility, functionality and security of cryptsetup plus LUKS/LUKS2; it also provides plausible deniability and hidden volume (under VeraCrypt's term) feature similar with VeraCrypt. it's ability to unlock using constant time when arbitrary number of passphrases has been registered surpasses all current storage encryption schemes.

 

How To install?

Windham requires a Linux kernel based UNIX-like system; most of the testing are performed under GNU/Linux. For these operating systems, such Dependencies are required.

These commands will compile Windham under ./windham/dev. Git, CMake 3.16+, and a ISO C11 compiler are required. such commands run on most modern shells across different operating systems.

git clone https://github.com/level-128/windham.git --depth=1
cd windham
cmake -B build
cd build
cmake --build .

Under GNU-like systems, the command above will default to Release build type, which builds a complete functional Windham under such platforms. You need to install dependencies before building Release . For other platforms, only ISO C build type -- provides a set of basic on-disk format management operations -- is available and enable by default. Refer: Supported platforms,

 

Quick usage guide:

1. Locate the device that you want to create a encrypted partition under /dev, you can do this by using your GUI disk manager (e.g. GNOME Disks, Gparted... ) or command lsblk. It might be something like /dev/sdb or /dev/nvme0n1; /dev/sdb2 or /dev/nvme0n2p2 if you prefer to create an encrypted partition instead.
2. use windham New *your device* to create a new Windham device. e.g: creating a Windham device on /dev/sdb, use sudo windham New /dev/sdb.
3. To open and map your device, use windham Open *your device*. e.g: sudo windham Open /dev/sdb --to=enc1 will open /dev/sdb: at /dev/mapper/enc1.
4. create the filesystem as if it is an empty disk. You can use your GUI disk manager or mkfs. e.g: using sudo mkfs.ext4 /dev/mapper/*name* to create an ext4 partition.
5. After use, close and lock your device using windham close *name*.
6. (Optional, highly recommended) run windham Open *your device* --dry-run to view your master key; back it up into a safe place. The master key can access, control and modify the entire partition. It is unique and impossible to regenerate when compromised!!

 

• Action Suspend can suspend encryption -- recording the intermediate key to the header in plain text, granting everyone to access the encrypted partition. It is temper resistant as well. Passphrase and master key cannot be derived from it. Use Resume to undo suspend. NOTE: Action Suspend for cryptsetup and windham has different meaning: in cryptsetup, it means to hang all IOs to and from the block device.
• Use AddKey and DelKey to add or remove key. Depending on your threat model, you might want to use --rapid-add if you don't think your adversary could access the device both before and after --rapid-add. If the adversary could, they will gain formidable advantage if they decide to brute-force the passphrase. Usually an encryption solution for cold storage does not need to defend for such adversary model. AddKey without --rapid-add option (which is also the default) does not have this venerability, but it is very slow when you already have multiple passphrases registered.

 

Supported platforms:

Windham has 2 feature support levels:

1. Full support with Linux kernel 2.6+ (5.14+ kernel with kernel key retention service enabled is recommended). No additional libc requirements.
2. Basic mode with strict ISO C11 support. The following requirements must be satisfied for the target system:

• 8-bit byte with 2's complement signed integer representation; a byte order that is either Big or Little-endian.
• The basic character set (defined as the representable characters in a single 8-bit byte) of the system must meet the following requirements: it must include all the characters in the "C" locale of ISO C; a-z, A-Z, and 0-9 should be encoded consecutively in the character set. (ASCII falls into this category)
• The system must contain a hosted environment, or freestanding environment with stdlib.h string.h and stdio.h fully implemented in the C library.
• The system must have at least 492,000 bytes of free memory in heap (or could be dynamic allocated). 464,000 bytes of 492,000 bytes must be continuous in the address space where Windham executes. Execution environment must provide at least 25,968 + sizeof(FILENAME_MAX) * 2 bytes of stack size when the control flow reaches the main function for 64-bit platform. 32/16-bit platform has slightly lower stack size requirements.
• (Optional): ISO C threads implementation.

Windham in ISO C mode cannot mount and operate (encrypt/decrypt) a partition; is not designed to run under pid1, cannot parse /etc/windhamtab, cannot search disks/devices uses UUID or device path. The ability to access partition/disks solely depends on the platform's libc implementation: If your platform requires platform-dependent interface to read partition/disks instead of general file I/O, you are out of luck. Some minor features might also be missing. However, unlock and extracting master key, managing passphrases, suspending support are all present under basic mode.

Nearly all modern consumer devices satisfy these requirements for the basic mode. Most 32-bit MCU or SoC with decent development framework or community support also works. Virtual environments (e.g. WebAssembly) with compatible libc might work out-of-box (or with minor modifications to overcome file permissions). However, without an operating environment or a standardized baremetal framework (e.g. FreeRTOS Plus FAT & POSIX) that could handle file IO or providing an unlock backend (e.g. Commandline TCG Opal framework), running windham is technically possible but basically useless.

For instructions about how to embed unlock backend for ISO C mode, see source file libplat/ISOC/mapper.c.

 

Additional guides:

/etc/windhamtab support and cryptography module integration

Windham supports /etc/windhamtab file under full support which describes encrypted windham devices. This file is similar with systemd's /etc/crypttab, and Windham will read /etc/windhamtab when using windham Open TAB. Refer to the commit under /etc/windhamtab for details. To create and configure windhamtab file, following these steps:

• First, run windham Open TAB to create a template windhamtab file (if it does not exist).
• Append your encrypted devices and target paths (under /dev/mapper, same as argument --to in Windham Open) according to the format commited in the file, along with parameters and decryption methods. windhamtab supports unlock by asking for key / keyfile / Clevis. It is strongly encouraged to use UUID=, since it is a robust way to name devices that works even if disks are added and removed
• To unlock using Clevis, specify your Clevis file using CLEVIS= in the key field. For users who use systemd as init (true under most distros), stdin are handled by the daemon itself; use systemd-dialog option to integrate with systemd and plymouth (if you are using a graphical boot screen), allowing systemd or plymouth to prompt for password, or you will be stuck forever!
• To resolve dependency between devices, assign lower <pass> value for devices that need to be open first. option --windhamtab-pass allows Windham to execute actions only with the same pass number.
• Running command windham Open TAB with windhamtab file present will then start parsing /etc/windhamtab.

Most modern consumer devices supports builtin TPM (trusted platform module) or other external hardware security modules (e.g. FIDO device). To utilize these devices, you need an Automated Encryption Framework, such as clevis. To register a random key designated for clevis encryption using TPM2:

sudo windham AddKey <device> --generate-random-key | sudo clevis encrypt tpm2 '{}' > keyfile.key

your clevis key will be created as keyfile.keyfile. to unlock with it:

cat keyfile.key | sudo clevis decrypt tpm2 '{}' | sudo windham Open <device> --keystdin

Inside /etc/windhamtab, you can