ceph/doc/ceph-volume/lvm/encryption.rst

   1 .. _ceph-volume-lvm-encryption:
   2
   3 Encryption
   4 ==========
   5
   6 Logical volumes can be encrypted using ``dmcrypt`` by specifying the
   7 ``--dmcrypt`` flag when creating OSDs. Encryption can be done in different ways,
   8 specially with LVM. ``ceph-volume`` is somewhat opinionated with the way it
   9 sets up encryption with logical volumes so that the process is consistent and
  10 robust.
  11
  12 In this case, ``ceph-volume lvm`` follows these constraints:
  13
  14 * only LUKS (version 1) is used
  15 * Logical Volumes are encrypted, while their underlying PVs (physical volumes)
  16   aren't
  17 * Non-LVM devices like partitions are also encrypted with the same OSD key
  18
  19
  20 LUKS
  21 ----
  22 There are currently two versions of LUKS, 1 and 2. Version 2 is a bit easier
  23 to implement but not widely available in all distros Ceph supports. LUKS 1 is
  24 not going to be deprecated in favor of LUKS 2, so in order to have as wide
  25 support as possible, ``ceph-volume`` uses LUKS version 1.
  26
  27 .. note:: Version 1 of LUKS is just referenced as "LUKS" whereas version 2 is
  28           referred to as LUKS2
  29
  30
  31 LUKS on LVM
  32 -----------
  33 Encryption is done on top of existing logical volumes (unlike encrypting the
  34 physical device). Any single logical volume can be encrypted while other
  35 volumes can remain unencrypted. This method also allows for flexible logical
  36 volume setups, since encryption will happen once the LV is created.
  37
  38
  39 Workflow
  40 --------
  41 When setting up the OSD, a secret key will be created, that will be passed
  42 along to the monitor in JSON format as stdin to prevent the key from being
  43 captured in the logs.
  44
  45 The JSON payload looks something like::
  46
  47         {
  48             "cephx_secret": CEPHX_SECRET,
  49             "dmcrypt_key": DMCRYPT_KEY,
  50             "cephx_lockbox_secret": LOCKBOX_SECRET,
  51         }
  52
  53 The naming convention for the keys is **strict**, and they are named like that
  54 for the hardcoded (legacy) names ceph-disk used.
  55
  56 * ``cephx_secret`` : The cephx key used to authenticate
  57 * ``dmcrypt_key`` : The secret (or private) key to unlock encrypted devices
  58 * ``cephx_lockbox_secret`` : The authentication key used to retrieve the
  59   ``dmcrypt_key``. It is named *lockbox* because ceph-disk used to have an
  60   unencrypted partition named after it, used to store public keys and other
  61   OSD metadata.
  62
  63 The naming convention is strict because Monitors supported the naming
  64 convention by ceph-disk, which used these key names. In order to keep
  65 compatibility and prevent ceph-disk from breaking, ceph-volume will use the same
  66 naming convention *although they don't make sense for the new encryption
  67 workflow*.
  68
  69 After the common steps of setting up the OSD during the prepare stage, either
  70 with :term:`filestore` or :term:`bluestore`, the logical volume is left ready
  71 to be activated, regardless of the state of the device (encrypted or decrypted).
  72
  73 At activation time, the logical volume will get decrypted and the OSD started
  74 once the process completes correctly.
  75
  76 Summary of the encryption workflow for creating a new OSD:
  77
  78 #. OSD is created, both lockbox and dmcrypt keys are created, and sent along
  79    with JSON to the monitors, indicating an encrypted OSD.
  80
  81 #. All complementary devices (like journal, db, or wal) get created and
  82    encrypted with the same OSD key. Key is stored in the LVM metadata of the
  83    OSD
  84
  85 #. Activation continues by ensuring devices are mounted, retrieving the dmcrypt
  86    secret key from the monitors and decrypting before the OSD gets started.