A collection of shell scripts to setup and manage LUKS2-encrypted drives, either interactively or via command line.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
This project provides command-line switches as well as a dialog-based interface to
- setup dm-crypt/LUKS2 encryption on hard disks and flash drives,
- mount and unmount LUKS2 devices,
- add and remove LUKS2 key slots (passphrases, FIDO2 devices, PKCS11 token, TPM2 chips),
- backup and restore LUKS2 header,
- clone drives.
The project has been developed and tested on the following system:
| Info | Description |
|---|---|
| OS | Debian GNU/Linux 12 (bookworm) |
| Kernel | 6.1.0-17-amd64 |
| Packages | coreutils (9.1-1) |
| cryptsetup (2:2.6.1-4~deb12u1) | |
| dash (0.5.12-2) | |
| dialog (1.3-20230209-1) | |
| libc-bin (2.36-9+deb12u1) | |
| libccid (1.5.2-1) | |
| libfido2-1 (1.12.0-2+b1) | |
| libtss2-esys-3.0.2-0 (3.2.1-3) | |
| libtss2-rc0 (3.2.1-3) | |
| opensc-pkcs11 (0.23.0-0.3+deb12u1) | |
| pcscd (1.9.9-2) | |
| pv (1.6.20-1) |
Please make sure that the following dependencies are installed:
Additionally, there are some use-case specific dependencies (see sections below):
Packages: Cryptsetup, PipeViewer
Debian: > sudo apt install cryptsetup pv
In case you run this script interactively your terminal window must have a size of <100x30> or bigger.
Packages: Dialog
Debian: > sudo apt install dialog
Please make sure that your OS is shipped with version '251.3-1' or higher. To check your current systemd version simply run
systemctl --version
Your token must support the "HMAC Secret Extension (hmac-secret)".
Additionally, the following packages must be installed:
Packages: libfido2.so.1
Debian: > sudo apt install libfido2-1
Your token must be initialized and contain a valid public/private key pair.
Additionally, the following packages must be installed:
Packages: OpenSC (PKCS#11 module), PCSClite, USB PC/SC CCID driver
Debian: > sudo apt install opensc-pkcs11 pcscd libccid
See also: https://github.com/shimunn/fido2luks/tree/master#theory-of-operation
Packages: TPM2 Software stack library - TSS and TCTI libraries
Debian: > sudo apt install libtss2-esys-3.0.2-0 libtss2-rc0
See also: https://manpages.debian.org/experimental/systemd/systemd-cryptenroll.1.en.html
Below you can find distribution-specific installation instructions.
sudo apt install cryptsetup pv # Required
sudo apt install dialog # Interactive Mode (optional)
sudo apt install libfido2-1 # FIDO2 (optional)
sudo apt install opensc-pkcs11 pcscd libccid # PKCS#11 (optional)
sudo apt install libtss2-esys-3.0.2-0 libtss2-rc0 # TPM2 (optional)- Clone the repo
git clone --recurse-submodules https://github.com/fkemser/LUKSwrapper.git
- Edit the repository configuration file. In case it is empty just keep it as it is, do not delete it.
nano ./LUKSwrapper/etc/luks.cfg.sh
To call the script interactively, run /src/luks.sh (without further arguments) from your terminal. To get help, run /src/luks.sh -h.
================================================================================
=============================== SYNOPSIS ===============================
================================================================================
There are multiple ways to run this script:
Interactive mode (without any args):
> ./luks.sh
Classic (script) mode:
> ./luks.sh [ OPTION ]... ACTION [<device>]
ACTION := { -h|--help | --benchmark | --clone <src dev> <dst dev> | --close <device> | --encrypt <device> | --enroll <device> | --header-backup <device> <file> | --header-info <device> | --header-restore <file> <device> | --is-luks-device <device> | --list-token <type> | --open <device> | --remove <device> | --replace <device> | --show-drives }
OPTION := { [--auth <type>] | [-c|--cipher <cipher>] | [--fido2-device <dev>] | [--filesystem <fs>] | [--hash <algorithm>] | [-i|--iter-time <t>] | [-s|--key-size <bits>] | [--mapper <name>] | [--mount <mountpoint>] | [--no-pin] | [--pkcs11-token-uri <uri>] | [--tpm2-device <dev>] | [--tpm2-pcrs <pcrs>] }
[<device>] : Block device to use, e.g. '/dev/sda'
--------------------------------------------------------------------------------
-------------------------------- ACTION --------------------------------
--------------------------------------------------------------------------------
-h|--help Show this help message
--submenu <menu> Run a certain submenu interactively and
exit
<menu> = { show-drives | benchmark |
encrypt | open | close | enroll | remove |
replace | header-backup | header-restore |
header-info | clone }
--benchmark Run a benchmark
--clone <src dev> <dst dev> Clone <src dev> to <dst dev>
--close <device> Close and unmount <device>
--encrypt <device> Encrypt <device>
--enroll <device> Enroll a passphrase or a security token
(FIDO2/PKCS#11/TPM2) to <device>'s LUKS
header. Use it with '--auth <type>' to set
the authentication method to use.
--header-backup <device> <file> Backup <device>'s LUKS header to <file> (4)
--header-info <device> Show information about <device>'s LUKS
header
--header-restore <file> <device> Restore <device>'s LUKS header from <file>
--is-luks-device <device> Check whether <device> is a LUKS device.
Return value: 0 = yes, 1 = no.
--list-token <type> List connected tokens of a certain type
fido2 : FIDO2 Security Token
pkcs11 : PKCS#11 Smartcards and
Security Token
tpm2 : Trusted Platform Module 2
(TPM2)
--open <device> Open <device> and mount it. Use it with
'--auth <type>' to set the authentication
method to use.
--remove <device> Either remove a passphrase from <device>'s
LUKS header or wipe an entire token slot
(3)
--replace <device> Only with '--auth <fido2|pkcs11|tpm2>'.
Replace an entire token slot by all
(currently connected) security token
--show-drives Show available drives
--------------------------------------------------------------------------------
-------------------------------- OPTION --------------------------------
--------------------------------------------------------------------------------
____________ ACTION := { --enroll | --open | --remove | --replace } ____________
--auth <type> Specify authentication method to use for accessing LUKS
encryption key
passphrase : Passphrase
recovery : Recovery Key
(automatically
generated). Only if
ACTION := { --enroll |
--remove | --replace }.
Mostly identical to
'passphrase', but this
option randomly
generates a passphrase
which can be optionally
scanned off screen via a
QR code.
fido2 : FIDO2 Security Token
pkcs11 : PKCS#11 Smartcards and
Security Token
tpm2 : Trusted Platform Module
2 (TPM2)
(default: 'passphrase')
_________________ ACTION := { --enroll | --open | --replace } __________________
--fido2-device <dev> Only with '--auth fido2'. Specify FIDO2 (hidraw)
device to use, possible values are:
auto : Automatically (exactly one (1)
token, no other token must be
connected)
... : Manually, by specifying its
devnode name (<dev> =
/dev/hidraw...). To list all
currently connected hidraw
devices, just run './luks.sh
--list-token fido2'.
(default: 'auto')
--pkcs11-token-uri <uri> Only with '--auth pkcs11'. Specify PKCS#11 URI of
the token object to use, possible values are:
auto : Automatically (exactly one (1)
token, no other token must be
connected)
... : Manually, by specifying the
URI (<uri> = pkcs11:...). To
list all currently discovered
PKCS#11 token, just run
'./luks.sh --list-token
pkcs11'.
(default: 'auto')
--tpm2-device <dev> Only with '--auth tpm2'. Specify TPM2 security
chip (device) to use, possible values are:
auto : Automatically (there must be
exactly one (1) chip existing)
... : Manually, by specifying its
devnode name (<dev> =
/dev/tpmrm...). To list all
currently discovered TPM2
chips, just run './luks.sh
--list-token tpm2'.
(default: 'auto')
______________________ ACTION := { --enroll | --replace } ______________________
--no-pin Only with '--auth <fido2|tpm2>'. Disable any PIN request
during unlock. Not recommended.
--tpm2-pcrs <pcrs> Only with '--auth tpm2'. Specify one or more TPM2 PCRs
(Platform Configuration Registers) to bind the requested
enrollment to. <pcrs> must be a '+' separated list of
PCR indexes in the range of 0...23. For more information
please have a look at 'man systemd-cryptenroll', section
'--tpm2-pcrs= [PCR...]'.
(default: '7')
_______________________ ACTION := { --encrypt | --open } _______________________
--filesystem <fs> Filesystem to use for mounting or formatting
(default '--encrypt <device>': ext4)
(default '--open <device>': auto)
--mapper <name> Map open LUKS device to '/dev/mapper/<name>'
(default: '<device>_crypt', e.g. 'sdz_crypt')
_____________________________ ACTION := --encrypt ______________________________
-c|--cipher <cipher> Specify cipher (1). Run 'cat /proc/crypto',
'cryptsetup benchmark' to get a list of available
ciphers.
(default: 'aes-xts-plain64')
--hash <algorithm> Specify the passphrase hash (1). Run 'cryptsetup
benchmark' to get a list of available algorithms.
(default: 'sha256')
-i|--iter-time <t> Specify number of milliseconds to spend with PBKDF2
passphrase processing
(default: '2000')
-s|--key-size <bits> Specify key size in bits (1) (2)
(default: '512')
_______________________________ ACTION := --open _______________________________
--mount <mountpoint> Specify mount point. Leave <mountpoint> empty ("") to
prevent mounting.
(default: '/mnt/mapper/(--mapper <name>)')
================================================================================
=============================== EXAMPLES ===============================
================================================================================
________________________________ Encrypt device ________________________________
./luks.sh --show-drives
./luks.sh --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 512 --filesystem ext4 --encrypt /dev/sdz
____________________________ Open and close device _____________________________
./luks.sh --show-drives
./luks.sh --mapper mymapper --filesystem auto --open /dev/sdz
./luks.sh --close /dev/sdz
______________________________ Enroll FIDO2 token ______________________________
./luks.sh --auth fido2 --fido2-device auto --enroll /dev/sdz
./luks.sh --auth fido2 --fido2-device auto --mapper mymapper --open /dev/sdz
./luks.sh --close /dev/sdz
__________________________ Backup and recover header ___________________________
./luks.sh --header-info /dev/sdz
./luks.sh --header-backup /dev/sdz /tmp/luks.header
./luks.sh --header-restore /tmp/luks.header /dev/sdz
================================================================================
================================ NOTES =================================
================================================================================
_____________________________________ (1) ______________________________________
Run 'cryptsetup --help' to show the defaults.
_____________________________________ (2) ______________________________________
Important if you use a cipher with XTS operation mode:
XTS splits the supplied key in half, e.g. for AES-256 with
XTS mode you need a key size of 512 bits.
_____________________________________ (3) ______________________________________
Use '--auth <type>' to define the authentication method that
should be removed from the LUKS header. If <type> is ...
'passphrase' : Only the passphrase entered during prompt
will be removed from LUKS header
'fido2'|'pkcs11' : ALL tokens of this type
'recovery'|'tpm2' will be removed from LUKS header
_____________________________________ (4) ______________________________________
IT IS HIGHLY RECOMMENDED TO STORE YOUR HEADER BACKUP ON A SEPARATE EXTERNAL
FLASH DRIVE. In case you delete passphrases/tokens from your header you must
also update your header backup files. Otherwise one could restore your old
header and use deprecated passphrases/tokens.See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the GNU General Public License v3.0 (or later). See LICENSE for more information.
⚠️ The license above does not apply to the files and folders within the library directory/lib. Please have a look at theLICENSEfile located in the root directory of each library to get more information.
Project Link: https://github.com/fkemser/LUKSwrapper