1 .\" Copyright (c) 2005-2010 Pawel Jakub Dawidek <pjd@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "control utility for cryptographic GEOM class"
34 To compile GEOM_ELI into your kernel, place the following lines in your kernel
36 .Bd -ragged -offset indent
38 .Cd "options GEOM_ELI"
41 Alternately, to load the GEOM_ELI module at boot time, place the following line
44 .Bd -literal -offset indent
56 .Op Fl B Ar backupfile
58 .Op Fl i Ar iterations
59 .Op Fl J Ar newpassfile
60 .Op Fl K Ar newkeyfile
62 .Op Fl s Ar sectorsize
65 .Cm label - an alias for
78 .Cm stop - an alias for
86 .Op Fl s Ar sectorsize
95 .Op Fl i Ar iterations
97 .Op Fl J Ar newpassfile
99 .Op Fl K Ar newkeyfile
155 utility is used to configure encryption on GEOM providers.
157 The following is a list of the most important features:
159 .Bl -bullet -offset indent -compact
163 framework, so when there is crypto hardware available,
165 will make use of it automatically.
167 Supports many cryptographic algorithms (currently
175 Can optionally perform data authentication (integrity verification) utilizing
176 one of the following algorithms:
185 Can create a key from a couple of components (user entered passphrase, random
186 bits from a file, etc.).
188 Allows to encrypt the root partition - the user will be asked for the
189 passphrase before the root file system is mounted.
191 The passphrase of the user is strengthened with:
194 .%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
199 Allows to use two independent keys (e.g.
202 .Qq "company key" ) .
206 performs simple sector-to-sector encryption.
208 Allows to backup/restore Master Keys, so when a user has to quickly
210 it is possible to get the data back by restoring keys from the backup.
212 Providers can be configured to automatically detach on last close
213 (so users do not have to remember to detach providers after unmounting
216 Allows to attach a provider with a random, one-time key - useful for swap
217 partitions and temporary file systems.
219 Allows to verify data integrity (data authentication).
221 Allows to suspend and resume encrypted devices.
224 The first argument to
226 indicates an action to be performed:
227 .Bl -tag -width ".Cm configure"
229 Initialize provider which needs to be encrypted.
230 Here you can set up the cryptographic algorithm to use, key length, etc.
231 The last provider's sector is used to store metadata.
234 subcommand also automatically backups metadata in
235 .Pa /var/backups/<prov>.eli
237 The metadata can be recovered with the
239 subcommand described below.
241 Additional options include:
242 .Bl -tag -width ".Fl J Ar newpassfile"
244 Enable data integrity verification (authentication) using the given algorithm.
245 This will reduce size of available storage and also reduce speed.
246 For example, when using 4096 bytes sector and
248 algorithm, 89% of the original provider storage will be available for use.
249 Currently supported algorithms are:
257 If the option is not given, there will be no authentication, only encryption.
258 The recommended algorithm is
261 Ask for the passphrase on boot, before the root partition is mounted.
262 This makes it possible to use an encrypted root partition.
263 One will still need bootable unencrypted storage with a
265 directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
267 .It Fl B Ar backupfile
268 File name to use for metadata backup instead of the default
269 .Pa /var/backups/<prov>.eli .
270 To inhibit backups, you can use
275 Encryption algorithm to use.
276 Currently supported algorithms are:
283 The default and recommended algorithm is
285 .It Fl i Ar iterations
286 Number of iterations to use with PKCS#5v2.
287 If this option is not specified,
289 will find the number of iterations which is equal to 2 seconds of crypto work.
290 If 0 is given, PKCS#5v2 will not be used.
291 .It Fl J Ar newpassfile
292 Specifies a file which contains the passphrase or its part.
295 is given as -, standard input will be used.
296 Only the first line (excluding new-line character) is taken from the given file.
297 This argument can be specified multiple times.
298 .It Fl K Ar newkeyfile
299 Specifies a file which contains part of the key.
302 is given as -, standard input will be used.
303 This argument can be specified multiple times.
305 Key length to use with the given cryptographic algorithm.
306 If not given, the default key length for the given algorithm is used, which is:
316 Do not use passphrase as the key component.
317 .It Fl s Ar sectorsize
318 Change decrypted provider's sector size.
319 Increasing sector size allows to increase performance, because we need to
320 generate an IV and do encrypt/decrypt for every single sector - less number
321 of sectors means less work to do.
324 Attach the given provider.
325 The master key will be decrypted using the given
326 passphrase/keyfile and a new GEOM provider will be created using the given
327 provider's name with an
331 Additional options include:
332 .Bl -tag -width ".Fl j Ar passfile"
334 If specified, a decrypted provider will be detached automatically on last close.
335 This can help with short memory - user does not have to remember to detach the
336 provider after unmounting the file system.
337 It only works when the provider was opened for writing, so it will not work if
338 the file system on the provider is mounted read-only.
339 Probably a better choice is the
345 Specifies a file which contains the passphrase or its part.
346 For more information see the description of the
352 Specifies a file which contains part of the key.
353 For more information see the description of the
359 Do not use passphrase as the key component.
361 Attach read-only provider.
362 It will not be opened for writing.
365 Detach the given providers, which means remove the devfs entry
366 and clear the keys from memory.
368 Additional options include:
369 .Bl -tag -width ".Fl f"
371 Force detach - detach even if the provider is open.
373 Mark provider to detach on last close.
374 If this option is specified, the provider will not be detached
375 until it is open, but when it will be closed last time, it will
376 be automatically detached (even
377 if it was only opened for reading).
380 Attach the given providers with random, one-time keys.
381 The command can be used to encrypt swap partitions or temporary file systems.
383 Additional options include:
384 .Bl -tag -width ".Fl a Ar sectorsize"
386 Enable data integrity verification (authentication).
387 For more information, see the description of the
391 Encryption algorithm to use.
392 For more information, see the description of the
396 Detach on last close.
397 Note, the option is not usable for temporary file systems as the provider will
398 be detached after creating the file system on it.
399 It still can (and should be) used for swap partitions.
400 For more information, see the description of the
404 Key length to use with the given cryptographic algorithm.
405 For more information, see the description of the
408 .It Fl s Ar sectorsize
409 Change decrypted provider's sector size.
410 For more information, see the description of the
415 Change configuration of the given providers.
417 Additional options include:
418 .Bl -tag -width ".Fl b"
420 Set the BOOT flag on the given providers.
421 For more information, see the description of the
425 Remove the BOOT flag from the given providers.
428 Change or setup (if not yet initialized) selected key.
429 There is one master key, which can be encrypted with two independent user keys.
432 subcommand, only key number 0 is initialized.
433 The key can always be changed: for an attached provider,
434 for a detached provider or on the backup file.
435 When a provider is attached, the user does not have to provide
436 an old passphrase/keyfile.
438 Additional options include:
439 .Bl -tag -width ".Fl J Ar newpassfile"
440 .It Fl i Ar iterations
441 Number of iterations to use with PKCS#5v2.
442 If 0 is given, PKCS#5v2 will not be used.
443 To be able to use this option with
445 subcommand, only one key have to be defined and this key has to be changed.
447 Specifies a file which contains the old passphrase or its part.
448 .It Fl J Ar newpassfile
449 Specifies a file which contains the new passphrase or its part.
451 Specifies a file which contains part of the old key.
452 .It Fl K Ar newkeyfile
453 Specifies a file which contains part of the new key.
455 Specifies the number of the key to change (could be 0 or 1).
456 If the provider is attached and no key number is given, the key
457 used for attaching the provider will be changed.
458 If the provider is detached (or we are operating on a backup file)
459 and no key number is given, the key decrypted with the passphrase/keyfile
462 Do not use passphrase as the old key component.
464 Do not use passphrase as the new key component.
467 Destroy (overwrite with random data) the selected key.
468 If one is destroying keys for an attached provider, the provider
469 will not be detached even if all keys will be destroyed.
470 It can be even rescued with the
474 Additional options include:
475 .Bl -tag -width ".Fl a Ar keyno"
477 Destroy all keys (does not need
481 Force key destruction.
482 This option is needed to destroy the last key.
484 Specifies the key number.
485 If the provider is attached and no key number is given, the key
486 used for attaching the provider will be destroyed.
487 If provider is detached (or we are operating on a backup file) the key number
491 This command should be used in emergency situations.
492 It will destroy all keys on the given provider and will detach it forcibly
494 This is absolutely a one-way command - if you do not have a metadata
495 backup, your data is gone for good.
496 In case the provider was attached with the
498 flag, the keys will not be destroyed, only the provider will be detached.
500 Additional options include:
501 .Bl -tag -width ".Fl a"
503 If specified, all currently attached providers will be killed.
506 Backup metadata from the given provider to the given file.
508 Restore metadata from the given file to the given provider.
510 Additional options include:
511 .Bl -tag -width ".Fl f"
513 Metadata contains the size of the provider to ensure that the correct
514 partition or slice is attached.
515 If an attempt is made to restore metadata to a provider that has a different
518 will refuse to restore the data unless the
521 If the partition or slice has been grown, the
523 subcommand should be used rather than attempting to relocate the metadata
530 Suspend device by waiting for all inflight request to finish, clearing all
531 sensitive informations (like keys) from the kernel memory and blocking all
532 further I/O requests until the
534 subcommand is executed.
535 This functionality is useful for eg. laptops - when one wants to suspend a
536 laptop, one does not want to leave encrypted device attached.
537 Instead of closing all files and directories opened from a file system placed
538 on an encrypted device, unmounting the file system and detaching the device,
541 subcommand can be used.
542 Any access to the encrypted device will be blocked until the keys are
545 subcommand, thus there is no need to close nor unmount anything.
548 subcommand does not work with devices created with the
551 Please note that sensitive data might still be present in memory after
552 suspending encrypted device, because of file system cache, etc.
554 Additional options include:
555 .Bl -tag -width ".Fl a"
562 Resume previously suspended device.
563 The caller must ensure that executing this subcommand won't try to access
564 suspended device, which will lead to a deadlock.
565 For example suspending device, which contains file system where the
567 utility is stored is bad idea.
569 Additional options include:
570 .Bl -tag -width ".Fl j Ar passfile"
572 Specifies a file which contains the passphrase or its part.
573 For more information see the description of the
579 Specifies a file which contains part of the key.
580 For more information see the description of the
586 Do not use passphrase as the key component.
591 that the provider has been resized.
592 The old metadata block is relocated to the correct position at the end of the
593 provider and the provider size is updated.
595 Additional options include:
596 .Bl -tag -width ".Fl s Ar oldsize"
598 The size of the provider before it was resized.
601 Clear metadata from the given providers.
603 Dump metadata stored on the given providers.
618 Additional options include:
619 .Bl -tag -width ".Fl v"
626 variables can be used to control the behavior of the
629 The default value is shown next to each variable.
630 All variables can also be set in
631 .Pa /boot/loader.conf .
632 .Bl -tag -width indent
633 .It Va kern.geom.eli.debug : No 0
637 This can be set to a number between 0 and 3 inclusive.
638 If set to 0, minimal debug information is printed.
640 maximum amount of debug information is printed.
641 .It Va kern.geom.eli.tries : No 3
642 Number of times a user is asked for the passphrase.
643 This is only used for providers which should be attached on boot
644 (before the root file system is mounted).
645 If set to 0, attaching providers on boot will be disabled.
646 This variable should be set in
647 .Pa /boot/loader.conf .
648 .It Va kern.geom.eli.overwrites : No 5
649 Specifies how many times the Master-Key will be overwritten
650 with random values when it is destroyed.
651 After this operation it is filled with zeros.
652 .It Va kern.geom.eli.visible_passphrase : No 0
653 If set to 1, the passphrase entered on boot (before the root
654 file system is mounted) will be visible.
655 This possibility should be used with caution as the entered
656 passphrase can be logged and exposed via
658 This variable should be set in
659 .Pa /boot/loader.conf .
660 .It Va kern.geom.eli.threads : No 0
661 Specifies how many kernel threads should be used for doing software
663 Its purpose is to increase performance on SMP systems.
664 If hardware acceleration is available, only one thread will be started.
665 If set to 0, CPU-bound thread will be started for every active CPU.
666 .It Va kern.geom.eli.batch : No 0
667 When set to 1, can speed-up crypto operations by using batching.
668 Batching allows to reduce number of interrupts by responding on a group of
669 crypto requests with one interrupt.
670 The crypto card and the driver has to support this feature.
673 Exit status is 0 on success, and 1 if the command fails.
675 Initialize a provider which is going to be encrypted with a
676 passphrase and random data from a file on the user's pen drive.
678 Attach the provider, create a file system and mount it.
680 Unmount the provider and detach it:
681 .Bd -literal -offset indent
682 # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
683 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
684 Enter new passphrase:
685 Reenter new passphrase:
686 # geli attach -k /mnt/pendrive/da2.key /dev/da2
688 # dd if=/dev/random of=/dev/da2.eli bs=1m
690 # mount /dev/da2.eli /mnt/secret
693 # geli detach da2.eli
696 Create an encrypted provider, but use two keys:
697 one for your girlfriend and one for
698 you (so there will be no tragedy if she forgets her passphrase):
699 .Bd -literal -offset indent
701 Enter new passphrase: (enter your passphrase)
702 Reenter new passphrase:
703 # geli setkey -n 1 /dev/da2
704 Enter passphrase: (enter your passphrase)
705 Enter new passphrase: (let your girlfriend enter her passphrase ...)
706 Reenter new passphrase: (... twice)
709 You are the security-person in your company.
710 Create an encrypted provider for use by the user, but remember that users
711 forget their passphrases, so back Master Key up with your own random key:
712 .Bd -literal -offset indent
713 # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
714 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ad0s1e
715 # geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
716 (use key number 0, so the encrypted Master Key by you will be overwritten)
717 # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
718 (allow the user to enter his passphrase)
719 Enter new passphrase:
720 Reenter new passphrase:
723 Encrypted swap partition setup:
724 .Bd -literal -offset indent
725 # dd if=/dev/random of=/dev/ad0s1b bs=1m
726 # geli onetime -d -e 3des ad0s1b
727 # swapon /dev/ad0s1b.eli
730 The example below shows how to configure two providers which will be attached
731 on boot (before the root file system is mounted).
732 One of them is using passphrase and three keyfiles and the other is using only a
734 .Bd -literal -offset indent
735 # dd if=/dev/random of=/dev/da0 bs=1m
736 # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
737 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
738 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
739 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
740 Enter new passphrase:
741 Reenter new passphrase:
742 # dd if=/dev/random of=/dev/da1s3a bs=1m
743 # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
744 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a
747 The providers are initialized, now we have to add those lines to
748 .Pa /boot/loader.conf :
749 .Bd -literal -offset indent
750 geli_da0_keyfile0_load="YES"
751 geli_da0_keyfile0_type="da0:geli_keyfile0"
752 geli_da0_keyfile0_name="/boot/keys/da0.key0"
753 geli_da0_keyfile1_load="YES"
754 geli_da0_keyfile1_type="da0:geli_keyfile1"
755 geli_da0_keyfile1_name="/boot/keys/da0.key1"
756 geli_da0_keyfile2_load="YES"
757 geli_da0_keyfile2_type="da0:geli_keyfile2"
758 geli_da0_keyfile2_name="/boot/keys/da0.key2"
760 geli_da1s3a_keyfile0_load="YES"
761 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
762 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
765 Not only configure encryption, but also data integrity verification using
767 .Bd -literal -offset indent
768 # geli init -a hmac/sha256 -s 4096 /dev/da0
769 Enter new passphrase:
770 Reenter new passphrase:
771 # geli attach /dev/da0
773 # dd if=/dev/random of=/dev/da0.eli bs=1m
775 # mount /dev/da0.eli /mnt/secret
779 backups metadata by default to the
780 .Pa /var/backups/<prov>.eli
782 If metadata is lost in any way (eg. by accidental overwrite), it can be restored.
783 Consider the following situation:
784 .Bd -literal -offset indent
786 Enter new passphrase:
787 Reenter new passphrase:
789 Metadata backup can be found in /var/backups/da0.eli and
790 can be restored with the following command:
792 # geli restore /var/backups/da0.eli /dev/da0
794 # geli clear /dev/da0
795 # geli attach /dev/da0
796 geli: Cannot read metadata from /dev/da0: Invalid argument.
797 # geli restore /var/backups/da0.eli /dev/da0
798 # geli attach /dev/da0
802 If an encrypted filesystem is extended, it is necessary to relocate and
804 .Bd -literal -offset indent
805 # gpart create -s GPT ada0
806 # gpart add -s 1g -t freebsd-ufs -i 1 ada0
807 # geli init -K keyfile -P ada0p1
808 # gpart resize -s 2g -i 1 ada0
809 # geli resize -s 1g ada0p1
810 # geli attach -k keyfile -p ada0p1
813 Initialize provider with passphrase split into two files.
814 The provider can be attached by giving those two files or by giving
819 .Bd -literal -offset indent
820 # echo foo > da0.pass0
821 # echo bar > da0.pass1
822 # geli init -J da0.pass0 -J da0.pass1 da0
823 # geli attach -j da0.pass0 -j da0.pass1 da0
826 Enter passphrase: foobar
831 devices, suspend a laptop, then resume devices one by one after resuming a
833 .Bd -literal -offset indent
837 # geli resume -p -k keyfile gpt/secret
838 # geli resume gpt/private
843 supports two encryption modes:
845 which was standarized as
849 with unpredictable IV.
854 is very similar to the mode
856 .Sh DATA AUTHENTICATION
858 can verify data integrity when an authentication algorithm is specified.
859 When data corruption/modification is detected,
861 will not return any data, but instead will return an error
863 The offset and size of the corrupted data will be printed on the console.
864 It is important to know against which attacks
866 provides protection for your data.
867 If data is modified in-place or copied from one place on the disk
868 to another even without modification,
870 should be able to detect such a change.
871 If an attacker can remember the encrypted data, he can overwrite any future
872 changes with the data he owns without notice.
875 will not protect your data against replay attacks.
891 block cipher is implemented by Yoshisato Yanagisawa in
894 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
projects / FreeBSD / releng / 8.2.git / blob