Debian Codegraph @

manuals/en/main/volume-encryption.tex

raw
1 \label{volumeencryption}
2
3 \section{Storage Daemon Encryption}
4
5
6 When using the Device directive \textbf{Volume Encryption = yes}, the blocks in the
7 volumes are encrypted using the BLOCK\_CIPHER\_AES\_128\_XTS or
8 BLOCK\_CIPHER\_AES\_256\_XTS cipher algorithm. These symmetrical ciphers are
9 fast, and used by most applications that need to perform symmetrical encryption of
10 blocks.
11
12 Every block is encrypted using a *key* that is unique for the volume and an
13 IV (Initialization Vector) - the block number that is saved in the
14 block header. The XTS ciphers are specifically designed to support an IV
15 with a low entropy.
16
17 The first block of the volume that holds the Volume Label is not encrypted
18 because certain fields such as the Volume Name are required to manage the volume and
19 the encryption. A user has an option to obfuscate the fields that are not
20 required which might hold critical information, e.g. hostname.
21 These fields are replaced by the string "OBFUSCATED".
22
23 The header of the block is not encrypted. This 24-byte header does not hold
24 user information. See the content of the header:
25
26 \begin{itemize}
27 \item 32bit header option bit field
28 \item 32bit block length
29 \item 32bit block number
30 \item BB03 string
31 \item 32bit volume session id
32 \item 32bit volume session time.
33 \end{itemize}
34
35 The Volume session time is the time of the Storage Daemon at startup. The
36 Volume session id is reset to zero when the daemon starts and is incremented
37 at every backup by the Storage Daemon.
38
39 The 64bit XXH64 checksum is encrypted with the data. The block must be be
40 decrypted to verify the checksum. If the checksum matches, Bacula uses the
41 right encryption key and the block is not modified. It is currently not
42 possible to verify the integrity of the block without the encryption key.
43
44 If data spooling is enabled, the data in the data spool is not encrypted.
45
46 \textbf{Do not store the data spool on an unsafe storage.}
47
48 \subsection{Storage Daemon Directives}
49
50 There is one new directive in the Storage resource of the Storage Daemon:
51
52 \texttt{Encryption Command = <command>} The command specifies an external
53 program that must provide the keys used to encrypt the volume.
54
55 There is one directive that must be added to all the devices
56 used to encrypt volumes:
57
58
59 \texttt{Volume Encryption = <no|yes|strong>}
60 It allows you to enable the encryption for a given device.
61 The encryption can be of 3 different types:
62
63 \begin{itemize}
64 \item \texttt{no} Default, the device don't do any encryption.
65
66 \item \texttt{yes} The device encrypts the data, but all information in the volume
67 label are left in clear text.
68
69 \item \texttt{strong} The device encrypts the data, and obfuscate any information in
70 the volume label except the one that are needed for the management of the
71 volume. The fields that are obfuscate are: volume name.
72 \end{itemize}
73
74
75 \subsection{Encryption Command}
76
77 The Encryption Command is called by the Storage Daemon every time
78 a new volume is initialized or mounted using a device with encryption enabled.
79 We provide a very simple example script that can be used to manage volume
80 encryption keys.
81
82 Example Encryption Command setting in the Storage Daemon configuration:
83
84 \begin{bVerbatim}
85 Encryption Command = "/opt/bacula/scripts/key-manager.py getkey"
86 \end{bVerbatim}
87
88 The command is limited to 127 characters. The same variable substitutions as
89 the Autochanger Command are available to be passed to the script.
90
91 The program can be an interface with your existing key management system or
92 perform the key management on its own.
93
94 The sample script called \texttt{key-manager.py} may be installed via the
95 bacula-storage-key-manager package. The install-key-manager.sh
96 script is designed to help to setup a master key:
97
98 \begin{bVerbatim}
99 # sudo -u bacula /opt/bacula/scripts/install-key-manager.sh check
100 # sudo -u bacula /opt/bacula/scripts/install-key-manager.sh install
101 \end{bVerbatim}
102
103 Example interaction using the sample key-manager.py script::
104
105 \begin{bVerbatim}
106 $ OPERATION=LABEL VOLUME_NAME=Volume0001 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys
107 cipher: AES_128_XTS
108 cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
109 volume_name: Volume0001
110
111 $ OPERATION=READ VOLUME_NAME=Volume0001 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys
112 cipher: AES_128_XTS
113 cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
114 volume_name: Volume0001
115
116 $ cat /opt/bacula/keys/Volume0001
117 cipher: AES_128_XTS
118 cipher_key: G6HksAYDnNGr67AAx2Lb/vecTVjZoYAqSLZ7lGMyDVE=
119 volume_name: Volume0001
120
121 $ OPERATION=READ VOLUME_NAME=DontExist ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys 2>/dev/null
122 error: no key information for volume "DontExist"
123 $ echo $?
124 0
125
126 $ OPERATION=BAD_CMD VOLUME_NAME=Volume0002 ./key-manager.py getkey --cipher AES_128_XTS --key-dir /opt/bacula/keys 2>/dev/null
127 error: environment variable OPERATION invalid "BAD_CMD" for volume "Volume0002"
128 $ echo $?
129 0
130 \end{bVerbatim}
131
132 In the command above, notice that the keys are kept in one
133 directory /opt/bacula/keys, and the arguments are passed using the environment variables.
134
135 Bacula passes the following variables via the environment:
136
137 \begin{itemize}
138 \item[OPERATION] This is LABEL when the volume is labeled. In this case
139 the script should generate a new key or this can be READ when
140 the volume already has a label and the Storage Daemon needs the already
141 existing key to read or append data to the volume
142
143 \item[VOLUME\_NAME] This is the name of the volume.
144
145 \end{itemize}
146
147 Some variables already exist to support a *Master Key* in the future.
148 This feature is not yet supported, but will come later:
149
150 \begin{itemize}
151 \item[ENC\_CIPHER\_KEY] This is a base64 encoded version of the key encrypted by
152 the master key.
153
154 \item[MASTER\_KEYID] This is a base64 encoded version of the key ID of
155 the master key that was used to encrypt the ENC\_CIPHER\_KEY above.
156 \end{itemize}
157
158 Bacula expects some values in return:
159
160 \begin{itemize}
161 \item[volumename] This is a repetition of the name of the volume that is
162 given to the script. This field is optional and ignored by Bacula.
163
164 \item [cipher] This is the cipher that Bacula must use.
165 Bacula knows the following ciphers: AES\_128\_XTS and AES\_256\_XTS.
166 Of course, the key lengths varies depending on the cipher used.
167
168 \item [cipher\_key] This is a symmetric key in base 64 format.
169
170 \item [comment] This is a single line of text that is optional and ignored by Bacula.
171
172 \item [error] This is a single line error message.
173 This is optional, but when provided, Bacula considers that the script
174 returned an error and displays this error in the job log.
175 \end{itemize}
176
177 Bacula expects an exit code of 0. If the script exits with a different
178 error code, any output is ignored and Bacula displays a generic message
179 with the exit code in the job log.
180
181 To return an error to Bacula, the script must use the *error* field
182 and return an error code of 0.
183
184
185 \subsection{Compatibility between Volumes Using the BB02 and BB03 Formats}
186
187 Any volume initialized using Bacula version 13.0 or prior versions can be read and appended in version 15 and above.
188 Volumes that have been initialized or simply appended using version 15.0 and after cannot be read with version 13.0 or prior versions.
189
190
191 \subsection{Interoperability between Encrypted and Unencrypted Volumes}
192
193 The volume has a flag in the header of the first block which indicated whether the volume is encrypted or not.
194 The field VolEncrypted in the Catalog reflects this state. Bacula does not mix encrypted and unencrypted data inside a volume.
195
196 Volumes that have been labeled or re-labeled on a Device with the directive VolumeEncryption are
197 encrypted volumes. Other volumes, including volumes which have been initialized
198 with a BB02 format using version 13.0 or older, are seen as unencrypted volumes.
199
200 You can change the value of the directive VolumeEncryption to Yes or Strong at any time.
201 Volumes that are not encrypted can be read on this device but cannot be appended until they are recycled.
202 Switching between Yes and Strong is fine, because the difference is only in the unencrypted label
203 and not in the blocks that come after the label.
204
205 Changing the value of the directive back to No will deactivate the encryption
206 and make all encrypted volumes unreadable and useless on this device until they are recycled.
207
208
209 \subsection{Using a Master Key}
210
211 Bacula uses symmetric keys to encrypt the volumes.
212 This means that the same key is used to encrypt and also to decrypt the volume content.
213 To improve security, each volume is expected to be encrypted using a different key.
214 The task of the key manager is to provide these keys to the Storage Daemon.
215 When needed, these keys must be generated for a new volume or when the volume is recycled.
216 This can result in a large amount of key files to handle, which must also be backed up or kept in a safe place.
217
218 The master key is implemented using a public/private key pair.
219 The public key is kept on the Storage Daemon to generate the encrypted version of the
220 symmetric keys while the private key may be kept somewhere else.
221
222 The master key is designed to provide two advantages:
223
224 \begin{itemize}
225 \item To be able to decrypt multiple volumes using one, or a set of master keys
226 \item When the **stealth** mode is used, the symmetric key is never stored on disk,
227 which makes any restore impossible without the private key.
228 If your server is hacked or stolen, nobody is able to restore your data.
229 \end{itemize}
230
231 \subsection{How the Master Key Is Implemented}
232
233 The master key is implemented using a public/private key pair.
234 The public key is stored on the Storage Daemon and is
235 used to encrypt the automatically generated symmetrical keys.
236 The private key does not need to be stored on the Storage Daemon to run backups.
237
238 The encrypted key and a unique identifier for the master key
239 are stored into the label of the volume.
240 At restore time, these two pieces of information, and the volume name are
241 provided to the key manager that must provide the correct symmetrical key.
242
243 There are a few scenarios to consider:
244
245 \begin{itemize}
246 \item You don't use the stealth mode, and the key-manager can use the
247 passphrase of the private key that you have provided in the
248 configuration file to decrypt the symmetrical key coming from the
249 volume *or use the clear version of the symmetrical key stored locally.
250
251 \item You use the stealth mode, and the key-manager asks GnuPG
252 to decrypt the symmetrical key coming from the volume.
253 There are two possibilities here:
254
255 \item The passphrase of the private key has been preset, or is still in
256 the cache of the *gpg* agent and *gpg* can decrypt the symmetrical key
257
258 \item Bacula waits until the user provides the passphrase
259 \end{itemize}
260
261 The key-manager provided with Bacula uses GnuPG to manage the
262 public/private key.
263
264 \subsection{Format of the key-manager.conf File}
265
266 When using the master key feature, you can set up your master keys
267 in the key-manager.conf file that is stored in /opt/bacula/etc.
268 This file is automatically populated with one master-key at installation time.
269 This file is not required if you don't use a master-key.
270
271 \begin{bVerbatim}
272
273 [default]
274 gnupghome="/opt/bacula/etc/gnupg"
275
276 [0378FB9C839FF9F207834D89DB856A1A513B7AB4]
277 #volume_regex=Volume[0-9]+|TestVolume[0-9]+
278 uid=bacula@localhost
279 passphrase=xm3ynBi7MfHTUovls4QV8OtBT5rfAnXwT8Wb7wjVRyCT
280 stealth=off
281
282 \end{bVerbatim}
283
284 The supported fields are:
285
286 \begin{itemize}
287 \item [gnupghome] This is where GnuPG stores your keys
288 \item [volume\_regrex] A regex that is used by the key manager to
289 know if this master key must be used with one volume
290 \item [uid] The uid helps you to identify the key
291 \item [passphrase] This is the passphrase of the key
292 \item [stealth] When stealth is used, the key manager does not store
293 the symmetrical keys in the KEYDIR directory.
294 \end{itemize}
295
296 The default gnupghome directory is in /opt/bacula/etc/gnupg.
297 When using GnuPG, you must use the --homedir option like: \texttt{--homedir /opt/bacula/etc/gnupg},
298 or set the GNUPGHOME environment variable::
299
300 \begin{bVerbatim}
301 export GNUPGHOME="/opt/bacula/etc/gnupg"
302 \end{bVerbatim}
303
304 You must define a section for every master key you want to use.
305 The name of the section is the Key-ID of your public/private key.
306 You can get the Key-ID when listing your keys::
307
308 \begin{bVerbatim}
309 bacula $ GNUPGHOME=/opt/bacula/etc/gnupg gpg -k
310 /opt/bacula/etc/gnupg/pubring.kbx
311 -----------------------------------------------------
312 pub rsa3072 2023-01-11 [SC]
313 0378FB9C839FF9F207834D89DB856A1A513B7AB4
314 uid [ultimate] Bacula <bacula@localhost>
315 sub rsa3072 2023-01-11 [E]
316 \end{bVerbatim}
317
318 Notice that the public key has a sub key that allows encryption.
319 This is the [E] in the last line. If your public/private key does not
320 own such a key, you cannot use it with the key manager.
321
322 The volume\_regex are checked sequentially. The first regex
323 that matches the volume name submitted to the key manager will
324 be used even if another volume\_regex matches the name of the volume.
325 By default the volume\_regex is commented out to not activate the
326 master key feature.
327
328 The uid is only informative, and is not used by the key manager.
329
330 When stealth is set to \texttt{on} the key manager does not keep the
331 symmetrical keys in clear text in the KEYDIR directory.
332 When \texttt{on}, you must also not specify a passphrase.
333
334 When the passphrase of the public/private key is not set,
335 but required by the key manager, it relies on the gpg-agent
336 to provide the key.
337
338 \subsection{Backup Your Keys}
339
340 In case of losing your symmetrical keys and/or your master key(s), your data is not recoverable.
341 Therefore, it is important to backup your keys.
342
343 Your symmetrical keys are stored in the /opt/bacula/etc/keydir
344 directory by default. This directory may be modified with the
345 --key-dir option in the command line that is configured
346 with the Encryption Command directive defined above.
347 This directory must be backed up regularly.
348
349 Your master keys are stored in the /opt/bacula/etc/gnupg
350 directory by default. This directory is defined in the
351 key manager configuration file (by default /opt/bacula/etc/key-manager.conf)
352 in the [default] section under the gnupghome directive as
353 seen above. The key-manager.conf file can be relocated with the
354 --config option in the command defined in Encryption Command
355 directive defined above. The default passphrase is stored in
356 the key-manager.conf. You just need to backup the key-manager.conf*
357 file, and the /opt/bacula/etc/gnupg directory.
358
359 You can export your default private key using the command::
360
361 \begin{bVerbatim}
362 # gpg --homedir /opt/bacula/etc/gnupg --output private.pgp --armor --export-secret-key bacula@localhost
363 \end{bVerbatim}
364
365 It asks you for the passphrase that is saved in you key-manager.conf file.
366 This exports an ASCII armored version of your private key
367 into the file private.pgp. You can print it and/or save it on USB drive or elsewhere.
368
369
370 \subsection{What Is Encrypted and What Is Not}
371
372 The main goal of encryption is to prevent outsiders without the volume key to
373 read the volume's data. Bacula does this well, but encryption alone cannot
374 protect against volume modifications.
375
376 The first block of the volume is the volume label and it is not encrypted.
377 Some information is required for the management of the volume itself.
378 The only data in the volume label coming from the user are: the hostname,
379 volumename, poolname. The hostname can be obfuscated using
380 the STRONG mode of encryption, the poolname and the volumename
381 could be made useless to an attacker by using a generic name like PoolAlpha or
382 Volume12345.
383
384 Data in your catalog database, for example the directories, filenames, and
385 the JobLog are not encrypted.
386
387 An attacker can also make some undetected modifications to the volumes.
388 The easiest way is to remove one block inside the volume.
389 Other verifications inside Bacula could detect such a modification and
390 the attacker must be meticulous, but it is a possibility.
391
392 The XXH64 checksum inside each volume is encrypted using the encryption key.
393 This is not as strong as using a certified signature, but it provides
394 substantial confidence that the block cannot be modified easily.
395
396 To summarize, with volume encryption enabled, you can be confident that:
397
398 \begin{itemize}
399 \item An attacker can not read any of your data: Very Strong.
400 \item An attacker can not substitute the volume with another one: Strong.
401 \item An attacker can not modify the contents of the volume: Good.
402 \end{itemize}