]> CyberLeo.Net >> Repos - FreeBSD/stable/10.git/blob - sbin/geom/class/eli/geli.8
MFC r267667:
[FreeBSD/stable/10.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 June 18, 2014
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 Camellia-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 a 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 an older version of metadata may limit the number of
363 features available.
364 .El
365 .It Cm attach
366 Attach the given provider.
367 The encrypted Master Key will be loaded from the metadata and decrypted
368 using the given passphrase/keyfile and a new GEOM provider will be created
369 using the given provider's name with an
370 .Qq .eli
371 suffix.
372 .Pp
373 Additional options include:
374 .Bl -tag -width ".Fl j Ar passfile"
375 .It Fl d
376 If specified, a decrypted provider will be detached automatically on last close.
377 This can help with scarce memory so the user does not have to remember to detach the
378 provider after unmounting the file system.
379 It only works when the provider was opened for writing, so it will not work if
380 the file system on the provider is mounted read-only.
381 Probably a better choice is the
382 .Fl l
383 option for the
384 .Cm detach
385 subcommand.
386 .It Fl j Ar passfile
387 Specifies a file which contains the passphrase component of the User Key
388 (or part of it).
389 For more information see the description of the
390 .Fl J
391 option for the
392 .Cm init
393 subcommand.
394 .It Fl k Ar keyfile
395 Specifies a file which contains the keyfile component of the User Key
396 (or part of it).
397 For more information see the description of the
398 .Fl K
399 option for the
400 .Cm init
401 subcommand.
402 .It Fl p
403 Do not use a passphrase as a component of the User Key.
404 Cannot be combined with the
405 .Fl j
406 option.
407 .It Fl r
408 Attach read-only provider.
409 It will not be opened for writing.
410 .El
411 .It Cm detach
412 Detach the given providers, which means remove the devfs entry
413 and clear the Master Key and Data Keys from memory.
414 .Pp
415 Additional options include:
416 .Bl -tag -width ".Fl f"
417 .It Fl f
418 Force detach - detach even if the provider is open.
419 .It Fl l
420 Mark provider to detach on last close.
421 If this option is specified, the provider will not be detached
422 while it is open, but will be automatically detached when it is closed for the
423 last time even if it was only opened for reading.
424 .El
425 .It Cm onetime
426 Attach the given providers with a random, one-time (ephemeral) Master Key.
427 The command can be used to encrypt swap partitions or temporary file systems.
428 .Pp
429 Additional options include:
430 .Bl -tag -width ".Fl a Ar sectorsize"
431 .It Fl a Ar aalgo
432 Enable data integrity verification (authentication).
433 For more information, see the description of the
434 .Cm init
435 subcommand.
436 .It Fl e Ar ealgo
437 Encryption algorithm to use.
438 For more information, see the description of the
439 .Cm init
440 subcommand.
441 .It Fl d
442 Detach on last close.
443 Note: this option is not usable for temporary file systems as the provider will
444 be detached after creating the file system on it.
445 It still can (and should be) used for swap partitions.
446 For more information, see the description of the
447 .Cm attach
448 subcommand.
449 .It Fl l Ar keylen
450 Data Key length to use with the given cryptographic algorithm.
451 For more information, see the description of the
452 .Cm init
453 subcommand.
454 .It Fl s Ar sectorsize
455 Change decrypted provider's sector size.
456 For more information, see the description of the
457 .Cm init
458 subcommand.
459 .El
460 .It Cm configure
461 Change configuration of the given providers.
462 .Pp
463 Additional options include:
464 .Bl -tag -width ".Fl b"
465 .It Fl b
466 Set the BOOT flag on the given providers.
467 For more information, see the description of the
468 .Cm init
469 subcommand.
470 .It Fl B
471 Remove the BOOT flag from the given providers.
472 .El
473 .It Cm setkey
474 Install a copy of the Master Key into the selected slot, encrypted with
475 a new User Key.
476 If the selected slot is populated, replace the existing copy.
477 A provider has one Master Key, which can be stored in one or both slots,
478 each encrypted with an independent User Key.
479 With the
480 .Cm init
481 subcommand, only key number 0 is initialized.
482 The User Key can be changed at any time: for an attached provider,
483 for a detached provider, or on the backup file.
484 When a provider is attached, the user does not have to provide
485 an existing passphrase/keyfile.
486 .Pp
487 Additional options include:
488 .Bl -tag -width ".Fl J Ar newpassfile"
489 .It Fl i Ar iterations
490 Number of iterations to use with PKCS#5v2.
491 If 0 is given, PKCS#5v2 will not be used.
492 To be able to use this option with the
493 .Cm setkey
494 subcommand, only one key has to be defined and this key must be changed.
495 .It Fl j Ar passfile
496 Specifies a file which contains the passphrase component of a current User Key
497 (or part of it).
498 .It Fl J Ar newpassfile
499 Specifies a file which contains the passphrase component of the new User Key
500 (or part of it).
501 .It Fl k Ar keyfile
502 Specifies a file which contains the keyfile component of a current User Key
503 (or part of it).
504 .It Fl K Ar newkeyfile
505 Specifies a file which contains the keyfile component of the new User Key
506 (or part of it).
507 .It Fl n Ar keyno
508 Specifies the index number of the Master Key copy to change (could be 0 or 1).
509 If the provider is attached and no key number is given, the key
510 used for attaching the provider will be changed.
511 If the provider is detached (or we are operating on a backup file)
512 and no key number is given, the first Master Key copy to be successfully
513 decrypted with the provided User Key passphrase/keyfile will be changed.
514 .It Fl p
515 Do not use a passphrase as a component of the current User Key.
516 Cannot be combined with the
517 .Fl j
518 option.
519 .It Fl P
520 Do not use a passphrase as a component of the new User Key.
521 Cannot be combined with the
522 .Fl J
523 option.
524 .El
525 .It Cm delkey
526 Destroy (overwrite with random data) the selected Master Key copy.
527 If one is destroying keys for an attached provider, the provider
528 will not be detached even if all copies of the Master Key are destroyed.
529 It can even be rescued with the
530 .Cm setkey
531 subcommand because the Master Key is still in memory.
532 .Pp
533 Additional options include:
534 .Bl -tag -width ".Fl a Ar keyno"
535 .It Fl a
536 Destroy all copies of the Master Key (does not need
537 .Fl f
538 option).
539 .It Fl f
540 Force key destruction.
541 This option is needed to destroy the last copy of the Master Key.
542 .It Fl n Ar keyno
543 Specifies the index number of the Master Key copy.
544 If the provider is attached and no key number is given, the key
545 used for attaching the provider will be destroyed.
546 If provider is detached (or we are operating on a backup file) the key number
547 has to be given.
548 .El
549 .It Cm kill
550 This command should be used only in emergency situations.
551 It will destroy all copies of the Master Key on a given provider and will
552 detach it forcibly (if it is attached).
553 This is absolutely a one-way command - if you do not have a metadata
554 backup, your data is gone for good.
555 In case the provider was attached with the
556 .Fl r
557 flag, the keys will not be destroyed, only the provider will be detached.
558 .Pp
559 Additional options include:
560 .Bl -tag -width ".Fl a"
561 .It Fl a
562 If specified, all currently attached providers will be killed.
563 .El
564 .It Cm backup
565 Backup metadata from the given provider to the given file.
566 .It Cm restore
567 Restore metadata from the given file to the given provider.
568 .Pp
569 Additional options include:
570 .Bl -tag -width ".Fl f"
571 .It Fl f
572 Metadata contains the size of the provider to ensure that the correct
573 partition or slice is attached.
574 If an attempt is made to restore metadata to a provider that has a different
575 size,
576 .Nm
577 will refuse to restore the data unless the
578 .Fl f
579 switch is used.
580 If the partition or slice has been grown, the
581 .Cm resize
582 subcommand should be used rather than attempting to relocate the metadata
583 through
584 .Cm backup
585 and
586 .Cm restore .
587 .El
588 .It Cm suspend
589 Suspend device by waiting for all inflight requests to finish, clearing all
590 sensitive information (like the Master Key and Data Keys) from kernel memory,
591 and blocking all further I/O requests until the
592 .Cm resume
593 subcommand is executed.
594 This functionality is useful for laptops: when one wants to suspend a
595 laptop, one does not want to leave an encrypted device attached.
596 Instead of closing all files and directories opened from a file system located
597 on an encrypted device, unmounting the file system, and detaching the device,
598 the
599 .Cm suspend
600 subcommand can be used.
601 Any access to the encrypted device will be blocked until the Master Key is
602 reloaded through the
603 .Cm resume
604 subcommand.
605 Thus there is no need to close nor unmount anything.
606 The
607 .Cm suspend
608 subcommand does not work with devices created with the
609 .Cm onetime
610 subcommand.
611 Please note that sensitive data might still be present in memory after
612 suspending an encrypted device due to the file system cache, etc.
613 .Pp
614 Additional options include:
615 .Bl -tag -width ".Fl a"
616 .It Fl a
617 Suspend all
618 .Nm
619 devices.
620 .El
621 .It Cm resume
622 Resume previously suspended device.
623 The caller must ensure that executing this subcommand does not access the
624 suspended device, leading to a deadlock.
625 For example suspending a device which contains the file system where the
626 .Nm
627 utility is stored is bad idea.
628 .Pp
629 Additional options include:
630 .Bl -tag -width ".Fl j Ar passfile"
631 .It Fl j Ar passfile
632 Specifies a file which contains the passphrase component of the User Key
633 (or part of it).
634 For more information see the description of the
635 .Fl J
636 option for the
637 .Cm init
638 subcommand.
639 .It Fl k Ar keyfile
640 Specifies a file which contains the keyfile component of the User Key
641 (or part of it).
642 For more information see the description of the
643 .Fl K
644 option for the
645 .Cm init
646 subcommand.
647 .It Fl p
648 Do not use a passphrase as a component of the User Key.
649 Cannot be combined with the
650 .Fl j
651 option.
652 .El
653 .It Cm resize
654 Inform
655 .Nm
656 that the provider has been resized.
657 The old metadata block is relocated to the correct position at the end of the
658 provider and the provider size is updated.
659 .Pp
660 Additional options include:
661 .Bl -tag -width ".Fl s Ar oldsize"
662 .It Fl s Ar oldsize
663 The size of the provider before it was resized.
664 .El
665 .It Cm version
666 If no arguments are given, the
667 .Cm version
668 subcommand will print the version of
669 .Nm
670 userland utility as well as the version of the
671 .Nm ELI
672 GEOM class.
673 .Pp
674 If GEOM providers are specified, the
675 .Cm version
676 subcommand will print metadata version used by each of them.
677 .It Cm clear
678 Clear metadata from the given providers.
679 .Em WARNING :
680 This will erase with zeros the encrypted Master Key copies stored in the
681 metadata.
682 .It Cm dump
683 Dump metadata stored on the given providers.
684 .It Cm list
685 See
686 .Xr geom 8 .
687 .It Cm status
688 See
689 .Xr geom 8 .
690 .It Cm load
691 See
692 .Xr geom 8 .
693 .It Cm unload
694 See
695 .Xr geom 8 .
696 .El
697 .Pp
698 Additional options include:
699 .Bl -tag -width ".Fl v"
700 .It Fl v
701 Be more verbose.
702 .El
703 .Sh KEY SUMMARY
704 .Ss Master Key
705 Upon
706 .Cm init ,
707 the
708 .Nm
709 utility generates a random Master Key for the provider.
710 The Master Key never changes during the lifetime of the provider.
711 Each copy of the provider metadata, active or backed up to a file, can store
712 up to two, independently-encrypted copies of the Master Key.
713 .Ss User Key
714 Each stored copy of the Master Key is encrypted with a User Key, which
715 is generated by the
716 .Nm
717 utility from a passphrase and/or a keyfile.
718 The
719 .Nm
720 utility first reads all parts of the keyfile in the order specified on the
721 command line, then reads all parts of the stored passphrase in the order
722 specified on the command line.
723 If no passphrase parts are specified, the system prompts the user to enter
724 the passphrase.
725 The passphrase is optionally strengthened by PKCS#5v2.
726 The User Key is a digest computed over the concatenated keyfile and passphrase.
727 .Ss Data Key
728 During operation, one or more Data Keys are deterministically derived by
729 the kernel from the Master Key and cached in memory.
730 The number of Data Keys used by a given provider, and the way they are
731 derived, depend on the GELI version and whether the provider is configured to
732 use data authentication.
733 .Sh SYSCTL VARIABLES
734 The following
735 .Xr sysctl 8
736 variables can be used to control the behavior of the
737 .Nm ELI
738 GEOM class.
739 The default value is shown next to each variable.
740 Some variables can also be set in
741 .Pa /boot/loader.conf .
742 .Bl -tag -width indent
743 .It Va kern.geom.eli.version
744 Version number of the
745 .Nm ELI
746 GEOM class.
747 .It Va kern.geom.eli.debug : No 0
748 Debug level of the
749 .Nm ELI
750 GEOM class.
751 This can be set to a number between 0 and 3 inclusive.
752 If set to 0, minimal debug information is printed.
753 If set to 3, the
754 maximum amount of debug information is printed.
755 .It Va kern.geom.eli.tries : No 3
756 Number of times a user is asked for the passphrase.
757 This is only used for providers which are attached on boot
758 (before the root file system is mounted).
759 If set to 0, attaching providers on boot will be disabled.
760 This variable should be set in
761 .Pa /boot/loader.conf .
762 .It Va kern.geom.eli.overwrites : No 5
763 Specifies how many times the Master Key will be overwritten
764 with random values when it is destroyed.
765 After this operation it is filled with zeros.
766 .It Va kern.geom.eli.visible_passphrase : No 0
767 If set to 1, the passphrase entered on boot (before the root
768 file system is mounted) will be visible.
769 This alternative should be used with caution as the entered
770 passphrase can be logged and exposed via
771 .Xr dmesg 8 .
772 This variable should be set in
773 .Pa /boot/loader.conf .
774 .It Va kern.geom.eli.threads : No 0
775 Specifies how many kernel threads should be used for doing software
776 cryptography.
777 Its purpose is to increase performance on SMP systems.
778 If set to 0, a CPU-pinned thread will be started for every active CPU.
779 .It Va kern.geom.eli.batch : No 0
780 When set to 1, can speed-up crypto operations by using batching.
781 Batching reduces the number of interrupts by responding to a group of
782 crypto requests with one interrupt.
783 The crypto card and the driver has to support this feature.
784 .It Va kern.geom.eli.key_cache_limit : No 8192
785 Specifies how many Data Keys to cache.
786 The default limit
787 (8192 keys) will allow caching of all keys for a 4TB provider with 512 byte
788 sectors and will take around 1MB of memory.
789 .It Va kern.geom.eli.key_cache_hits
790 Reports how many times we were looking up a Data Key and it was already in
791 cache.
792 This sysctl is not updated for providers that need fewer Data Keys than
793 the limit specified in
794 .Va kern.geom.eli.key_cache_limit .
795 .It Va kern.geom.eli.key_cache_misses
796 Reports how many times we were looking up a Data Key and it was not in cache.
797 This sysctl is not updated for providers that need fewer Data Keys than the limit
798 specified in
799 .Va kern.geom.eli.key_cache_limit .
800 .El
801 .Sh EXIT STATUS
802 Exit status is 0 on success, and 1 if the command fails.
803 .Sh EXAMPLES
804 Initialize a provider which is going to be encrypted with a
805 passphrase and random data from a file on the user's pen drive.
806 Use 4kB sector size.
807 Attach the provider, create a file system, and mount it.
808 Do the work.
809 Unmount the provider and detach it:
810 .Bd -literal -offset indent
811 # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
812 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
813 Enter new passphrase:
814 Reenter new passphrase:
815 # geli attach -k /mnt/pendrive/da2.key /dev/da2
816 Enter passphrase:
817 # dd if=/dev/random of=/dev/da2.eli bs=1m
818 # newfs /dev/da2.eli
819 # mount /dev/da2.eli /mnt/secret
820 \&...
821 # umount /mnt/secret
822 # geli detach da2.eli
823 .Ed
824 .Pp
825 Create an encrypted provider, but use two User Keys:
826 one for your employee and one for you as the company's security officer
827 (so it is not a tragedy if the employee
828 .Qq accidentally
829 forgets his passphrase):
830 .Bd -literal -offset indent
831 # geli init /dev/da2
832 Enter new passphrase:   (enter security officer's passphrase)
833 Reenter new passphrase:
834 # geli setkey -n 1 /dev/da2
835 Enter passphrase:       (enter security officer's passphrase)
836 Enter new passphrase:   (let your employee enter his passphrase ...)
837 Reenter new passphrase: (... twice)
838 .Ed
839 .Pp
840 You are the security officer in your company.
841 Create an encrypted provider for use by the user, but remember that users
842 forget their passphrases, so backup the Master Key with your own random key:
843 .Bd -literal -offset indent
844 # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
845 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e
846 # geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname`
847 (use key number 0, so the encrypted Master Key will be re-encrypted by this)
848 # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e
849 (allow the user to enter his passphrase)
850 Enter new passphrase:
851 Reenter new passphrase:
852 .Ed
853 .Pp
854 Encrypted swap partition setup:
855 .Bd -literal -offset indent
856 # dd if=/dev/random of=/dev/ada0s1b bs=1m
857 # geli onetime -d -e 3des ada0s1b
858 # swapon /dev/ada0s1b.eli
859 .Ed
860 .Pp
861 The example below shows how to configure two providers which will be attached
862 on boot (before the root file system is mounted).
863 One of them is using passphrase and three keyfile parts and the other is
864 using only a keyfile in one part:
865 .Bd -literal -offset indent
866 # dd if=/dev/random of=/dev/da0 bs=1m
867 # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
868 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
869 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
870 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
871 Enter new passphrase:
872 Reenter new passphrase:
873 # dd if=/dev/random of=/dev/da1s3a bs=1m
874 # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
875 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a
876 .Ed
877 .Pp
878 The providers are initialized, now we have to add these lines to
879 .Pa /boot/loader.conf :
880 .Bd -literal -offset indent
881 geli_da0_keyfile0_load="YES"
882 geli_da0_keyfile0_type="da0:geli_keyfile0"
883 geli_da0_keyfile0_name="/boot/keys/da0.key0"
884 geli_da0_keyfile1_load="YES"
885 geli_da0_keyfile1_type="da0:geli_keyfile1"
886 geli_da0_keyfile1_name="/boot/keys/da0.key1"
887 geli_da0_keyfile2_load="YES"
888 geli_da0_keyfile2_type="da0:geli_keyfile2"
889 geli_da0_keyfile2_name="/boot/keys/da0.key2"
890
891 geli_da1s3a_keyfile0_load="YES"
892 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
893 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
894 .Ed
895 .Pp
896 Not only configure encryption, but also data integrity verification using
897 .Nm HMAC/SHA256 .
898 .Bd -literal -offset indent
899 # geli init -a hmac/sha256 -s 4096 /dev/da0
900 Enter new passphrase:
901 Reenter new passphrase:
902 # geli attach /dev/da0
903 Enter passphrase:
904 # dd if=/dev/random of=/dev/da0.eli bs=1m
905 # newfs /dev/da0.eli
906 # mount /dev/da0.eli /mnt/secret
907 .Ed
908 .Pp
909 .Cm geli
910 writes the metadata backup by default to the
911 .Pa /var/backups/<prov>.eli
912 file.
913 If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored.
914 Consider the following situation:
915 .Bd -literal -offset indent
916 # geli init /dev/da0
917 Enter new passphrase:
918 Reenter new passphrase:
919
920 Metadata backup can be found in /var/backups/da0.eli and
921 can be restored with the following command:
922
923         # geli restore /var/backups/da0.eli /dev/da0
924
925 # geli clear /dev/da0
926 # geli attach /dev/da0
927 geli: Cannot read metadata from /dev/da0: Invalid argument.
928 # geli restore /var/backups/da0.eli /dev/da0
929 # geli attach /dev/da0
930 Enter passphrase:
931 .Ed
932 .Pp
933 If an encrypted file system is extended, it is necessary to relocate and
934 update the metadata:
935 .Bd -literal -offset indent
936 # gpart create -s GPT ada0
937 # gpart add -s 1g -t freebsd-ufs -i 1 ada0
938 # geli init -K keyfile -P ada0p1
939 # gpart resize -s 2g -i 1 ada0
940 # geli resize -s 1g ada0p1
941 # geli attach -k keyfile -p ada0p1
942 .Ed
943 .Pp
944 Initialize provider with the passphrase split into two files.
945 The provider can be attached using those two files or by entering
946 .Dq foobar
947 as the passphrase at the
948 .Nm
949 prompt:
950 .Bd -literal -offset indent
951 # echo foo > da0.pass0
952 # echo bar > da0.pass1
953 # geli init -J da0.pass0 -J da0.pass1 da0
954 # geli attach -j da0.pass0 -j da0.pass1 da0
955 # geli detach da0
956 # geli attach da0
957 Enter passphrase: foobar
958 .Ed
959 .Pp
960 Suspend all
961 .Nm
962 devices on a laptop, suspend the laptop, then resume devices one by one after
963 resuming the laptop:
964 .Bd -literal -offset indent
965 # geli suspend -a
966 # zzz
967 <resume your laptop>
968 # geli resume -p -k keyfile gpt/secret
969 # geli resume gpt/private
970 Enter passphrase:
971 .Ed
972 .Sh ENCRYPTION MODES
973 .Nm
974 supports two encryption modes:
975 .Nm XTS ,
976 which was standardized as
977 .Nm IEEE P1619
978 and
979 .Nm CBC
980 with unpredictable IV.
981 The
982 .Nm CBC
983 mode used by
984 .Nm
985 is very similar to the mode
986 .Nm ESSIV .
987 .Sh DATA AUTHENTICATION
988 .Nm
989 can verify data integrity when an authentication algorithm is specified.
990 When data corruption/modification is detected,
991 .Nm
992 will not return any data, but instead will return an error
993 .Pq Er EINVAL .
994 The offset and size of the corrupted data will be printed on the console.
995 It is important to know against which attacks
996 .Nm
997 provides protection for your data.
998 If data is modified in-place or copied from one place on the disk
999 to another even without modification,
1000 .Nm
1001 should be able to detect such a change.
1002 If an attacker can remember the encrypted data, he can overwrite any future
1003 changes with the data he owns without it being noticed.
1004 In other words
1005 .Nm
1006 will not protect your data against replay attacks.
1007 .Pp
1008 It is recommended to write to the whole provider before first use,
1009 in order to make sure that all sectors and their corresponding
1010 checksums are properly initialized into a consistent state.
1011 One can safely ignore data authentication errors that occur immediately
1012 after the first time a provider is attached and before it is
1013 initialized in this way.
1014 .Sh SEE ALSO
1015 .Xr crypto 4 ,
1016 .Xr gbde 4 ,
1017 .Xr geom 4 ,
1018 .Xr loader.conf 5 ,
1019 .Xr gbde 8 ,
1020 .Xr geom 8 ,
1021 .Xr crypto 9
1022 .Sh HISTORY
1023 The
1024 .Nm
1025 utility appeared in
1026 .Fx 6.0 .
1027 Support for the
1028 .Nm Camellia
1029 block cipher is implemented by Yoshisato Yanagisawa in
1030 .Fx 7.0 .
1031 .Pp
1032 Highest
1033 .Nm GELI
1034 metadata version supported by the given FreeBSD version:
1035 .Bl -column -offset indent ".Sy FreeBSD" ".Sy version"
1036 .It Sy FreeBSD Ta Sy GELI
1037 .It Sy version Ta Sy version
1038 .Pp
1039 .It Li 6.0 Ta 0
1040 .It Li 6.1 Ta 0
1041 .It Li 6.2 Ta 3
1042 .It Li 6.3 Ta 3
1043 .It Li 6.4 Ta 3
1044 .Pp
1045 .It Li 7.0 Ta 3
1046 .It Li 7.1 Ta 3
1047 .It Li 7.2 Ta 3
1048 .It Li 7.3 Ta 3
1049 .It Li 7.4 Ta 3
1050 .Pp
1051 .It Li 8.0 Ta 3
1052 .It Li 8.1 Ta 3
1053 .It Li 8.2 Ta 5
1054 .Pp
1055 .It Li 9.0 Ta 6
1056 .Pp
1057 .It Li 10.0 Ta 7
1058 .El
1059 .Sh AUTHORS
1060 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org