ceph/doc/rbd/rbd-encryption.rst

   1 ======================
   2  Image Encryption
   3 ======================
   4
   5 .. index:: Ceph Block Device; encryption
   6
   7 Starting with the Pacific release, image-level encryption can be handled
   8 internally by RBD clients. This means you can set a secret key that will be
   9 used to encrypt a specific RBD image. This page describes the scope of the
  10 RBD encryption feature.
  11
  12 .. note::
  13    The ``krbd`` kernel module does not support encryption at this time.
  14
  15 .. note::
  16    External tools (e.g. dm-crypt, QEMU) can be used as well to encrypt
  17    an RBD image, and the feature set and limitation set for that use may be
  18    different than described here.
  19
  20 Encryption Format
  21 =================
  22
  23 By default, RBD images are not encrypted. To encrypt an RBD image, it needs to
  24 be formatted to one of the supported encryption formats. The format operation
  25 persists encryption metadata to the image. The encryption metadata usually
  26 includes information such as the encryption format and version, cipher
  27 algorithm and mode specification, as well as information used to secure the
  28 encryption key. The encryption key itself is protected by a user-kept secret
  29 (usually a passphrase), which is never persisted. The basic encryption format
  30 operation will require specifying the encryption format and a secret.
  31
  32 Some of the encryption metadata may be stored as part of the image data,
  33 typically an encryption header will be written to the beginning of the raw
  34 image data. This means that the effective image size of the encrypted image may
  35 be lower than the raw image size. See the `Supported Formats`_ section for more
  36 details.
  37
  38 .. note::
  39    Currently only flat images (i.e. not cloned) can be formatted.
  40    Clones of an encrypted image are inherently encrypted using the same format
  41    and secret.
  42
  43 .. note::
  44    Any data written to the image prior to its format may become unreadable,
  45    though it may still occupy storage resources.
  46
  47 .. note::
  48    Images with the `journal feature`_ enabled cannot be formatted and encrypted
  49    by RBD clients.
  50
  51 Encryption Load
  52 =================
  53
  54 Formatting an image is a necessary pre-requisite for enabling encryption.
  55 However, formatted images will still be treated as raw unencrypted images by
  56 all of the RBD APIs. In particular, an encrypted RBD image can be opened
  57 by the same APIs as any other image, and raw unencrypted data can be
  58 read / written. Such raw IOs may risk the integrity of the encryption format,
  59 for example by overriding encryption metadata located at the beginning of the
  60 image.
  61
  62 In order to safely perform encrypted IO on the formatted image, an additional
  63 *encryption load* operation should be applied after opening the image. The
  64 encryption load operation requires supplying the encryption format and a secret
  65 for unlocking the encryption key. Following a successful encryption load
  66 operation, all IOs for the opened image will be encrypted / decrypted.
  67 For a cloned image, this includes IOs for ancestor images as well. The
  68 encryption key will be stored in-memory by the RBD client until the image is
  69 closed.
  70
  71 .. note::
  72    Once encryption has been loaded, no other encryption load / format
  73    operations can be applied to the context of the opened image.
  74
  75 .. note::
  76    Once encryption has been loaded, API calls for retrieving the image size
  77    using the opened image context will return the effective image size.
  78
  79 .. note::
  80    Encryption load can be automatically applied when mounting RBD images as
  81    block devices via `rbd-nbd`_.
  82
  83 Supported Formats
  84 =================
  85
  86 LUKS
  87 ~~~~~~~
  88
  89 Both LUKS1 and LUKS2 are supported. The data layout is fully compliant with the
  90 LUKS specification. Thus, images formatted by RBD can be loaded using external
  91 LUKS-supporting tools such as dm-crypt or QEMU. Furthermore, existing LUKS
  92 data, created outside of RBD, can be imported (by copying the raw LUKS data
  93 into the image) and loaded by RBD encryption.
  94
  95 .. note::
  96    The LUKS formats are supported on Linux-based systems only.
  97
  98 .. note::
  99    Currently, only AES-128 and AES-256 encryption algorithms are supported.
 100    Additionally, xts-plain64 is currently the only supported encryption mode.
 101
 102 To use the LUKS format, start by formatting the image::
 103
 104     $ rbd encryption format {pool-name}/{image-name} {luks1|luks2} {passphrase-file} [–cipher-alg {aes-128 | aes-256}]
 105
 106 The encryption format operation generates a LUKS header and writes it to the
 107 beginning of the image. The header is appended with a single keyslot holding a
 108 randomly-generated encryption key, and is protected by the passphrase read from
 109 `passphrase-file`.
 110
 111 .. note::
 112    If the content of `passphrase-file` ends with a newline character, it will
 113    be stripped off.
 114
 115 By default, AES-256 in xts-plain64 mode (which is the current recommended mode,
 116 and the usual default for other tools) will be used. The format operation
 117 allows selecting AES-128 as well. Adding / removing passphrases is currently
 118 not supported by RBD, but can be applied to the raw RBD data using compatible
 119 tools such as cryptsetup.
 120
 121 The LUKS header size can vary (upto 136MiB in LUKS2), but is usually upto
 122 16MiB, depending on the version of `libcryptsetup` installed. For optimal
 123 performance, the encryption format will set the data offset to be aligned with
 124 the image object size. For example expect a minimum overhead of 8MiB if using
 125 an imageconfigured with an 8MiB object size.
 126
 127 In LUKS1, sectors, which are the minimal encryption units, are fixed at 512
 128 bytes. LUKS2 supports larger sectors, and for better performance we set
 129 the default sector size to the maximum of 4KiB. Writes which are either smaller
 130 than a sector, or are not aligned to a sector start, will trigger a guarded
 131 read-modify-write chain on the client, with a considerable latency penalty.
 132 A batch of such unaligned writes can lead to IO races which will further
 133 deteriorate performance. Thus it is advisable to avoid using RBD encryption
 134 in cases where incoming writes cannot be guaranteed to be sector-aligned.
 135
 136 To mount a LUKS-encrypted image run::
 137
 138     $ rbd -p {pool-name} device map -t nbd -o encryption-format={luks1|luks2},encryption-passphrase-file={passphrase-file}
 139
 140 Note that for security reasons, both the encryption format and encryption load
 141 operations are CPU-intensive, and may take a few seconds to complete. For the
 142 encryption operations of actual image IO, assuming AES-NI is enabled,
 143 a relative small microseconds latency should be added, as well as a small
 144 increase in CPU utilization.
 145
 146 .. _journal feature: ../rbd-mirroring/#enable-image-journaling-feature
 147 .. _Supported Formats: #supported-formats
 148 .. _rbd-nbd: ../../man/8/rbd-nbd