]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
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:: | |
1e59de90 TL |
39 | Unless explicitly (re-)formatted, clones of an encrypted image are |
40 | inherently encrypted using the same format and secret. | |
41 | ||
42 | .. note:: | |
43 | Clones of an encrypted image are always encrypted. | |
44 | Re-formatting to plaintext is not supported. | |
f67539c2 TL |
45 | |
46 | .. note:: | |
47 | Any data written to the image prior to its format may become unreadable, | |
48 | though it may still occupy storage resources. | |
49 | ||
50 | .. note:: | |
51 | Images with the `journal feature`_ enabled cannot be formatted and encrypted | |
52 | by RBD clients. | |
53 | ||
54 | Encryption Load | |
55 | ================= | |
56 | ||
57 | Formatting an image is a necessary pre-requisite for enabling encryption. | |
58 | However, formatted images will still be treated as raw unencrypted images by | |
59 | all of the RBD APIs. In particular, an encrypted RBD image can be opened | |
60 | by the same APIs as any other image, and raw unencrypted data can be | |
61 | read / written. Such raw IOs may risk the integrity of the encryption format, | |
62 | for example by overriding encryption metadata located at the beginning of the | |
63 | image. | |
64 | ||
65 | In order to safely perform encrypted IO on the formatted image, an additional | |
66 | *encryption load* operation should be applied after opening the image. The | |
67 | encryption load operation requires supplying the encryption format and a secret | |
1e59de90 TL |
68 | for unlocking the encryption key for the image itself and each of its explicitly |
69 | formatted ancestor images. Following a successful encryption load operation, | |
70 | all IOs for the opened image will be encrypted / decrypted. For a cloned | |
71 | image, this includes IOs for ancestor images as well. The encryption keys will | |
72 | be stored in-memory by the RBD client until the image is closed. | |
f67539c2 TL |
73 | |
74 | .. note:: | |
75 | Once encryption has been loaded, no other encryption load / format | |
76 | operations can be applied to the context of the opened image. | |
77 | ||
78 | .. note:: | |
79 | Once encryption has been loaded, API calls for retrieving the image size | |
1e59de90 TL |
80 | and the parent overlap using the opened image context will return the |
81 | effective image size and the effective parent overlap respectively. | |
82 | ||
83 | .. note:: | |
84 | Once encryption has been loaded, API calls for resizing the image will | |
85 | interpret the specified target size as effective image size. | |
86 | ||
87 | .. note:: | |
88 | If a clone of an encrypted image is explicitly formatted, the operation of | |
89 | flattening the cloned image ceases to be transparent since the parent data | |
90 | must be re-encrypted according to the cloned image format as it is copied | |
91 | from the parent snapshot. If encryption is not loaded before the flatten | |
92 | operation is issued, any parent data that was previously accessible in the | |
93 | cloned image may become unreadable. | |
94 | ||
95 | .. note:: | |
96 | If a clone of an encrypted image is explicitly formatted, the operation of | |
97 | shrinking the cloned image ceases to be transparent since in some cases | |
98 | (e.g. if the cloned image has snapshots or if the cloned image is being | |
99 | shrunk to a size that is not aligned with the object size) it involves | |
100 | copying some data from the parent snapshot, similar to flattening. If | |
101 | encryption is not loaded before the shrink operation is issued, any parent | |
102 | data that was previously accessible in the cloned image may become | |
103 | unreadable. | |
f67539c2 TL |
104 | |
105 | .. note:: | |
106 | Encryption load can be automatically applied when mounting RBD images as | |
107 | block devices via `rbd-nbd`_. | |
108 | ||
109 | Supported Formats | |
110 | ================= | |
111 | ||
112 | LUKS | |
113 | ~~~~~~~ | |
114 | ||
115 | Both LUKS1 and LUKS2 are supported. The data layout is fully compliant with the | |
116 | LUKS specification. Thus, images formatted by RBD can be loaded using external | |
117 | LUKS-supporting tools such as dm-crypt or QEMU. Furthermore, existing LUKS | |
118 | data, created outside of RBD, can be imported (by copying the raw LUKS data | |
119 | into the image) and loaded by RBD encryption. | |
120 | ||
121 | .. note:: | |
122 | The LUKS formats are supported on Linux-based systems only. | |
123 | ||
124 | .. note:: | |
125 | Currently, only AES-128 and AES-256 encryption algorithms are supported. | |
126 | Additionally, xts-plain64 is currently the only supported encryption mode. | |
127 | ||
1e59de90 TL |
128 | To use the LUKS format, start by formatting the image: |
129 | ||
130 | .. prompt:: bash $ | |
f67539c2 | 131 | |
1e59de90 | 132 | rbd encryption format [--cipher-alg {aes-128|aes-256}] {image-spec} {luks1|luks2} {passphrase-file} |
f67539c2 TL |
133 | |
134 | The encryption format operation generates a LUKS header and writes it to the | |
135 | beginning of the image. The header is appended with a single keyslot holding a | |
136 | randomly-generated encryption key, and is protected by the passphrase read from | |
137 | `passphrase-file`. | |
138 | ||
139 | .. note:: | |
1e59de90 TL |
140 | In older versions, if the content of `passphrase-file` ended with a newline |
141 | character, it was stripped off. | |
f67539c2 TL |
142 | |
143 | By default, AES-256 in xts-plain64 mode (which is the current recommended mode, | |
144 | and the usual default for other tools) will be used. The format operation | |
145 | allows selecting AES-128 as well. Adding / removing passphrases is currently | |
146 | not supported by RBD, but can be applied to the raw RBD data using compatible | |
147 | tools such as cryptsetup. | |
148 | ||
20effc67 | 149 | The LUKS header size can vary (up to 136MiB in LUKS2), but is usually up to |
f67539c2 TL |
150 | 16MiB, depending on the version of `libcryptsetup` installed. For optimal |
151 | performance, the encryption format will set the data offset to be aligned with | |
1e59de90 TL |
152 | the image stripe period size. For example, expect a minimum overhead of 8MiB if |
153 | using an image configured with an 8MiB object size and a minimum overhead of | |
154 | 12MiB if using an image configured with a 4MiB object size and `stripe count`_ | |
155 | of 3. | |
f67539c2 TL |
156 | |
157 | In LUKS1, sectors, which are the minimal encryption units, are fixed at 512 | |
158 | bytes. LUKS2 supports larger sectors, and for better performance we set | |
159 | the default sector size to the maximum of 4KiB. Writes which are either smaller | |
160 | than a sector, or are not aligned to a sector start, will trigger a guarded | |
161 | read-modify-write chain on the client, with a considerable latency penalty. | |
162 | A batch of such unaligned writes can lead to IO races which will further | |
163 | deteriorate performance. Thus it is advisable to avoid using RBD encryption | |
164 | in cases where incoming writes cannot be guaranteed to be sector-aligned. | |
165 | ||
1e59de90 | 166 | To map a LUKS-formatted image run: |
f67539c2 | 167 | |
1e59de90 TL |
168 | .. prompt:: bash # |
169 | ||
170 | rbd device map -t nbd -o encryption-passphrase-file={passphrase-file} {image-spec} | |
f67539c2 TL |
171 | |
172 | Note that for security reasons, both the encryption format and encryption load | |
173 | operations are CPU-intensive, and may take a few seconds to complete. For the | |
174 | encryption operations of actual image IO, assuming AES-NI is enabled, | |
175 | a relative small microseconds latency should be added, as well as a small | |
176 | increase in CPU utilization. | |
177 | ||
1e59de90 TL |
178 | Examples |
179 | ======== | |
180 | ||
181 | Create a LUKS2-formatted image with the effective size of 50GiB: | |
182 | ||
183 | .. prompt:: bash $ | |
184 | ||
185 | rbd create --size 50G mypool/myimage | |
186 | rbd encryption format mypool/myimage luks2 passphrase.bin | |
187 | rbd resize --size 50G --encryption-passphrase-file passphrase.bin mypool/myimage | |
188 | ||
189 | ``rbd resize`` command at the end grows the image to compensate for the | |
190 | overhead associated with the LUKS2 header. | |
191 | ||
192 | Given a LUKS2-formatted image, create a LUKS2-formatted clone with the | |
193 | same effective size: | |
194 | ||
195 | .. prompt:: bash $ | |
196 | ||
197 | rbd snap create mypool/myimage@snap | |
198 | rbd snap protect mypool/myimage@snap | |
199 | rbd clone mypool/myimage@snap mypool/myclone | |
200 | rbd encryption format mypool/myclone luks2 clone-passphrase.bin | |
201 | ||
202 | Given a LUKS2-formatted image with the effective size of 50GiB, create | |
203 | a LUKS1-formatted clone with the same effective size: | |
204 | ||
205 | .. prompt:: bash $ | |
206 | ||
207 | rbd snap create mypool/myimage@snap | |
208 | rbd snap protect mypool/myimage@snap | |
209 | rbd clone mypool/myimage@snap mypool/myclone | |
210 | rbd encryption format mypool/myclone luks1 clone-passphrase.bin | |
211 | rbd resize --size 50G --allow-shrink --encryption-passphrase-file clone-passphrase.bin --encryption-passphrase-file passphrase.bin mypool/myclone | |
212 | ||
213 | Since LUKS1 header is usually smaller than LUKS2 header, ``rbd resize`` | |
214 | command at the end shrinks the cloned image to get rid of unneeded | |
215 | space allowance. | |
216 | ||
217 | Given a LUKS1-formatted image with the effective size of 50GiB, create | |
218 | a LUKS2-formatted clone with the same effective size: | |
219 | ||
220 | .. prompt:: bash $ | |
221 | ||
222 | rbd resize --size 51G mypool/myimage | |
223 | rbd snap create mypool/myimage@snap | |
224 | rbd snap protect mypool/myimage@snap | |
225 | rbd clone mypool/myimage@snap mypool/myclone | |
226 | rbd encryption format mypool/myclone luks2 clone-passphrase.bin | |
227 | rbd resize --size 50G --allow-shrink --encryption-passphrase-file passphrase.bin mypool/myimage | |
228 | rbd resize --size 50G --allow-shrink --encryption-passphrase-file clone-passphrase.bin --encryption-passphrase-file passphrase.bin mypool/myclone | |
229 | ||
230 | Since LUKS2 header is usually bigger than LUKS1 header, ``rbd resize`` | |
231 | command at the beginning temporarily grows the parent image to reserve | |
232 | some extra space in the parent snapshot and consequently the cloned | |
233 | image. This is necessary to make all parent data accessible in the | |
234 | cloned image. ``rbd resize`` commands at the end shrink the parent | |
235 | image back to its original size (this does not impact the parent | |
236 | snapshot) and also the cloned image to get rid of unused reserved | |
237 | space. | |
238 | ||
239 | The same applies to creating a formatted clone of an unformatted | |
240 | (plaintext) image since an unformatted image does not have a header at | |
241 | all. | |
242 | ||
f67539c2 TL |
243 | .. _journal feature: ../rbd-mirroring/#enable-image-journaling-feature |
244 | .. _Supported Formats: #supported-formats | |
245 | .. _rbd-nbd: ../../man/8/rbd-nbd | |
1e59de90 | 246 | .. _stripe count: ../../man/8/rbd/#striping |