]> CyberLeo.Net >> Repos - FreeBSD/releng/10.0.git/blob - sbin/geom/class/eli/geli.8
- Copy stable/10 (r259064) to releng/10.0 as part of the
[FreeBSD/releng/10.0.git] / sbin / geom / class / eli / geli.8
1 .\" Copyright (c) 2005-2011 Pawel Jakub Dawidek <pawel@dawidek.net>
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD$
26 .\"
27 .Dd October 1, 2013
28 .Dt GELI 8
29 .Os
30 .Sh NAME
31 .Nm geli
32 .Nd "control utility for the cryptographic GEOM class"
33 .Sh SYNOPSIS
34 To compile GEOM_ELI into your kernel, add the following lines to your kernel
35 configuration file:
36 .Bd -ragged -offset indent
37 .Cd "device crypto"
38 .Cd "options GEOM_ELI"
39 .Ed
40 .Pp
41 Alternatively, to load the GEOM_ELI module at boot time, add the following line
42 to your
43 .Xr loader.conf 5 :
44 .Bd -literal -offset indent
45 geom_eli_load="YES"
46 .Ed
47 .Pp
48 Usage of the
49 .Nm
50 utility:
51 .Pp
52 .Nm
53 .Cm init
54 .Op Fl bPv
55 .Op Fl a Ar aalgo
56 .Op Fl B Ar backupfile
57 .Op Fl e Ar ealgo
58 .Op Fl i Ar iterations
59 .Op Fl J Ar newpassfile
60 .Op Fl K Ar newkeyfile
61 .Op Fl l Ar keylen
62 .Op Fl s Ar sectorsize
63 .Op Fl V Ar version
64 .Ar prov
65 .Nm
66 .Cm label - an alias for
67 .Cm init
68 .Nm
69 .Cm attach
70 .Op Fl dprv
71 .Op Fl j Ar passfile
72 .Op Fl k Ar keyfile
73 .Ar prov
74 .Nm
75 .Cm detach
76 .Op Fl fl
77 .Ar prov ...
78 .Nm
79 .Cm stop - an alias for
80 .Cm detach
81 .Nm
82 .Cm onetime
83 .Op Fl d
84 .Op Fl a Ar aalgo
85 .Op Fl e Ar ealgo
86 .Op Fl l Ar keylen
87 .Op Fl s Ar sectorsize
88 .Ar prov
89 .Nm
90 .Cm configure
91 .Op Fl bB
92 .Ar prov ...
93 .Nm
94 .Cm setkey
95 .Op Fl pPv
96 .Op Fl i Ar iterations
97 .Op Fl j Ar passfile
98 .Op Fl J Ar newpassfile
99 .Op Fl k Ar keyfile
100 .Op Fl K Ar newkeyfile
101 .Op Fl n Ar keyno
102 .Ar prov
103 .Nm
104 .Cm delkey
105 .Op Fl afv
106 .Op Fl n Ar keyno
107 .Ar prov
108 .Nm
109 .Cm kill
110 .Op Fl av
111 .Op Ar prov ...
112 .Nm
113 .Cm backup
114 .Op Fl v
115 .Ar prov
116 .Ar file
117 .Nm
118 .Cm restore
119 .Op Fl fv
120 .Ar file
121 .Ar prov
122 .Nm
123 .Cm suspend
124 .Op Fl v
125 .Fl a | Ar prov ...
126 .Nm
127 .Cm resume
128 .Op Fl pv
129 .Op Fl j Ar passfile
130 .Op Fl k Ar keyfile
131 .Ar prov
132 .Nm
133 .Cm resize
134 .Op Fl v
135 .Fl s Ar oldsize
136 .Ar prov
137 .Nm
138 .Cm version
139 .Op Ar prov ...
140 .Nm
141 .Cm clear
142 .Op Fl v
143 .Ar prov ...
144 .Nm
145 .Cm dump
146 .Op Fl v
147 .Ar prov ...
148 .Nm
149 .Cm list
150 .Nm
151 .Cm status
152 .Nm
153 .Cm load
154 .Nm
155 .Cm unload
156 .Sh DESCRIPTION
157 The
158 .Nm
159 utility is used to configure encryption on GEOM providers.
160 .Pp
161 The following is a list of the most important features:
162 .Pp
163 .Bl -bullet -offset indent -compact
164 .It
165 Utilizes the
166 .Xr crypto 9
167 framework, so when there is crypto hardware available,
168 .Nm
169 will make use of it automatically.
170 .It
171 Supports many cryptographic algorithms (currently
172 .Nm AES-XTS ,
173 .Nm AES-CBC ,
174 .Nm Blowfish-CBC ,
175 .Nm Camellia-CBC
176 and
177 .Nm 3DES-CBC ) .
178 .It
179 Can optionally perform data authentication (integrity verification) utilizing
180 one of the following algorithms:
181 .Nm HMAC/MD5 ,
182 .Nm HMAC/SHA1 ,
183 .Nm HMAC/RIPEMD160 ,
184 .Nm HMAC/SHA256 ,
185 .Nm HMAC/SHA384
186 or
187 .Nm HMAC/SHA512 .
188 .It
189 Can create a User Key from up to two, piecewise components: a passphrase
190 entered via prompt or read from one or more passfiles; a keyfile read from
191 one or more files.
192 .It
193 Allows encryption of the root partition.
194 The user will be asked for the
195 passphrase before the root file system is mounted.
196 .It
197 Strengthens the passphrase component of the User Key with:
198 .Rs
199 .%A B. Kaliski
200 .%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
201 .%R RFC
202 .%N 2898
203 .Re
204 .It
205 Allows the use of two independent User Keys (e.g., a
206 .Qq "user key"
207 and a
208 .Qq "company key" ) .
209 .It
210 It is fast -
211 .Nm
212 performs simple sector-to-sector encryption.
213 .It
214 Allows the encrypted Master Key to be backed up and restored,
215 so that if a user has to quickly destroy key material,
216 it is possible to get the data back by restoring keys from
217 backup.
218 .It
219 Providers can be configured to automatically detach on last close
220 (so users do not have to remember to detach providers after unmounting
221 the file systems).
222 .It
223 Allows attaching a provider with a random, one-time Master Key -
224 useful for swap partitions and temporary file systems.
225 .It
226 Allows verification of data integrity (data authentication).
227 .It
228 Allows suspending and resuming encrypted devices.
229 .El
230 .Pp
231 The first argument to
232 .Nm
233 indicates an action to be performed:
234 .Bl -tag -width ".Cm configure"
235 .It Cm init
236 Initialize the provider which needs to be encrypted.
237 Here you can set up the cryptographic algorithm to use, Data Key length,
238 etc.
239 The last sector of the provider is used to store metadata.
240 The
241 .Cm init
242 subcommand also automatically writes metadata backups to
243 .Pa /var/backups/<prov>.eli
244 file.
245 The metadata can be recovered with the
246 .Cm restore
247 subcommand described below.
248 .Pp
249 Additional options include:
250 .Bl -tag -width ".Fl J Ar newpassfile"
251 .It Fl a Ar aalgo
252 Enable data integrity verification (authentication) using the given algorithm.
253 This will reduce the size of storage available and also reduce speed.
254 For example, when using 4096 bytes sector and
255 .Nm HMAC/SHA256
256 algorithm, 89% of the original provider storage will be available for use.
257 Currently supported algorithms are:
258 .Nm HMAC/MD5 ,
259 .Nm HMAC/SHA1 ,
260 .Nm HMAC/RIPEMD160 ,
261 .Nm HMAC/SHA256 ,
262 .Nm HMAC/SHA384
263 and
264 .Nm HMAC/SHA512 .
265 If the option is not given, there will be no authentication, only encryption.
266 The recommended algorithm is
267 .Nm HMAC/SHA256 .
268 .It Fl b
269 Ask for the passphrase on boot, before the root partition is mounted.
270 This makes it possible to use an encrypted root partition.
271 One will still need bootable unencrypted storage with a
272 .Pa /boot/
273 directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
274 after boot.
275 .It Fl B Ar backupfile
276 File name to use for metadata backup instead of the default
277 .Pa /var/backups/<prov>.eli .
278 To inhibit backups, you can use
279 .Pa none
280 as the
281 .Ar backupfile .
282 .It Fl e Ar ealgo
283 Encryption algorithm to use.
284 Currently supported algorithms are:
285 .Nm AES-XTS ,
286 .Nm AES-CBC ,
287 .Nm Blowfish-CBC ,
288 .Nm Camellia-CBC ,
289 .Nm 3DES-CBC ,
290 and
291 .Nm NULL .
292 The default and recommended algorithm is
293 .Nm AES-XTS .
294 .Nm NULL
295 is unencrypted.
296 .It Fl i Ar iterations
297 Number of iterations to use with PKCS#5v2 when processing User Key
298 passphrase component.
299 If this option is not specified,
300 .Nm
301 will find the number of iterations which is equal to 2 seconds of crypto work.
302 If 0 is given, PKCS#5v2 will not be used.
303 PKCS#5v2 processing is performed once, after all parts of the passphrase
304 component have been read.
305 .It Fl J Ar newpassfile
306 Specifies a file which contains the passphrase component of the User Key
307 (or part of it).
308 If
309 .Ar newpassfile
310 is given as -, standard input will be used.
311 Only the first line (excluding new-line character) is taken from the given file.
312 This argument can be specified multiple times, which has the effect of
313 reassembling a single passphrase split across multiple files.
314 Cannot be combined with the
315 .Fl P
316 option.
317 .It Fl K Ar newkeyfile
318 Specifies a file which contains the keyfile component of the User Key
319 (or part of it).
320 If
321 .Ar newkeyfile
322 is given as -, standard input will be used.
323 This argument can be specified multiple times, which has the effect of
324 reassembling a single keyfile split across multiple keyfile parts.
325 .It Fl l Ar keylen
326 Data Key length to use with the given cryptographic algorithm.
327 If the length is not specified, the selected algorithm uses its
328 .Em default
329 key length.
330 .Bl -ohang -offset indent
331 .It Nm AES-XTS
332 .Em 128 ,
333 256
334 .It Nm AES-CBC , Nm Camilla-CBC
335 .Em 128 ,
336 192,
337 256
338 .It Nm Blowfish-CBC
339 .Em 128
340 + n * 32, for n=[0..10]
341 .It Nm 3DES-CBC
342 .Em 192
343 .El
344 .It Fl P
345 Do not use a passphrase as a component of the User Key.
346 Cannot be combined with the
347 .Fl J
348 option.
349 .It Fl s Ar sectorsize
350 Change decrypted provider's sector size.
351 Increasing the sector size allows increased performance,
352 because encryption/decryption which requires an initialization vector
353 is done per sector; fewer sectors means less computational work.
354 .It Fl V Ar version
355 Metadata version to use.
356 This option is helpful when creating provider that may be used by older
357 .Nm FreeBSD/GELI
358 versions.
359 Consult the
360 .Sx HISTORY
361 section to find which metadata version is supported by which FreeBSD version.
362 Note that using older metadata version may limit numer of features available.
363 .El
364 .It Cm attach
365 Attach the given provider.
366 The encrypted Master Key will be loaded from the metadata and decrypted
367 using the given passphrase/keyfile and a new GEOM provider will be created
368 using the given provider's name with an
369 .Qq .eli
370 suffix.
371 .Pp
372 Additional options include:
373 .Bl -tag -width ".Fl j Ar passfile"
374 .It Fl d
375 If specified, a decrypted provider will be detached automatically on last close.
376 This can help with scarce memory so the user does not have to remember to detach the
377 provider after unmounting the file system.
378 It only works when the provider was opened for writing, so it will not work if
379 the file system on the provider is mounted read-only.
380 Probably a better choice is the
381 .Fl l
382 option for the
383 .Cm detach
384 subcommand.
385 .It Fl j Ar passfile
386 Specifies a file which contains the passphrase component of the User Key
387 (or part of it).
388 For more information see the description of the
389 .Fl J
390 option for the
391 .Cm init
392 subcommand.
393 .It Fl k Ar keyfile
394 Specifies a file which contains the keyfile component of the User Key
395 (or part of it).
396 For more information see the description of the
397 .Fl K
398 option for the
399 .Cm init
400 subcommand.
401 .It Fl p
402 Do not use a passphrase as a component of the User Key.
403 Cannot be combined with the
404 .Fl j
405 option.
406 .It Fl r
407 Attach read-only provider.
408 It will not be opened for writing.
409 .El
410 .It Cm detach
411 Detach the given providers, which means remove the devfs entry
412 and clear the Master Key and Data Keys from memory.
413 .Pp
414 Additional options include:
415 .Bl -tag -width ".Fl f"
416 .It Fl f
417 Force detach - detach even if the provider is open.
418 .It Fl l
419 Mark provider to detach on last close.
420 If this option is specified, the provider will not be detached
421 while it is open, but will be automatically detached when it is closed for the
422 last time even if it was only opened for reading.
423 .El
424 .It Cm onetime
425 Attach the given providers with a random, one-time (ephemeral) Master Key.
426 The command can be used to encrypt swap partitions or temporary file systems.
427 .Pp
428 Additional options include:
429 .Bl -tag -width ".Fl a Ar sectorsize"
430 .It Fl a Ar aalgo
431 Enable data integrity verification (authentication).
432 For more information, see the description of the
433 .Cm init
434 subcommand.
435 .It Fl e Ar ealgo
436 Encryption algorithm to use.
437 For more information, see the description of the
438 .Cm init
439 subcommand.
440 .It Fl d
441 Detach on last close.
442 Note: this option is not usable for temporary file systems as the provider will
443 be detached after creating the file system on it.
444 It still can (and should be) used for swap partitions.
445 For more information, see the description of the
446 .Cm attach
447 subcommand.
448 .It Fl l Ar keylen
449 Data Key length to use with the given cryptographic algorithm.
450 For more information, see the description of the
451 .Cm init
452 subcommand.
453 .It Fl s Ar sectorsize
454 Change decrypted provider's sector size.
455 For more information, see the description of the
456 .Cm init
457 subcommand.
458 .El
459 .It Cm configure
460 Change configuration of the given providers.
461 .Pp
462 Additional options include:
463 .Bl -tag -width ".Fl b"
464 .It Fl b
465 Set the BOOT flag on the given providers.
466 For more information, see the description of the
467 .Cm init
468 subcommand.
469 .It Fl B
470 Remove the BOOT flag from the given providers.
471 .El
472 .It Cm setkey
473 Install a copy of the Master Key into the selected slot, encrypted with
474 a new User Key.
475 If the selected slot is populated, replace the existing copy.
476 A provider has one Master Key, which can be stored in one or both slots,
477 each encrypted with an independent User Key.
478 With the
479 .Cm init
480 subcommand, only key number 0 is initialized.
481 The User Key can be changed at any time: for an attached provider,
482 for a detached provider, or on the backup file.
483 When a provider is attached, the user does not have to provide
484 an existing passphrase/keyfile.
485 .Pp
486 Additional options include:
487 .Bl -tag -width ".Fl J Ar newpassfile"
488 .It Fl i Ar iterations
489 Number of iterations to use with PKCS#5v2.
490 If 0 is given, PKCS#5v2 will not be used.
491 To be able to use this option with the
492 .Cm setkey
493 subcommand, only one key has to be defined and this key must be changed.
494 .It Fl j Ar passfile
495 Specifies a file which contains the passphrase component of a current User Key
496 (or part of it).
497 .It Fl J Ar newpassfile
498 Specifies a file which contains the passphrase component of the new User Key
499 (or part of it).
500 .It Fl k Ar keyfile
501 Specifies a file which contains the keyfile component of a current User Key
502 (or part of it).
503 .It Fl K Ar newkeyfile
504 Specifies a file which contains the keyfile component of the new User Key
505 (or part of it).
506 .It Fl n Ar keyno
507 Specifies the index number of the Master Key copy to change (could be 0 or 1).
508 If the provider is attached and no key number is given, the key
509 used for attaching the provider will be changed.
510 If the provider is detached (or we are operating on a backup file)
511 and no key number is given, the first Master Key copy to be successfully
512 decrypted with the provided User Key passphrase/keyfile will be changed.
513 .It Fl p
514 Do not use a passphrase as a component of the current User Key.
515 Cannot be combined with the
516 .Fl j
517 option.
518 .It Fl P
519 Do not use a passphrase as a component of the new User Key.
520 Cannot be combined with the
521 .Fl J
522 option.
523 .El
524 .It Cm delkey
525 Destroy (overwrite with random data) the selected Master Key copy.
526 If one is destroying keys for an attached provider, the provider
527 will not be detached even if all copies of the Master Key are destroyed.
528 It can even be rescued with the
529 .Cm setkey
530 subcommand because the Master Key is still in memory.
531 .Pp
532 Additional options include:
533 .Bl -tag -width ".Fl a Ar keyno"
534 .It Fl a
535 Destroy all copies of the Master Key (does not need
536 .Fl f
537 option).
538 .It Fl f
539 Force key destruction.
540 This option is needed to destroy the last copy of the Master Key.
541 .It Fl n Ar keyno
542 Specifies the index number of the Master Key copy.
543 If the provider is attached and no key number is given, the key
544 used for attaching the provider will be destroyed.
545 If provider is detached (or we are operating on a backup file) the key number
546 has to be given.
547 .El
548 .It Cm kill
549 This command should be used only in emergency situations.
550 It will destroy all copies of the Master Key on a given provider and will
551 detach it forcibly (if it is attached).
552 This is absolutely a one-way command - if you do not have a metadata
553 backup, your data is gone for good.
554 In case the provider was attached with the
555 .Fl r
556 flag, the keys will not be destroyed, only the provider will be detached.
557 .Pp
558 Additional options include:
559 .Bl -tag -width ".Fl a"
560 .It Fl a
561 If specified, all currently attached providers will be killed.
562 .El
563 .It Cm backup
564 Backup metadata from the given provider to the given file.
565 .It Cm restore
566 Restore metadata from the given file to the given provider.
567 .Pp
568 Additional options include:
569 .Bl -tag -width ".Fl f"
570 .It Fl f
571 Metadata contains the size of the provider to ensure that the correct
572 partition or slice is attached.
573 If an attempt is made to restore metadata to a provider that has a different
574 size,
575 .Nm
576 will refuse to restore the data unless the
577 .Fl f
578 switch is used.
579 If the partition or slice has been grown, the
580 .Cm resize
581 subcommand should be used rather than attempting to relocate the metadata
582 through
583 .Cm backup
584 and
585 .Cm restore .
586 .El
587 .It Cm suspend
588 Suspend device by waiting for all inflight requests to finish, clearing all
589 sensitive information (like the Master Key and Data Keys) from kernel memory,
590 and blocking all further I/O requests until the
591 .Cm resume
592 subcommand is executed.
593 This functionality is useful for laptops: when one wants to suspend a
594 laptop, one does not want to leave an encrypted device attached.
595 Instead of closing all files and directories opened from a file system located
596 on an encrypted device, unmounting the file system, and detaching the device,
597 the
598 .Cm suspend
599 subcommand can be used.
600 Any access to the encrypted device will be blocked until the Master Key is
601 reloaded through the
602 .Cm resume
603 subcommand.
604 Thus there is no need to close nor unmount anything.
605 The
606 .Cm suspend
607 subcommand does not work with devices created with the
608 .Cm onetime
609 subcommand.
610 Please note that sensitive data might still be present in memory after
611 suspending an encrypted device due to the file system cache, etc.
612 .Pp
613 Additional options include:
614 .Bl -tag -width ".Fl a"
615 .It Fl a
616 Suspend all
617 .Nm
618 devices.
619 .El
620 .It Cm resume
621 Resume previously suspended device.
622 The caller must ensure that executing this subcommand doesn't access the
623 suspended device, leading to a deadlock.
624 For example suspending a device which contains the file system where the
625 .Nm
626 utility is stored is bad idea.
627 .Pp
628 Additional options include:
629 .Bl -tag -width ".Fl j Ar passfile"
630 .It Fl j Ar passfile
631 Specifies a file which contains the passphrase component of the User Key
632 (or part of it).
633 For more information see the description of the
634 .Fl J
635 option for the
636 .Cm init
637 subcommand.
638 .It Fl k Ar keyfile
639 Specifies a file which contains the keyfile component of the User Key
640 (or part of it).
641 For more information see the description of the
642 .Fl K
643 option for the
644 .Cm init
645 subcommand.
646 .It Fl p
647 Do not use a passphrase as a component of the User Key.
648 Cannot be combined with the
649 .Fl j
650 option.
651 .El
652 .It Cm resize
653 Inform
654 .Nm
655 that the provider has been resized.
656 The old metadata block is relocated to the correct position at the end of the
657 provider and the provider size is updated.
658 .Pp
659 Additional options include:
660 .Bl -tag -width ".Fl s Ar oldsize"
661 .It Fl s Ar oldsize
662 The size of the provider before it was resized.
663 .El
664 .It Cm version
665 If no arguments are given, the
666 .Cm version
667 subcommand will print the version of
668 .Nm
669 userland utility as well as the version of the
670 .Nm ELI
671 GEOM class.
672 .Pp
673 If GEOM providers are specified, the
674 .Cm version
675 subcommand will print metadata version used by each of them.
676 .It Cm clear
677 Clear metadata from the given providers.
678 .Em WARNING :
679 This will erase with zeros the encrypted Master Key copies stored in the
680 metadata.
681 .It Cm dump
682 Dump metadata stored on the given providers.
683 .It Cm list
684 See
685 .Xr geom 8 .
686 .It Cm status
687 See
688 .Xr geom 8 .
689 .It Cm load
690 See
691 .Xr geom 8 .
692 .It Cm unload
693 See
694 .Xr geom 8 .
695 .El
696 .Pp
697 Additional options include:
698 .Bl -tag -width ".Fl v"
699 .It Fl v
700 Be more verbose.
701 .El
702 .Sh KEY SUMMARY
703 .Ss Master Key
704 Upon
705 .Cm init ,
706 the
707 .Nm
708 utility generates a random Master Key for the provider.
709 The Master Key never changes during the lifetime of the provider.
710 Each copy of the provider metadata, active or backed up to a file, can store
711 up to two, independently-encrypted copies of the Master Key.
712 .Ss User Key
713 Each stored copy of the Master Key is encrypted with a User Key, which
714 is generated by the
715 .Nm
716 utility from a passphrase and/or a keyfile.
717 The
718 .Nm
719 utility first reads all parts of the keyfile in the order specified on the
720 command line, then reads all parts of the stored passphrase in the order
721 specified on the command line.
722 If no passphrase parts are specified, the system prompts the user to enter
723 the passphrase.
724 The passphrase is optionally strengthened by PKCS#5v2.
725 The User Key is a digest computed over the concatenated keyfile and passphrase.
726 .Ss Data Key
727 During operation, one or more Data Keys are deterministically derived by
728 the kernel from the Master Key and cached in memory.
729 The number of Data Keys used by a given provider, and the way they are
730 derived, depend on the GELI version and whether the provider is configured to
731 use data authentication.
732 .Sh SYSCTL VARIABLES
733 The following
734 .Xr sysctl 8
735 variables can be used to control the behavior of the
736 .Nm ELI
737 GEOM class.
738 The default value is shown next to each variable.
739 Some variables can also be set in
740 .Pa /boot/loader.conf .
741 .Bl -tag -width indent
742 .It Va kern.geom.eli.version
743 Version number of the
744 .Nm ELI
745 GEOM class.
746 .It Va kern.geom.eli.debug : No 0
747 Debug level of the
748 .Nm ELI
749 GEOM class.
750 This can be set to a number between 0 and 3 inclusive.
751 If set to 0, minimal debug information is printed.
752 If set to 3, the
753 maximum amount of debug information is printed.
754 .It Va kern.geom.eli.tries : No 3
755 Number of times a user is asked for the passphrase.
756 This is only used for providers which are attached on boot
757 (before the root file system is mounted).
758 If set to 0, attaching providers on boot will be disabled.
759 This variable should be set in
760 .Pa /boot/loader.conf .
761 .It Va kern.geom.eli.overwrites : No 5
762 Specifies how many times the Master Key will be overwritten
763 with random values when it is destroyed.
764 After this operation it is filled with zeros.
765 .It Va kern.geom.eli.visible_passphrase : No 0
766 If set to 1, the passphrase entered on boot (before the root
767 file system is mounted) will be visible.
768 This alternative should be used with caution as the entered
769 passphrase can be logged and exposed via
770 .Xr dmesg 8 .
771 This variable should be set in
772 .Pa /boot/loader.conf .
773 .It Va kern.geom.eli.threads : No 0
774 Specifies how many kernel threads should be used for doing software
775 cryptography.
776 Its purpose is to increase performance on SMP systems.
777 If set to 0, a CPU-pinned thread will be started for every active CPU.
778 .It Va kern.geom.eli.batch : No 0
779 When set to 1, can speed-up crypto operations by using batching.
780 Batching reduces the number of interrupts by responding to a group of
781 crypto requests with one interrupt.
782 The crypto card and the driver has to support this feature.
783 .It Va kern.geom.eli.key_cache_limit : No 8192
784 Specifies how many Data Keys to cache.
785 The default limit
786 (8192 keys) will allow caching of all keys for a 4TB provider with 512 byte
787 sectors and will take around 1MB of memory.
788 .It Va kern.geom.eli.key_cache_hits
789 Reports how many times we were looking up a Data Key and it was already in
790 cache.
791 This sysctl is not updated for providers that need fewer Data Keys than
792 the limit specified in
793 .Va kern.geom.eli.key_cache_limit .
794 .It Va kern.geom.eli.key_cache_misses
795 Reports how many times we were looking up a Data Key and it was not in cache.
796 This sysctl is not updated for providers that need fewer Data Keys than the limit
797 specified in
798 .Va kern.geom.eli.key_cache_limit .
799 .El
800 .Sh EXIT STATUS
801 Exit status is 0 on success, and 1 if the command fails.
802 .Sh EXAMPLES
803 Initialize a provider which is going to be encrypted with a
804 passphrase and random data from a file on the user's pen drive.
805 Use 4kB sector size.
806 Attach the provider, create a file system, and mount it.
807 Do the work.
808 Unmount the provider and detach it:
809 .Bd -literal -offset indent
810 # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
811 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
812 Enter new passphrase:
813 Reenter new passphrase:
814 # geli attach -k /mnt/pendrive/da2.key /dev/da2
815 Enter passphrase:
816 # dd if=/dev/random of=/dev/da2.eli bs=1m
817 # newfs /dev/da2.eli
818 # mount /dev/da2.eli /mnt/secret
819 \&...
820 # umount /mnt/secret
821 # geli detach da2.eli
822 .Ed
823 .Pp
824 Create an encrypted provider, but use two User Keys:
825 one for your employee and one for you as the company's security officer
826 (so it's not a tragedy if the employee
827 .Qq accidentally
828 forgets his passphrase):
829 .Bd -literal -offset indent
830 # geli init /dev/da2
831 Enter new passphrase:   (enter security officer's passphrase)
832 Reenter new passphrase:
833 # geli setkey -n 1 /dev/da2
834 Enter passphrase:       (enter security officer's passphrase)
835 Enter new passphrase:   (let your employee enter his passphrase ...)
836 Reenter new passphrase: (... twice)
837 .Ed
838 .Pp
839 You are the security officer in your company.
840 Create an encrypted provider for use by the user, but remember that users
841 forget their passphrases, so backup the Master Key with your own random key:
842 .Bd -literal -offset indent
843 # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
844 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e
845 # geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname`
846 (use key number 0, so the encrypted Master Key will be re-encrypted by this)
847 # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e
848 (allow the user to enter his passphrase)
849 Enter new passphrase:
850 Reenter new passphrase:
851 .Ed
852 .Pp
853 Encrypted swap partition setup:
854 .Bd -literal -offset indent
855 # dd if=/dev/random of=/dev/ada0s1b bs=1m
856 # geli onetime -d -e 3des ada0s1b
857 # swapon /dev/ada0s1b.eli
858 .Ed
859 .Pp
860 The example below shows how to configure two providers which will be attached
861 on boot (before the root file system is mounted).
862 One of them is using passphrase and three keyfile parts and the other is
863 using only a keyfile in one part:
864 .Bd -literal -offset indent
865 # dd if=/dev/random of=/dev/da0 bs=1m
866 # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
867 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
868 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
869 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
870 Enter new passphrase:
871 Reenter new passphrase:
872 # dd if=/dev/random of=/dev/da1s3a bs=1m
873 # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
874 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a
875 .Ed
876 .Pp
877 The providers are initialized, now we have to add these lines to
878 .Pa /boot/loader.conf :
879 .Bd -literal -offset indent
880 geli_da0_keyfile0_load="YES"
881 geli_da0_keyfile0_type="da0:geli_keyfile0"
882 geli_da0_keyfile0_name="/boot/keys/da0.key0"
883 geli_da0_keyfile1_load="YES"
884 geli_da0_keyfile1_type="da0:geli_keyfile1"
885 geli_da0_keyfile1_name="/boot/keys/da0.key1"
886 geli_da0_keyfile2_load="YES"
887 geli_da0_keyfile2_type="da0:geli_keyfile2"
888 geli_da0_keyfile2_name="/boot/keys/da0.key2"
889
890 geli_da1s3a_keyfile0_load="YES"
891 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
892 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
893 .Ed
894 .Pp
895 Not only configure encryption, but also data integrity verification using
896 .Nm HMAC/SHA256 .
897 .Bd -literal -offset indent
898 # geli init -a hmac/sha256 -s 4096 /dev/da0
899 Enter new passphrase:
900 Reenter new passphrase:
901 # geli attach /dev/da0
902 Enter passphrase:
903 # dd if=/dev/random of=/dev/da0.eli bs=1m
904 # newfs /dev/da0.eli
905 # mount /dev/da0.eli /mnt/secret
906 .Ed
907 .Pp
908 .Cm geli
909 writes the metadata backup by default to the
910 .Pa /var/backups/<prov>.eli
911 file.
912 If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored.
913 Consider the following situation:
914 .Bd -literal -offset indent
915 # geli init /dev/da0
916 Enter new passphrase:
917 Reenter new passphrase:
918
919 Metadata backup can be found in /var/backups/da0.eli and
920 can be restored with the following command:
921
922         # geli restore /var/backups/da0.eli /dev/da0
923
924 # geli clear /dev/da0
925 # geli attach /dev/da0
926 geli: Cannot read metadata from /dev/da0: Invalid argument.
927 # geli restore /var/backups/da0.eli /dev/da0
928 # geli attach /dev/da0
929 Enter passphrase:
930 .Ed
931 .Pp
932 If an encrypted file system is extended, it is necessary to relocate and
933 update the metadata:
934 .Bd -literal -offset indent
935 # gpart create -s GPT ada0
936 # gpart add -s 1g -t freebsd-ufs -i 1 ada0
937 # geli init -K keyfile -P ada0p1
938 # gpart resize -s 2g -i 1 ada0
939 # geli resize -s 1g ada0p1
940 # geli attach -k keyfile -p ada0p1
941 .Ed
942 .Pp
943 Initialize provider with the passphrase split into two files.
944 The provider can be attached using those two files or by entering
945 .Dq foobar
946 as the passphrase at the
947 .Nm
948 prompt:
949 .Bd -literal -offset indent
950 # echo foo > da0.pass0
951 # echo bar > da0.pass1
952 # geli init -J da0.pass0 -J da0.pass1 da0
953 # geli attach -j da0.pass0 -j da0.pass1 da0
954 # geli detach da0
955 # geli attach da0
956 Enter passphrase: foobar
957 .Ed
958 .Pp
959 Suspend all
960 .Nm
961 devices on a laptop, suspend the laptop, then resume devices one by one after
962 resuming the laptop:
963 .Bd -literal -offset indent
964 # geli suspend -a
965 # zzz
966 <resume your laptop>
967 # geli resume -p -k keyfile gpt/secret
968 # geli resume gpt/private
969 Enter passphrase:
970 .Ed
971 .Sh ENCRYPTION MODES
972 .Nm
973 supports two encryption modes:
974 .Nm XTS ,
975 which was standardized as
976 .Nm IEEE P1619
977 and
978 .Nm CBC
979 with unpredictable IV.
980 The
981 .Nm CBC
982 mode used by
983 .Nm
984 is very similar to the mode
985 .Nm ESSIV .
986 .Sh DATA AUTHENTICATION
987 .Nm
988 can verify data integrity when an authentication algorithm is specified.
989 When data corruption/modification is detected,
990 .Nm
991 will not return any data, but instead will return an error
992 .Pq Er EINVAL .
993 The offset and size of the corrupted data will be printed on the console.
994 It is important to know against which attacks
995 .Nm
996 provides protection for your data.
997 If data is modified in-place or copied from one place on the disk
998 to another even without modification,
999 .Nm
1000 should be able to detect such a change.
1001 If an attacker can remember the encrypted data, he can overwrite any future
1002 changes with the data he owns without it being noticed.
1003 In other words
1004 .Nm
1005 will not protect your data against replay attacks.
1006 .Pp
1007 It is recommended to write to the whole provider before first use,
1008 in order to make sure that all sectors and their corresponding
1009 checksums are properly initialized into a consistent state.
1010 One can safely ignore data authentication errors that occur immediately
1011 after the first time a provider is attached and before it is
1012 initialized in this way.
1013 .Sh SEE ALSO
1014 .Xr crypto 4 ,
1015 .Xr gbde 4 ,
1016 .Xr geom 4 ,
1017 .Xr loader.conf 5 ,
1018 .Xr gbde 8 ,
1019 .Xr geom 8 ,
1020 .Xr crypto 9
1021 .Sh HISTORY
1022 The
1023 .Nm
1024 utility appeared in
1025 .Fx 6.0 .
1026 Support for the
1027 .Nm Camellia
1028 block cipher is implemented by Yoshisato Yanagisawa in
1029 .Fx 7.0 .
1030 .Pp
1031 Highest
1032 .Nm GELI
1033 metadata version supported by the given FreeBSD version:
1034 .Bl -column -offset indent ".Sy FreeBSD" ".Sy version"
1035 .It Sy FreeBSD Ta Sy GELI
1036 .It Sy version Ta Sy version
1037 .Pp
1038 .It Li 6.0 Ta 0
1039 .It Li 6.1 Ta 0
1040 .It Li 6.2 Ta 3
1041 .It Li 6.3 Ta 3
1042 .It Li 6.4 Ta 3
1043 .Pp
1044 .It Li 7.0 Ta 3
1045 .It Li 7.1 Ta 3
1046 .It Li 7.2 Ta 3
1047 .It Li 7.3 Ta 3
1048 .It Li 7.4 Ta 3
1049 .Pp
1050 .It Li 8.0 Ta 3
1051 .It Li 8.1 Ta 3
1052 .It Li 8.2 Ta 5
1053 .Pp
1054 .It Li 9.0 Ta 6
1055 .El
1056 .Sh AUTHORS
1057 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org