Skip to content
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


    __       __  __   __ __    _____    __  __   _____
   / /      / / / /  / //_/   / ___/   / / / /  / ___/
  / /      / / / /  / ,<      \__ \   / / / /   \__ \ 
 / /___   / /_/ /  / /| |    ___/ /  / /_/ /   ___/ / 
/_____/   \____/  /_/ |_|   /____/   \____/   /____/  


LUKSUS is a tool that creates an encrypted volume and filesystem on a hardrive or other storage
media as well as a filecontainer.
It can use the following encryption facilities: LUKS, Truecrypt and GELI. 
It works on Linux, DragonflyBSD and FreeBSD.


The purpose of this script is to provide to myself, an easy eay to encrypt
storage media in Linux, FreeBSD and DragonflyBSD, such as hardrives, usb sticks,
sd cards or external hardrives. It uses the LUKS and cryptsetup
crypto subsystem internal to the Linux Kernel. It can also use
Truecrypt encryption with the tcplay command, and FreeBSD's geli

This is thus a wrapper script for cryptsetup/tcplay/geli, shred and mkfs.
Instead of having to read up on the documentation for these
tools, I wrote this wrapper script to handle the dirtywork.
Being opinionated and pragmatic this program assumes that you (must)
have: dialog or whiptail, gnutools / coretools , and a supported
encryption engine installed.


(No command line options needed, anymore)

# FAQ:
Q: I really want to learn more about crypto in Linux. Where should I start?
A: This Kiwi guy wrote a series of excellent blog posts covering Linux
crypto software and usage of these. I highly recommend reading through them:
Thanks a lot Tom Ryder, for these very thorough and awesome posts.

Q: What are some alternatives to LUKSUS?
The QT-based zulucrypt is a graphical option - and a good one too!:

Q: Why should I use this script? 
A: I wrote this script because I wanted to have a way to easily and casually create encrypted volumes.
   Because doing all these tasks manually is 
   time consuming and can be a little tricky. I wanted to have a simple
   way of creating encrypted volumes instead of having to consult
   documentation each and every time I wanted to do it.
   Also, writing this has been a great learning experience.

Q: What is the license of LUKSUS?
A: LUKSUS is free libre open source software, released under the GPLv2
   license. Please let me know if the GPLv2 makes it hard for you to use it, and I
   will consider adding an extra license or changing it.

Q: Why should I encrypt?
A: It is beyond the scope of this README to go indepth. 
   Please google/duckduckgo for more info. Read some of Bruce Schneier's excellent articles and essays.
   imaginary scenario:
   You are working for a top notch startup. You have written a bunch
   of amazing code, and created some fantastic technical charts and your
   competitors are envious. Then one day, at a cafe, your laptop gets
   stolen. You loose all your files. You had a backup, sure, but the
   thief might sell your data. The solution is to encrypt the drive
   and protect your data.

   real scenario:
   Your data is at risk, and you want to protect it.
   Since it is your data, you deserve to decide who gets access.

Q: What have you based this on?
A: It is based on the guides provided in the LUKS FAQ, Truecrypt/Tcplay FAQ, and FreeBSD documentation:
   Cryptsetup / LUKS FAQ:
   Truecrypt documentation:
   FreeBSD disk encryption documentation:
   NetBSD disk encryption documentation:
   OpenBSD crypto documentation:
   OpenBSD 16 systems tips:
   NetBSD disk encryption guide:
   NetBSD disk encryption guide:
   NetBSD disk encryption description:
   NetBSD cgd author interview:

Q: How is the script designed?
A: The script reuses code wherever possible and is heavily built around reusable variables.
The script works like this:
   all existing data will be brutally removed beyond reconstruction (forensically)
   then it writes random data to the drive
   then creates a keyfile
   then encrypts the drive using the keyfile stored in /keys
   a LUKS header backup will also be placed in /keys
   please remember to take care of your /keys
   if you loose your /keys, the keyfile to your encrypted drive, then
   the data will be impossible to retrieve.

Q: Is there a Disclaimer? 
A: Yes:
    As with all security measures: Think them through, use with caution.
    There is no such thing as 100% guaranteed security. Also:
    I, the author, take no responsibility if a black hole appears,
    and implodes your house, your town and the entire planet earth as an
    effect of using this script.
    Understand that the author takes no responsibility, and cannot
    be held liable if you, the user, use the script to destroy the
    files/contents of your storage media.
    As a consequence it is the sole responsibility of the user
    to use this software correctly. The author cannot be held
    liable for any damages, as of this disclaimer.
    Furthermore you are responsible for the content you encrypt.

Q: I lost the key or the password, is there a way to restore the key
if I forgot it?
A: No. Really. No.

Q: What's in the secret sauce?
This is the gist of the encryption process is this command:

cryptsetup --batch-mode --verbose --key-size=512 --cipher=aes-xts-plain64 luksFormat $device $keyfile

Truecrypt (tcplay)
tcplay --create --device=$device --cipher=AES-256-XTS

Geli (FreeBSD)
geli init -s 4096 $device

Q: Why are we using the AES-256 cipher?
A: It is thoroughly vetted and impossible to crack unless Quantum
Computers become a reality.

A: Good question, some crypto wizards gave me this answer: -
(Passphrase-protected) Keyfiles are two-factor (something you have,
something you know) and passphrases are one-factor (something you
know). It should be obvious that (passphrase-protected) keyfiles are
at least as secure as passphrases because you need a passphrase to use
them. Considering you also need access to the appropriate filesystem,
they'd be more secure, if just by a little bit.
If you're talking about plaintext keyfiles, they're one-factor secure
(something you have). It's not so obvious whether a plaintext is more
or less secure than a passphrase. It would depend on the context, I
Keyfiles are possession factors (something you have). Possession
factors are threatened by theft and duplication. Since a keyfile is
just a file, it's relatively easy to duplicate it, so it's not a very
strong factor. In theory, a possession factor can be destroyed -- but
not if it's been duplicated or stolen!
Passphrases are knowledge factors (something you know). Knowledge
factors are threatened by guessing and discovery. A strong passphrase
that's not stored anywhere but your head is still weak against
compulsive discovery (the cyrpto wrench attack, legal compulsion, etc.).
Source: Reddit discussion

So let's take the case of David Miranda, for him it was very useful
not to have the keys:

Also the web is closing in even on longer passwords nowadays:

Q: What are the requirements of using LUKSUS:
A: an empty hardrive or storage media
   knowledge about which device the hardrive or storage
   (blkid or dmesg will provide this)
   On Linux:
   dialog or whiptail
   On *BSD:
   dialog or whiptail
   tcplay - If you want to encrypt using truecrypt, then install the
   tcplay package.

DragonFlyBSD does not ship with bash, dialog and GNU coreutils by default, so you have to install it
from the repositories. "pkg_radd bash dialog coreutils tcplay" 
FreeBSD: pkg_add -r bash dialog coreutils
NetBSD: pkg_add -v bash dialog coreutils

Q: On what platforms and distributions has LUKSUS been tested?
A: LUKSUS works on Linux, FreeBSD and DragonFlyBSD.
   Tested on the distros: Debian, Ubuntu, ArchLinux, DragonFlyBSD and
   FreeBSD. Very possibly all derivatives of FreeBSD also.

Q: What license is LUKSUS released under?
A: Luksus is released under GNU GPLv2 License
   located here:
Q: I have found a bug or have another issue, how can I report it?
A: Any issues can be reported to the Github issue tracker for
   this project, located here:
   I really want to hear from you, feedback, the ways you use it, 
   suggestions, tips and so on. 
   My email is: thomas.frivold./\a\/t/\

Q: What is the LUKSUS homepage?
A: LUKSUS is maintained in a Github repository.
   The latest version can always be downloaded
   from GITHUB page, see the TAGS to download latest release
   or just go to the shiny fancy page:

Q: I'm a developer. How do I add another encryption engine?
A: After having made the script more or less modular, this is the
steps necessary to add another engine to LUKSUS:

Add loopbackdevice to LOOPBACKTEST()
Write HOUSEKEEPING() function for the new OS if necessary
Create engine() enginekeyfile() and engineopen() functions
put these new engine* functions into the main LUKSUS bootstrap-file
TEST TEST TEST! It is easy to break things, so it is very important to
test a lot.

Release preparation stuff to do:
* Complete the extensive test procedure:
Test in virtualbox:
4 different Linux distributions, Debian, CentOS, Arch, Ubuntu.

Must pass both tests:
Create volume on a physical drive (Virtualbox is fine)
Create volume on a virtual file container (if supported by os)
Frag any typos and silly formulations.
Frag any error messages.

Release it into the wild:
Bump version number in LUKSUS.variables
Update README Changelog and TODO
Push a new tag to Github
Update jekyll homepage at
Post to Freshmeat
Consider posting elsewhere

###################TODO ##############################

Implement a use of the oschecker in the encryption engine choice:
if linux then display available encryption engines
if freebsd then present available encryption engines
if netbsd then present available encryption engines
if dragonflybsd then present available encryption engines

Make the encryption engine choice work
Make the passphrase or keyfile stuff work
Focus and improve the user experience

Project overall todo:
Get user feedback, feature requests
Dare to post it to "Show Hackernews" (
Dare to post it to newslists, DragonFlyBSD users list, NetBSD users
list, FreeBSD users list 

Engines todo:
Add NetBSD support, cgd [50% done!]
Add OpenBSD , bioctl support
Add PGP / OpenPGP container support (maybe, if feasible)
Add ecryptfs container support (maybe, if feasible)

FreeBSD todo: 
Test LUKSUS on FreeBSD derivatives
Implement headerbackup in the geli encryption routine
Fix keyfile handling with GELI - Skip passphrase, and use key
Test keyfile handling properly with GELI

# User interaction things
Attempt to improve overall code, eliminate and kill laughable hacks
Improve conditional statements, get rid of redundant echo "" lines
Add LUKSUS status to key.information
Improve LUKSUS output in Dialog window, remove keyfile information
if the user is not using a keyfile.
Improve the actual output, if not using keyfile, then don't show
the empty variables to the dialog screen... 

Add mount command and losetup/vnconfig to key.information for added usability

This would make the script graphical. Consider how to
ask the user about this. ** Must be tested thoroughly. **

Write a proper Jekyll Markdown Github page for the readme.

New features todo:
Add strongbox/keyvault option+Debate whether to call it strongbox or keyvault
(this might not be necessary since the user can simply use LUKSUS to
create a stronbox, this should rather become a part of the README
file. And it should become a suggestion)

Improve this script to make it working (NetBSD cgdconfig)
# The below lines almost make cgdconfig work... still have to work it out
#!/usr/pkg/bin/bash -x
#### The netbsd CGD drive encryption method is really arcane.

# create cgd partition
disklabel -i sd1

# scrub partition with random data
cgdconfig -s cgd0 /dev/sd1a aes-cbc 128 < /dev/urandom

# scrub partition with zero ... however it will be converted into random
# data using aes-cbc with a random key and cbc mode for XORing with previous
# sectors.
dd if=/dev/zero of=/dev/rcgd0a bs=32k

# destroying the random key
cgdconfig -u cgd0

# build the cgd config file
# skip the -V if you want data to be destroyed at first attempt of access with wrong key. For the truly paranoid.
cgdconfig -g -V disklabel -o /etc/cgd/sd1a aes-cbc 256

# specify the password
cgdconfig -V re-enter cgd0 /dev/sd1a

# create a disklabel (I don't really understand why we do this at this particular point in the process)
disklabel -I -i /dev/cgd0

# create filesystem
newfs /dev/rcgd0a

# configure cgdconfig - is this necessary???
echo "cgd0 /dev/sd1a" >> /etc/cgd/cgd.conf

some pragmatic snippets of code, that probably will
be implemented:
device=$(dialog --inputbox "Enter the device to create volume on. E.g. /dev/sdd1 or /dev/loop0" 10 30 3>&1 1>&2 2>&3)
name=$(dialog --inputbox "Enter the volume name (nickname of the volume). E.g. Mystuff. Note no special characters or spaces" 10 30 3>&1 1>&2 2>&3)
luksfile=$(dialog --inputbox "Full path of encrypted volume" 10 30 3>&1 1>&2 2>&3)
luksfilesize=$(dialog --inputbox "What is the desired size of the container. E.g. 100M or 25G" 10 30 3>&1 1>&2 2>&3)
echo $device
echo $name
echo $luksfile
echo $luksfilesize

some code for improvement of the menu system

#!/usr/bin/env bash
t(){ type "$1"&>/dev/null;}
function Menu.Show {
   local DIA DIA_ESC; while :; do
      t whiptail && DIA=whiptail && break
      t dialog && DIA=dialog && DIA_ESC=-- && break
      exec date +s"No dialog program found"
   done; declare -A o="$1"; shift
   $DIA --backtitle "${o[backtitle]}" --title "${o[title]}" \
      --menu "${o[text]}" 0 0 0 $DIA_ESC "$@"; }

Menu.Show '([backtitle]="Backtitle"
            [question]="Please choose encryption ENGINE:")'          \
            "LUKS"  "LINUX NATIVE"                \
            "TRUECRYPT"  "TRUECRYPT (TCPLAY)"                \
            "GELI"  "FREEBSD NATIVE"                \
            "CGD"  "NETBSD NATIVE"    


whiptail implementation
foobar=$(whiptail --inputbox "Enter some text" 10 30 3>&1 1>&2 2>&3)

whiptail tutorial

whiptail --menu "Choose encryption engine" 10 40 4 \
               LUKS "" off  \
               TRUECRYPT "Popular Ubuntu"   on   \
               GELI "Hackish Fedora"   off  \
               CGD "Stable Centos"    off  \
               PGP "Rising Star Mint"   off  2>ENCRYPTION


###################CHANGELOG #########################

+Extensive testing was done on all platforms
+NetBSD is now properly supported

V1.2.9 14:50 23.10.2013
Great strides has been taken to improve the code.
Added a debug mode, can be enabled in the VARIABLES section. Devs only.

v1.2.8 19:25 17.10.2013
+Very nice looking menu created
Got some ideas from here: a complete menusystem I borrowed some ideas from:

+Preliminary menu system works
It is not pretty enough yet, but the idea is that from now on, the
user will not have to use commandline options. Dialog og whiptail is
+Added whiptail support, which will not require dialog on Debian based
systems. Thanks Stackexchange!
+Command line arguments are now optional, a dialog/whiptail will ask the
user for options.

Preliminary menu system is almost a reality

+Attempts were made to add crude NetBSD support

Create a label to newly created filesystem, based on $name (Linux only)
Better usability of the information file of each volume.
Improvements to output 

Fixed a tiny mistake.

Fixes some regressions

Adds FreeBSD support

LUKSUS is stable and mature enough to be called 1.0
Tested on Linux and DragonFlyBSD

v1.0RC9 03.08.2013
The testing phase of LUKSUS has really forced a lot of 
improvements all over. The code is now completely modular, and
adding further encryption engines and operating systems should
be a walk in the park.
Now executes flawlessly in all operating modes on Linux and DragonFlyBSD

v1.0RC8 02.08.2013
+ added nodialog option and FreeBSD support
+ Dialog use is not enforced anymore. If package is not installed,
+  then the script will skip fancy dialog use. Dialog is not shipped
+  with all distros by default. Less headache for the user.

v1.0RC7 30.07.2013

v1.0RC5 29.07.2013 12:30

+LUKSUS now defaults to passphrase. Using a keyfile is 
optional. User feedback suggested that many users preferred
to use passphrase instead of keys. Therefore the default
has been set to passphrase, with using keyfiles being optional.
+The dawn of modularization of the encryption engine code.
I am hoping to be able to add support for FreeBSDs GBDE and GELI,
NetBSD's CGD and OpenBSDs BIOCTL. This would bump the number of
supported platforms to 5.

v1.0RC4 22.07.2013 15:09
+Removed some extra integrity checks. They were redundant and broke
Truecrypt support
Feature freeze, and all that is required now is more testing.
Fixed some regressions. Testing is a good idea.

v1.0RC3 22.07.2013 12:00
+Better dialog - yesno now works
I like where this is going

v1.0RC2 18.07.2013 19:00

+Improved logging and reporting further
+Cleaner OS Detection

Truecrypt command line option added
Usage cleanup
Readme testing

v0.95 06.03.2013 15:13
+Truecrypt support

v0.8.91 05.03.2013 20:00
Small bugfixes

v0.8.9 05.03.2013 13:28
+DragonFlyBSD support is now fully supported.
Cryptsetup / dm-luks spends a lot of time with its operation, 
10-15 minutes, but apart from that, LUKSUS runs on DragonFlyBSD.
Functions need more attention and cleanup, but everything is working
quite well now.

v0.8.5 26.02.2013 12:00
Cleanup before public release on!
Hello World

v0.8.4 26.02.2013 10:00
Added a routine to check the screensize, and display
a logo according to which screensize the user has.
Cleaned up a little bit here and there

v0.8.3 25.02.2013 20:00

v0.8.2 25.02.2013 15:00
Added a welcome sequence
Added a logo! (yay)

v0.8.1 25.02.2013 14:30
Added missing apostrophe

v0.8 24.02.2013 10:15
+ Improved code quality, implemented simple modularization.

v0.7 02.01.2013 13:20
+ Added support for loopback devices 
  creating an encrypted container is now possible with LUKSUS
+ Began work on implementing functions throughout
+ Added some conditional checks with regex

v0.6 02.01.2013 01:35
+ improved documentation (README file)
+ Added some nice sanity checks
+ Further cleaned up the code
+ Added a definite CTRL+C to cancel now
+ Added dependency checks

v0.5 25.04.2012 12:30
+ initial public release
  live on github here:
+ massive cleanup
+ added a conditional check to verify that user is root
+ added a conditional check in the middle of the procedure to
  verify that a LUKS container has been created on the device
  good for integrity 
+ added a routine to hackup the luks header with a conditional
  check as suggested by the luks FAQ
+ fixed mounting procedure
  changed name of the script from cryptcreate to luksus
  the luksus name is more a pun than a functional name
  luksus means luxury in Norwegian and coincidentally it includes the main technology
  used to encrypt hardrives in Linux since the 2.6 kernels - Linux Unified Key Setup
  on a celebratory note, the script can now be considered stable. Even though
  it lacks some niceties such as a fully fledged ncurses dialog menu system
  which is aimed at version v1.0
  - Thomas Frivold 

+ cleaned up script
+ added required runtime arguments

+ added command line input

+ cosmetic fixes
+ did some nice thinking about dialog

v0.1 16.04.2012 GMT+1 1320
+ initial release

### Notes ###

There are a few things to note about running this on DragonflyBSD...
EXT4 support is currently not available in a workable state in DFlyBSD;
The mkfs.ext4 tool shipped in e2fsprogs does not like the Dfly
loopback device, and I have not yet managed to get it to work.
Therefore the user will get a UFS filesystem instead.


Truecrypt defaults to using passphrase for volume security.
A keyfile can be added by using the commandline argument: usekey
This will add a key to the keychain in the volume, but TrueCrypt will
also ask for a password. 

Applies to both on Linux and DragonflyBSD
Truecrypt / tcplay is slow when it is creating encrypted
filecontainers on Linux. Once the volume has been created
speeds are nominal. This has at least been the case in my 
testing on Virtualbox instances of various Linux distributions.

Really slow loopback device encryption in DragonFlyBSD:
For some reason the cryptsetup tool in Dfly takes a very long time
to do its work when it is manipulating loopback LUKS volumes, ie.
file containers... I do not know the reason to this strange behaviour, 
but once it has created the volume, file transfer speeds are nominal and fast.
In my experience it takes 15 minutes to finish the process of creating
an encrypted filecontainer. Just have patience when creating encrypted filecontainers with 
loopback devices:)


Legacy documentation for those who really wish to use command line
options (not necessary anymore):

The usage of LUKSUS can take two different forms, 
mainly whether you are using LUKSUS on a physical device or a
virtual file. These two requires somewhat different commandline
arguments. Volumename simply means nickname for the encrypted
drive/media. Optional parameters are: 
truecrypt - which enables truecrypt instead of using LUKS (Linux and
DragonFlyBSD only)
usekey - which uses a keyfile instead of a passphrase, which will be
placed in /keys (LUKS only, works on truecrypt as well, but it will
ask for a passphrase anyhow so this will add a keyfile to the volume)

./LUKSUS /dev/sdb1 rambo1
./LUKSUS /dev/sdb1 rambo1 usekey

./LUKSUS /dev/loop0 ENCRYPTEDVOLUME /encryptedvolume.encrypted 300M 
./LUKSUS /dev/vn0 ENCRYPTEDVOLUME /encryptedvolume.encrypted 300M
./LUKSUS /dev/md0 ENCRYPTEDVOLUME /encryptedvolume.encrypted 300M

To enable the use of TrueCrypt instead of LUKS append the option: truecrypt
./LUKSUS /dev/sdc1 library truecrypt
./LUKSUS /dev/loop0 ENCRYPTEDVOLUME /encryptedvolume.encrypted 300M truecrypt

This last example is a corner case. This would create an encrypted
filecontainer using truecrypt with a passphrase as well as with a keyfile.
That keyfile would then work as a backdoor or an extra way into the archive, in case the password gets lost.
./LUKSUS /dev/loop0 ENCRYPTEDVOLUME /encryptedvolume.encrypted 300M truecrypt usekey

As of version 1.0, LUKSUS defaults to passphrase
for securing the volume. Using a keyfile is optional
and can be activated by using the commandline option: usekey
as mentioned earlier.

optional commandline arguments are: usekey nodialog
usekey - will enable the use of a keyfile instead of a passphrase
nodialog - will disable dialog prompts. Some people wants this.

It is possible to create an encrypted file container
The usage then changes a little as the script then needs to
know which loopbackdevice you wish to use, where the encrypted
filecontainer should be located, and how large it should be.
Please note that the size must have M for megabytes or G for
gigabyte appended to the size.

The following will use loop0, and place the encrypted container in
/usr and will have 1000MiB as space.

./LUKSUS /dev/loop0 mysecretlibrary /usr/thelibrary.encrypted 1000M

For creating an encrypted filecontainer on DragonFlyBSD
./LUKSUS /dev/vn0 mysecretlibrary /usr/thelibrary.encrypted 1000M

Something went wrong with that request. Please try again.