LUKS Encrypt Your Root File System on Raspberry Pi


@koltaig, our apt-repo has been updated and tested against Stretch. Please try it out against Stretch again. Please make sure that you do sudo apt-get update before upgrading the packages.


Thank you for the fast response!
It’s the same. Cannot boot.
But now it wrote an interesting line:

Begin: Running /scripts/local-block … cryptsetup (cryptrfs): cryptsetup failed, bad password or options?

And the blue LED is blinking continuously.


I’m looking into it.


@koltaig I have made some fixes in our software that I think will fix your issues. My testing shows that the SD card conversion script is stable with both Jessie and Stretch. Please reinstall the Zymkey packages and rerun the SD card conversion script again.

Thanks for finding and reporting this issue.


I have tested it.

Thanks for your help!


No problem. Glad we could help :slight_smile:


I am confused at the USB-reuse point. From the procedure description it says the external media is LUKS encrypted, I assumed with the uniqueKey for every Zymkey device. So you could not use in another pair of rPi+Zymkey as the uniqeKey will be different.
What am I missing?


Within the standard LUKS framework a MasterKey is used to encrypt the ‘bulk data contents’ of the USB drive. The LUKS MasterKey is never explosed to the user and only available to the LUKS encrypt/decrypt ‘engine’ when a valid passphrase is presented to it. LUKS supports multiple passphrase / keyslots, allowing multiple users to decrypt content, assuming they present a valid password.

Zymkey integrates with this LUKS framework by generating a unique passphrase (uniqueKEY), just as a user would. Such a uniqueKEY is, as you correctly say, unique to a specific (Pi+ Zymkey + SDcard) binding, therefore cannot be moved from system to system.

The advantage of this approach is that the ‘bulk data contents’ can be pre-encrypted with a common LUKS Masterkey (that is never exposed). Depending upon the size of your file system, this could save considerable time in that the ‘bulk data contents’ only need to encrypted once, in a secure manufacturing facility of your choice. The disadvantage of this approach is that the LUKS Masterkey is common across a fleet of devices, and IF exposed (through concerted effort, time and money) would provide access to a fleet of devices. If that represents a practical security risk to your application (a high threshold in our opinion), then you would have to encrypt each instance seperately and uniquely with a unique LUKS Masterkey.

Ultimately, as in all security matters, its a question of assessing the risk/loss and deciding how much time and effort to spend on building security layers. In this particular situation, you might consider using a common LUKS Masterkey across 10% of your devices, so ten unique LUKS Masterkeys would cover 100% of your fleet of devices.

Hopefully this provides more clarity. Let us know if you need more explanation.


Thanks, this was perfectly clear.


While the toUSB conversion worked nicely I am stuck at the SD-only version.
The process runs smoothly but when it finishes (rPi is rebooted) it only boots if the USB keyboard is plugged in and I don’t see any encrypted system neither in the SDcard nor in the USB.

There is something I am doing terribly wrong but I can not find out: I just ran the script and saw no error message.


Hi @Iker,

For the SD card conversion, please make sure that you have an external USB disk attached. Also, please note that the SD card conversion requires two passes and can take some time - first pass can take 20 to 30 minutes depending on a lot of factors and the second pass can take 5 to 10 minutes. You can tell when the entire process is done when the blue LED stops flashing rapidly and goes to its “operational” mode of flashing once every 3 seconds.

If all of the conditions are true, I’m not sure why a USB keyboard would make any difference.


I run the script and it goes on normally. I have checked USB and SDcard mounts are ok and I see it working. I run the script and leave it working untill the rPi reboots. Should the second pass start then? Should I call it?


@Iker, the second phase of the SD card conversion starts itself, so you don’t have to do anything special. If you have a monitor connected to your Pi, you will notice 2 reboots. After the second reboot, you should see that the root partition is running on dm-0 when you run the df command. This means that the SD card conversion completed successfully.


I’m sure it’s just me not understanding this device and LUKS correctly yet, but while waiting for delivery I thought I could ask.

So it seems from the description that it is not possible to protect the boot partition and the kernel/initramfs, fair enough the bootloader has to be able to read and load them. This means nothing prevents a bad actor modify the RPi’s config file and kernel command line to e.g. see console messages or peek into/change the initramfs (assuming it’s a cpio archive).

  1. The kernel initializes initramfs
  2. initramfs presents the locked LUKS key to Zymkey
  3. Zymkey validates the signature and decrypts the key *
  4. The decrypted key is presented to LUKS and the root file system is then decrypted

Is it so that in the (reasonably) worst case the bad actor would be able to get hold of the encrypted LUKS key from the initramfs, but could not intercept the decrypted key from step 4.?


You are correct. In the current state, the bad actor could extract the encrypted LUKS key from the initramfs, but that would be useless to him because that key is encrypted by the Zymkey. Since the Zymkey operation is tightly coupled to the serial numbers of the host Pi as well as the SD card, the Zymkey would be largely useless to the bad actor if placed in a different environment for analysis or cracking.

We highly recommend configuring at least one tamper detect input for deployments that have an encrypted root file system. When configured for “self destruct” mode, the zymkey would be rendered useless if the tamper detection were triggered. This means that the whole unit would be bricked if the tamper detection were triggered.


Thanks @Scott_of_Zymbit.

Since the Zymkey operation is tightly coupled to the serial numbers of the host Pi as well as the SD card, the Zymkey would be largely useless to the bad actor if placed in a different environment for analysis or cracking.

We highly recommend configuring at least one tamper detect input for deployments that have an encrypted root file system.

The scenario I’m concerned about is where the bad actor does not change the environment. They may use the exact Pi and the exact SD card.
If one of the tamper detect inputs would be the signature of the kernel/initramfs, that would likely mitigate the issue of the bad actor making changes to them, but at first glance that seems to make remote updates impossible.


@hlev80, thanks for the questions. I’ll see if I can answer:

The tamper detect isn’t tied to any kernel signature or any specific key slots. It is a physical perimeter breach detection that can be configured to operate in a “doomsday” manner. In other words, if a tamper detect input were configured in “self-destruct” mode and the root file system were encrypted, then, if a tamper detect event was to occur, all keys in the Zymkey would be destroyed. This means that upon next boot, the whole unit would be bricked by design because the LUKS key could not be decrypted.

Currently, we don’t have anything in place for the kernel to be validated prior to launch via Zymkey signature nor do we have the bits in place for the kernel to self-validate. The reason for the first part (kernel validate prior to launch) is because the GPU boots the ARM CPU and its compiled environment is closed source. The reason for the second part (kernel self-validates its own signature) is because 1) we are trying to work within the existing raspbian infrastructure and 2) our software infrastructure does not communicate to Zymkey via kernel modules.

The above may change based on customer requirements, but we think that for IoT, what we have is a very good strategy for a likely use case: bad actor breaks into IoT box, then Zymkey blows itself up. Encrypted root file system on SD card cannot be deciphered if removed and analyzed.

Hope this answers your questions and/or addresses your concerns.


I see now, thanks @Scott_of_Zymbit, I thought you meant “tamper detect input” as any variable that can be used at binding the Zymkey to its environment, which could in theory include signatures of the kernel or even the bootloaders (at least the ones on the SD, start.elf and the likes)

Btw I ordered the 4i Lite so physical tamper detection will not be available for me.
The device looks interesting and I’m curious to find out how we could utilize it.


@hlev80 No problem at all


I supplied the desired destination partition number with the ‘-p’ option of your installer script, ,
but as I discovered after an otherwise successful install, the script doesn’t appear to be set up to use an already ext4-formatted and partitioned drive,
and it also appears to not be set up to create a partition of the same size after completely wiping it either.
(I do apologize in advance though, if I am mistaken, or there’s a piece of the big picture that I’m missing here.)

I recognize that the installer addresses what’s probably the most commonly-desired use case though.
Installation is pretty smooth and painless as well.

Ideally, I’d like to have my Raspberry Pis set up such that
a) the root file system gets put on one encrypted partition, while the Pi writes collected/received
iot data, system and firewall logs, etc. on another encrypted partition.
b) In the case of using a >1tb HDD in particular, it’d be nice to be able to have have the option of having the above, but also be able to use other partitions for unrelated purposes.

Would it be possible to have the ability to install the Zymkey with LUKS on multi-partitioned drive,
if there are not big encryption and performance problems with any of these desired setups?

(The idea behind a. would be to both avoid accidental running out of disk-space memory for the OS as a backup safety on a smaller drive,
and to try and isolate OS from the frequent write cycles and accompanying elevated data corruption risks (with a usb stick in particular)