crypto-drive-manager 3.0
Unlock all your encrypted drives with one pass phrase.

crypto-drive-manager: Unlock all your encrypted drives with one pass phrase
---------------------------------------------------------------------------

The ``crypto-drive-manager`` program allows you to safely, quickly and
conveniently unlock an unlimited number of `LUKS encrypted devices`_ using a
single pass phrase. You can think of it as a `key pass`_ for LUKS encrypted
devices. It works by creating a small (10 MB) encrypted file system inside a
regular file (using a `loop device`_) and storing key files for the encrypted
devices of your choosing inside this encrypted file system. Each time you run
the program it temporarily unlocks the 10 MB encrypted file system and uses the
key files to unlock and mount encrypted devices that are present and not
already unlocked.

.. contents::
   :local:

Installation
------------

The `crypto-drive-manager` program is written in Python and is available on
PyPI_ which means installation should be as simple as::

  $ pip install crypto-drive-manager

There's actually a multitude of ways to install Python packages (e.g. the `per
user site-packages directory`_, `virtual environments`_ or just installing
system wide) and I have no intention of getting into that discussion here, so
if this intimidates you then read up on your options before returning to these
instructions ;-).

Configuration
-------------

The `crypto-drive-manager` program doesn't have a configuration file because
it looks at your system configuration to infer what it should do. You need to
create or change ``/etc/crypttab`` in order to enable `crypto-drive-manager`.
As an example here's my ``/etc/crypttab`` file::

  # <target name>  <source device>                            <key file>                 <options>
  internal-hdd     UUID=626f4560-cf80-4ed9-b211-ac263b41ca67  none                       luks
  media-files      UUID=6d413429-f8d1-4d8e-8a3a-075603b8efdd  /mnt/keys/media-files.key  luks,noauto
  mirror3          UUID=978d7a3a-c902-43e6-aa71-5654d406c247  /mnt/keys/mirror3.key      luks,noauto
  mirror4          UUID=7a48e547-1dfa-4c6a-96e9-05842c87465d  /mnt/keys/mirror4.key      luks,noauto
  mirror5          UUID=ac6aa22a-0c32-4bd9-829a-75316177affb  /mnt/keys/mirror5.key      luks,noauto
  mirror6          UUID=00474636-6d6e-4ecc-a7d6-21b42d850ac6  /mnt/keys/mirror6.key      luks,noauto
  mirror7          UUID=ec56dc10-1086-4f2b-808c-88995cb8b513  /mnt/keys/mirror7.key      luks,noauto

You can see why I don't want to manage all of these encrypted devices manually
by entering pass phrases for each of them :-). Even though my root device
(``internal-hdd``) is also encrypted, storing key files to unlock my encrypted
devices on my root device doesn't feel right because the key files will be
exposed at all times.

You tell `crypto-drive-manager` to manage an encrypted device by setting the
key file (the third field in ``/etc/crypttab``) to a file located under the
mount point used by `crypto-drive-manager` ( ``/mnt/keys`` by default). Every
time you run `crypto-drive-manager` it parses ``/etc/crypttab`` to find and
unlock managed devices. The ``UUID=...`` definition in ``/etc/crypttab`` is
used to check if the physical device exists in ``/dev/disk/by-uuid``. Because
of this a source device definition with a ``UUID=...`` value is required.

Each physical device that exists is initialized, unlocked and mounted. Device
initialization happens when the key file for the encrypted device doesn't exist
yet: The key file is created with 4 KB of random bytes and installed as a key
on the encrypted device.

The end result is a program that requires a single pass phrase to unlock a
virtual keys device containing key files used to unlock a group of encrypted
devices. Once the encrypted devices have been unlocked the virtual keys device
is unmounted and the keys are no longer available (except in memory, which
cannot be avoided to the best of my knowledge).

Usage
-----

.. A DRY solution to avoid duplication of the `crypto-drive-manager --help' text:
..
.. [[[cog
.. from humanfriendly.usage import inject_usage
.. inject_usage('crypto_drive_manager.cli')
.. ]]]

**Usage:** `crypto-drive-manager [OPTIONS] [NAME, ..]`

Safely, quickly and conveniently unlock an unlimited number of LUKS encrypted
devices using a single pass phrase.

By default all entries in /etc/crypttab that reference a key file located under
the mount point of the encrypted disk with key files are unlocked (as needed).
To unlock a subset of the configured devices you can pass one or more ``NAME``
arguments that match mapper name(s) configured in /etc/crypttab.

**Supported options:**

.. csv-table::
   :header: Option, Description
   :widths: 30, 70


   "``-i``, ``--image-file=PATH``","Set the pathname of the file that contains the encrypted disk image with
   key files (defaults to '/root/encryption-keys.img')."
   "``-n``, ``--mapper-name=NAME``","Set the mapper device name for the encrypted disk with key files so that
   the device for the drive with key files will be created as
   '/dev/mapper/NAME' (defaults to 'encryption-keys')."
   "``-m``, ``--mount-point=PATH``","Set the pathname of the mount point for the encrypted disk with key files
   (defaults to '/mnt/keys')."
   ``--install-systemd-workaround``,"Replace the systemd-cryptsetup-generator program with a wrapper that
   removes the 'RequiresMountsFor' option from the generated configuration
   files at /var/run/systemd/generator/\*.service.

   Refer to the readme for more details about how this works."
   "``-v``, ``--verbose``",Increase logging verbosity (can be repeated).
   "``-q``, ``--quiet``",Decrease logging verbosity (can be repeated).
   "``-h``, ``--help``",Show this message and exit.

.. [[[end]]]

Problems
--------

When I upgraded my personal server to Ubuntu 16.04 and rebooted the system I
was immediately bitten by `systemd issue #3816`_: When any of the encrypted
drives managed by `crypto-drive-manager` are affected by this issue then
unmounting of the keys device will cause systemd to immediately unmount and
lock those encrypted drives.

My initial workaround for this issue (released in crypto-drive-manager 2.0) was
to simply leave the virtual keys device unlocked and mounted, but of course
this went straight against how `crypto-drive-manager` was originally designed
and intended to work.

In crypto-drive-manager 3.0 I implemented and released a real workaround:

1. The command ``crypto-drive-manager --install-systemd-workaround`` replaces
   ``/lib/systemd/system-generators/systemd-cryptsetup-generator`` with a
   symbolic link to the `crypto-drive-manager` program. The original
   generator program is renamed so that it remains accessible.

2. When ``systemctl daemon-reload`` is run it calls `crypto-drive-manager`
   by following the symbolic link (without realizing it of course).

3. By checking the value of ``sys.argv[0]`` the `crypto-drive-manager`
   program can determine whether it's being run by ``systemd``.

4. In this case `crypto-drive-manager` will first run the original generator
   program and then it will rewrite the generated service files located in
   ``/var/run/systemd/generator`` to remove ``RequiresMountsFor`` fields.

5. By the time ``systemd`` rereads its configuration files the
   ``RequiresMountsFor`` fields have already been removed.

6. Because ``crypto-drive-manager`` automatically detects the presence or
   absence of problematic ``RequiresMountsFor`` fields it will detect its own
   workaround and properly lock the virtual keys device after use.

7. Profit! :-P

To be honest all of this started as a thought experiment with me trying to
verify my understanding of the problem and what would be involved to fix it.
Once I realized that my (nasty! I know) workaround was actually effective I
decided I might as well publish it. I do actually use this workaround on my
personal server (for whatever that's worth).

Contact
-------

The latest version of `crypto-drive-manager` is available on PyPI_ and
GitHub_. For bug reports please create an issue on GitHub_. If you have
questions, suggestions, etc. feel free to send me an e-mail at
`peter@peterodding.com`_.

License
-------

This software is licensed under the `MIT license`_.

© 2017 Peter Odding.

.. External references:
.. _GitHub: https://github.com/xolox/python-crypto-drive-manager
.. _key pass: http://en.wikipedia.org/wiki/Password_manager
.. _loop device: http://en.wikipedia.org/wiki/Loop_device
.. _LUKS encrypted devices: http://en.wikipedia.org/wiki/Linux_Unified_Key_Setup
.. _MIT license: http://en.wikipedia.org/wiki/MIT_License
.. _per user site-packages directory: https://www.python.org/dev/peps/pep-0370/
.. _peter@peterodding.com: mailto:peter@peterodding.com
.. _PyPI: https://pypi.python.org/pypi/crypto-drive-manager
.. _systemd issue #3816: https://github.com/systemd/systemd/issues/3816
.. _virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/