Metadata-Version: 1.1
Name: crypto-drive-manager
Version: 3.0
Summary: Unlock all your encrypted drives with one pass phrase.
Home-page: https://github.com/xolox/python-crypto-drive-manager
Author: Peter Odding
Author-email: peter@peterodding.com
License: UNKNOWN
Description-Content-Type: UNKNOWN
Description: 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/
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
