Windham

Windham is free and open-source software for disk encryption, an implementation of its own specification, based on the Linux dm-crypt module.

 

Supported features:

• Transparent & on-the-fly disk (or partition) encryption.
• Plausible deniability: through Decoy Partition (steganography) and completely signature-less & mathematically random header.
• Tamper resistance: The encryption header scheme is designed to prevent malicious tampering.
• Password management: supports registering multiple passwords, revoking them with (optional) authorization.
• Atomic metadata: metadata will entangle each minor change to the full modifiable region. It is impossible to compare the partition header thus extracting information about the previous modification, reducing the attack surface.

 

How To install?

You can Choose to:

• Download the repository and use the auto-install.sh script, which will install all dependencies automatically and build Windham using CMake. Most distros are supported.
• Compile by your own. See Compile Instructions below.

 

Basic usage:

1. Locate the device that you want to encrypt under /dev, you can do this by using your disk manager 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 disk manager or mkfs. e.g: using sudo mkfs.ext4 /dev/mapper/*name* to create an ext4 partition.
5. close and lock your device using windham close *name*.
6. (Optional, but 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's unique and impossible to regenerate when compromised!!

 

/etc/windhamtab support and Clevis integration.

Windham supports /etc/windhamtab file which describes encrypted windham devices. Windham will read /etc/windhamtab when using windham Open TAB. if /etc/windhamtab does not exist, windham Open TAB will create a new file. Refer to the commit under /etc/windhamtab for details.

To integrate windham with systemd, use option systemd (or --systemd under windham actions). Without this option, systemd will not prompt for password during early user-space, leaves you no way to enter your password during boot.

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.keyfile

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

cat keyfile.keyfile | sudo windham Open <device> --keystdin

Inside /etc/windhamtab, you can use CLEVIS= prefix to integrate with clevis.

 

Introduction to the Decoy Partition

Windham supports Decoy Partition: a feature that provides encrypted partitions with a high degree of plausible deniability.

What is Decoy Partition?

A Decoy Partition allows windham to hide the encrypted partition. In a case where someone may forces you to disclose your confidential data located on your disk, or when the randomness of the header itself doesn't constitute a strong rebuttal of its existence, Decoy Partition allows you to deny the existence of the encrypted partition.

Decoy Partition achieves a high degree of plausible deniability by hiding itself under an identifiable partition that occupies the same region (usually the last partition / trailing free area in the partition table). The size of the decoy partition is usually much smaller than the full space of the identifiable partition. Also, The identifiable partition on top of it, both its metadata, journal and data, must be linear, otherwise the decoy partition may be damaged due to overwritten by the identifiable partition.

How to enable Decoy Partition?

Use windham New *your device* --decoy to create a decoy partition along with the encrypted partition. To open a Decoy Partition, use argument --decoy (Except for Close); the program then recognizes the given device as a Decoy Partition. Use --decoy-size when New to designate a size for the decoy partition. The solver will calculate whether the given size is feasible (e.g. the decoy partition cannot spawn across partition boundary defined by the partition table).

It is strongly recommend to overwrite your device with random data before deploying decoy partition and identifiable partitions: sudo dd if=/dev/urandom of=/dev/<your device>, bs=16M. The confidentially of the decoy partition is build upon security through obscurity, skipping the random overwrite degrades a decoy partition, in terms of plausible deniability when facing an experienced attacker, to a normal windham partition. Well, this may be okay if you just want to hide your files from somebody else (like your family members... well, you shouldn't do this in a moral perspective, but I'm not gonna blame you for this).

Note for using Decoy Partition

Decoy partition should be created above the partition level: mostly on the disk itself, or the top level mapping scheme. You can create a decoy partition inside a encrypt partition, which is a very useful way to hide your data if, due to some reasion, cryptographically random header makes you look suspicious.

If your device contains a GPT partition table, things becomes a little different: GPT partition table utilizes the last few sectors to store its backup. Thus windham will avoid them by locating header for the decoy partition just before the backup. Windham will actively probe for the GPT layout and decide the location for decoy partition header, thus ensure that the GPT structure will never get corrupted. Location of the decoy partition header, thanks to the reason above, depends on the specific GPT structure created by your partition software.

If you remove or create the GPT partition after the creation of the decoy partition, windham may not locate the original decoy partition header, or, more likely, the modification caused by removing or creating the GPT partition overwrites it. well, the only thing you can do, then, is to gracefully say goodbye to your data.

There are no protection and no ways to ensure the modification to the identifiable partition will not overwrite the underlying encrypted partition. For filesystems, Exfat and FAT32 are recommended. These filesystems have (by default) linear sequences when writing. EXT4, by default, does not.

TRIM issues: most internal SSD devices supports TRIM, a.k.a logical block discard. TRIM command allows the device to flag region as invalid, and allows the hardware to reclaim them for internal swapping. When creating a decoy partition on a TRIM capable SSD device, the adversary will easily notice a giant blob of random data that are not labeled as discarded, thus penetrating all plausible deniability features. You should disable trim; or if you want yourself look less suspicious, use a USB flash drive (they usually lacks TRIM support) or a HDD disk. Some HDD disks are TRIM-capable, mostly shingled magnetic recording (SMR) disks, but the controller will return its data as it is when reading a discarded sector, and swapping occurs very infrequently on these devices.

 

Install instructions:

Auto-compile using auto-install.sh

Run auto-install.sh at the root directory of the source code:

git clone https://level-128-git.com/level-128/windham.git --depth=1
cd windham
sudo sh auto-install.sh

auto-install.sh will install all dependencies automatically and build Windham using CMake. Most distros are supported. This is the
preferred installation method with native architecture. If something failed, then:

Build manually

cmake make and gcc (with gas, usually bundled with GCC) are required to build Windham (windham uses kconfig so you can't use ninja).

Windham only runs on glibc.

Install additional required libraries:

Description	Debian-based	Fedora-based / SUSE	Arch-based
device mapper	libdevmapper-dev	device-mapper-devel	device-mapper
Kernel key retention service(**)	libkeyutils-dev	keyutils-libs-devel	keyutils
EXT filesystem development package(*)	libext2fs-dev	e2fsprogs-devel	e2fsprogs
Kernel Header	linux-headers-$(uname -r)	kernel-devel	linux-headers
GNU Gettext	libgettextpo-dev	gettext-runtime	gettext
ncurses	libncurses-dev	ncurses-devel	ncurses
libblkid library	libblkid-dev	libblkid-devel	util-linux

Additional user-space programs:

• (*)resize2fs: user-space ext2/ext3/ext4 file system resizer (under e2fsprogs).
• clevis: a pluggable framework for automated decryption / encryption.

(*): only if Submodule support -> dynamic conversion and in place encryption support. (Experimental) enabled.

(**): only if Submodule support -> Kernel key retention service support set to 1 or 2.

 

Build windham using cmake:

cmake CMakeLists.txt -B build
cd build
make
make install # Optional

 

To configure Windham, use make menuconfig under build directory.

 

Other Usage Examples:

See: How To Use?

 

Contribute:

🥰🥰 Contributions are highly welcome 🥰🥰!

Oh, make sure that you have acknowledged the code of conduct.

Any questions? email me: level-128@gmx.com

 

License and Legal issues

Copyright (C) 2023- W. Wang (level-128)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.

The early version of this program has granted "Additional permissions" applied from article (7) when using, propagating and conveying the unmodified covered work. The "Additional permissions" have been revoked and removed from version 0.231128.

U.S. Encryption Export Regulations

Windham is classified under ECCN 5D002 that provides or performs "non-standard cryptography" as defined in part 772 of the EAR, and is subject to Export Administration Regulation jurisdiction from the Bureau of Industry and Security. A notification to BIS and the ENC Encryption Request Coordinator via email of the internet location (e.g., URL or internet address) of the source code is required when the cryptographic functionality of the source code is updated or modified. This can be done by notifying level-128 (Email: level-128@gmx.com) when making contributions or forking the software.

I know this is not ideal...