RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2025-01-03 09:32:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/ceph-volume: refine encryption.rst

Browse Source 
Improve the word choice and grammar of
doc/ceph-volume/lvm/encryption.rst.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
This commit is contained in:
Zac Dover 2023-01-17 19:45:23 +10:00
parent ece58aaaae
commit 6f7f7c8f65
1 changed files with 34 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/ceph-volume/lvm/encryption.rst
View File

@ -4,42 +4,41 @@ Encryption
==========
Logical volumes can be encrypted using ``dmcrypt`` by specifying the
``--dmcrypt`` flag when creating OSDs. Encryption can be done in different ways,
specially with LVM. ``ceph-volume`` is somewhat opinionated with the way it
sets up encryption with logical volumes so that the process is consistent and
``--dmcrypt`` flag when creating OSDs. When using LVM, logical volumes can be
encrypted in different ways. ``ceph-volume`` does not offer as many options as
LVM does, but it encrypts logical volumes in a way that is consistent and
robust.
In this case, ``ceph-volume lvm`` follows these constraints:
In this case, ``ceph-volume lvm`` follows this constraint:
* Logical Volumes are encrypted, while their underlying PVs (physical volumes)
aren't
* Non-LVM devices like partitions are also encrypted with the same OSD key
* Non-LVM devices (such as partitions) are encrypted with the same OSD key.
LUKS
----
There are currently two versions of LUKS, 1 and 2. Version 2 is a bit easier
to implement but not widely available in all distros Ceph supports.
There are currently two versions of LUKS, 1 and 2. Version 2 is a bit easier to
implement but not widely available in all Linux distributions supported by
Ceph.
.. note:: Version 1 of LUKS is just referenced as "LUKS" whereas version 2 is
referred to as LUKS2
.. note:: Version 1 of LUKS is referred to in this documentation as "LUKS".
Version 2 is of LUKS is referred to in this documentation as "LUKS2".
LUKS on LVM
-----------
Encryption is done on top of existing logical volumes (unlike encrypting the
physical device). Any single logical volume can be encrypted while other
volumes can remain unencrypted. This method also allows for flexible logical
Encryption is done on top of existing logical volumes (this is not the same as
encrypting the physical device). Any single logical volume can be encrypted,
leaving other volumes unencrypted. This method also allows for flexible logical
volume setups, since encryption will happen once the LV is created.
Workflow
--------
When setting up the OSD, a secret key will be created, that will be passed
along to the monitor in JSON format as ``stdin`` to prevent the key from being
When setting up the OSD, a secret key is created. That secret key is passed
to the monitor in JSON format as ``stdin`` to prevent the key from being
captured in the logs.
The JSON payload looks something like::
The JSON payload looks something like this::
{
"cephx_secret": CEPHX_SECRET,
@ -48,36 +47,38 @@ The JSON payload looks something like::
}
The naming convention for the keys is **strict**, and they are named like that
for the hardcoded (legacy) names ceph-disk used.
for the hardcoded (legacy) names used by ceph-disk.
* ``cephx_secret`` : The cephx key used to authenticate
* ``dmcrypt_key`` : The secret (or private) key to unlock encrypted devices
* ``cephx_lockbox_secret`` : The authentication key used to retrieve the
``dmcrypt_key``. It is named *lockbox* because ceph-disk used to have an
unencrypted partition named after it, used to store public keys and other
OSD metadata.
unencrypted partition named after it, which was used to store public keys and
other OSD metadata.
The naming convention is strict because Monitors supported the naming
convention by ceph-disk, which used these key names. In order to keep
compatibility and prevent ceph-disk from breaking, ceph-volume will use the same
naming convention *although they don't make sense for the new encryption
convention of ceph-disk, which used these key names. In order to maintain
compatibility and prevent ceph-disk from breaking, ceph-volume uses the same
naming convention *although it does not make sense for the new encryption
workflow*.
After the common steps of setting up the OSD during the prepare stage, either
with :term:`filestore` or :term:`bluestore`, the logical volume is left ready
to be activated, regardless of the state of the device (encrypted or decrypted).
After the common steps of setting up the OSD during the "prepare stage" (either
with :term:`filestore` or :term:`bluestore`), the logical volume is left ready
to be activated, regardless of the state of the device (encrypted or
decrypted).
At activation time, the logical volume will get decrypted and the OSD started
once the process completes correctly.
At the time of its activation, the logical volume is decrypted. The OSD starts
after the process completes correctly.
Summary of the encryption workflow for creating a new OSD:
Summary of the encryption workflow for creating a new OSD
----------------------------------------------------------
#. OSD is created, both lockbox and dmcrypt keys are created, and sent along
with JSON to the monitors, indicating an encrypted OSD.
#. OSD is created. Both lockbox and dmcrypt keys are created and sent to the
monitors in JSON format, indicating an encrypted OSD.
#. All complementary devices (like journal, db, or wal) get created and
encrypted with the same OSD key. Key is stored in the LVM metadata of the
OSD
OSD.
#. Activation continues by ensuring devices are mounted, retrieving the dmcrypt
secret key from the monitors and decrypting before the OSD gets started.
secret key from the monitors, and decrypting before the OSD gets started.