Your rating: None Average: 4.9 (9 votes)

Unlocking and mounting encrypted SD-cards automatically

The necessary steps to prepare an SD-card are described at (TJC).

crypto-sdcard solely protects "data at rest" on SD-cards, i.e. specifically when the device is locked or switched off (and the SD-card may be taken out), as the "key"-files reside unencrypted on fixed, internal mass storage of the device.


  • For devices, which need to load Qualcomm's qcrypto kernel module in order to support modern cryptographic schemes as e.g. XTS, a separate "qcrypto edition" is provided.
    As the Jolla 1 (sbj) is the only known such device, it currently is the only device supported by the "qcrypto edition".
    For all other devices, this regular edition shall be used.
  • Do reboot before using crypto-sdcard.
  • These RPM packages contain newer versions of the configuration files originally posted at TJC, which are now hosted at Github.
  • "Key"-file path and names are:
    • For Cryptsetup LUKS:
    • For Cryptsetup "plain":
    • A specific "<UUID>" can be obtained by executing
      blkid -s UUID -o value /dev/<device-name>
      with e.g. "mmcblk1p2" as "<device-name>".
  • For discussing the necessary preparation of SD-cards (i.e., partitioning and formatting them, plus the usage of Cryptsetup and creating "key"-files), please use the corresponding thread on TJC.
  • For discussing crypto-sdcard's specific configuration files and its RPM packaging, please use its issue tracker at Github.
  • Issues with these RPM packages or the configuration files they install shall also be filed at crypto-sdcard's issue tracker at Github.
  • As this web-page at OpenRepos merely exists for describing and distributing the crypto-sdcard (regular edition) RPMs, there is no need for issuing comments here.


  • These configuration files do not alter, replace or delete any extant files.
  • Support of encrypted partitions and whole devices.
  • Support for (µ)SD-cards and USB-attached storage (if supported by device hardware and Operating System).
  • Interoperable with SailfishOS GUI apps (see details).
  • Support for Cryptsetup LUKS and Cryptsetup "plain".
    • Note that SailfishOS just recently (with v3.0.3) switched to Cryptsetup 2, and so did most (desktop) Linux distributions. For interoperability with extant Linux installations and commonality with SailfishOS before v3.0.3, which provide Cryptsetup 1.x (therefore only support LUKSv1 headers), the "partitioning guide" aims at creating LUKSv1 headers.
    • As Cryptsetup LUKS reads the cryptography parameters from the LUKS header and Cryptsetup 2 supports both v1 and v2 headers, crypto-sdcard shall work fine with any LUKS header version and parameters, which are valid for the installed Cryptsetup version.
    • For Cryptsetup "plain" (only to be used, when "plausible deniability" is a must), crypto-sdcard has to provide the cryptography parameters and uses "-h sha1 -s 256 -c aes-xts-plain" by default. While these parameters are optimised for speed, low power consumption, interoperability and sufficiently strong security for the next decade (including the specific use of SHA1 for hashing a pass-file down to 160 bits), other parameters may be set for unlocking Cryptsetup "plain" in /etc/systemd/system/cryptosd-plain@.service.
    • Since crypto-sdcard 1.3.4, the parsing of "key"-files in "plain" mode is enhanced (as an experimental feature).
      This change requires to convert extant "key"-files for "plain" mode.
      New "plain" "containers" shall be created slightly differently now, in order to take advantage of this enhancement.
  • Start mounting encrypted (partitions on) SD-card via udisks at the earliest sensible time: Right after udisks2.service has started.
  • Unmount before udisks2.service begins stopping, hence achieving a clean unmount.
  • Since v1.3.4 the Systemd EnvironmentFiles mount-cryptosd-luks@.conf and mount-cryptosd-luks@crypto_luks_<UUID>.conf (in this order), respectively mount-cryptosd-plain@.conf and mount-cryptosd-plain@crypto_plain_<device-name>.conf, in /var/lib/environment/udisks2/ are evaluated for additional mount options, if they exist (one or both). Take a look at ls /dev/mapper/crypto* for the partition specific part (between the @ and the .conf extension) of the file names for the partition specific configuration files.
    These configuration files can be created by a system administrator (i.e., you), so if you want to add restricting mount options, see here for details.
  • Ensure, that AlienDalvik begins starting after mounting succeeded, to allow for android_storage on SD-card.
    Even more importantly (i.e., also relevant for devices without "android_storage on SD-card") this also ensures, that unmounting occurs only after AlienDalvik has completely stopped.
    Nevertheless, these configuration files are also applicable to devices without AlienDalvik installed.
  • Boot time is not significantly prolonged, as unlocking encrypted partitions per Cryptsetup occurs in parallel to starting udisks2.service; after both succeeded, all mount operations are also started concurrently.
  • Versions below 1.0: Create / try to rectify the "compatibility symlink" in order to allow older apps seamlessly accessing encrypted (partitions on) SD-cards at their new (since SailfishOS 2.2.0) mount point.


Application versions: 


olf's picture

FYI: Some change in SailfishOS 4.0.1 broke crypto-sdcard, see issue #115 for details.
An easy workaround how to manually mount an encrypted partition is described there.

This is still under investigation, and implementing a proper solution will follow when the cause is fully understood; any help with that (all three aspects: investigating, understanding and implementing) is welcome (at issue #115)!

olf's picture

Should be fixed per crypto-sdcard-1.4.2-1.sfos401regular.

Manually starting an instanciated unit (either one, it will start the corresponding one for unlocking or mounting) under SailfishOS 4.x.y shall be fixed in crypto-sdcard-1.5.2-1.sfos401regular.noarch.rpm and crypto-sdcard-1.7.1-1.sfos401regular.noarch.rpm.

Ultimately crypto-sdcard-1.7.2-1.sfos401regular.noarch.rpm should also enable the main function for SailfishOS 4: Automatic unlocking and mounting of encrypted partitions on OS boot-up (µSD-cards and USB-storage) or when hot-plugging USB-OTG mass storage devices.

Please report success or the lack of it at issue #115, including your phone model, SailfishOS 4.x.y release, if "LUKS"- or "plain"-encrypted, which local device path was used, and what kind of mass storage this physically is.
My report is: Successfully hot-plugging on XperiaXA2Plus@SFOS4.0.1, "plain"@sda3, USB-FLASH-Stick (Kingston DataTraveller G4, "32 GB").

P.S. / edit: Automatic unlocking and mounting of encrypted partitions under SailfishOS 4 on OS boot-up turned out to be still broken in crypto-sdcard-1.7.2-1.sfos401regular.noarch.rpm (but only on boot-up; any later triggering works, be it manually or per hot-plug).
A new release will be prepared, when the reason for this (hopefully: last) flaw under SailfishOS 4 is determined.

zipotron's picture

Hello! I had it working good, but after update system to os3.4 is not automonting at boot any more, I updated the app too, I did the steps of the forum again, but no way to make it work again... any idea? Thanks!

fooxl's picture

See this issue. You have to edit some files.

olf's picture

Thank you @fooxl for providing a link to this issue here.

Meanwhile I fixed the breakage SFOS 3.4.0 brought (by the help of some analysis and testing from @fuchsmich) in crypto-sdcard-1.3.1-1.sfos340.noarch.rpm

yeoldegrove's picture

This is a killer feature app. Writing this from a fully encrypred Sailfish 3.3 phone.

olf's picture

BTW, crypto-sdcard is in "maintenance mode" since version 1.0, as it appears to be stable and feature complete for its users.
That means there will be no new releases, unless bugs are reported (preferably at Github) or a new SailfishOS release breaks it.

fooxl's picture

What is the reason it's not compatible with SFOS 3.0?

olf's picture

v0.5-4 and later versions should install flawlessly under SFOS 3.0.0.
Do you have issues installing crypto-sdcard?