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