1 .\" Copyright (c) 2005-2011 Pawel Jakub Dawidek <pawel@dawidek.net>
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 Some variables can also be set in
631 .Pa /boot/loader.conf .
632 .Bl -tag -width indent
633 .It Va kern.geom.eli.version
634 Version number of the
637 .It Va kern.geom.eli.debug : No 0
641 This can be set to a number between 0 and 3 inclusive.
642 If set to 0, minimal debug information is printed.
644 maximum amount of debug information is printed.
645 .It Va kern.geom.eli.tries : No 3
646 Number of times a user is asked for the passphrase.
647 This is only used for providers which should be attached on boot
648 (before the root file system is mounted).
649 If set to 0, attaching providers on boot will be disabled.
650 This variable should be set in
651 .Pa /boot/loader.conf .
652 .It Va kern.geom.eli.overwrites : No 5
653 Specifies how many times the Master-Key will be overwritten
654 with random values when it is destroyed.
655 After this operation it is filled with zeros.
656 .It Va kern.geom.eli.visible_passphrase : No 0
657 If set to 1, the passphrase entered on boot (before the root
658 file system is mounted) will be visible.
659 This possibility should be used with caution as the entered
660 passphrase can be logged and exposed via
662 This variable should be set in
663 .Pa /boot/loader.conf .
664 .It Va kern.geom.eli.threads : No 0
665 Specifies how many kernel threads should be used for doing software
667 Its purpose is to increase performance on SMP systems.
668 If hardware acceleration is available, only one thread will be started.
669 If set to 0, CPU-bound thread will be started for every active CPU.
670 .It Va kern.geom.eli.batch : No 0
671 When set to 1, can speed-up crypto operations by using batching.
672 Batching allows to reduce number of interrupts by responding on a group of
673 crypto requests with one interrupt.
674 The crypto card and the driver has to support this feature.
675 .It Va kern.geom.eli.key_cache_limit : No 8192
676 Specifies how many encryption keys to cache.
679 keys) will allow to cache all keys for 4TB provider with 512 bytes sectors and
680 will take around 1MB of memory.
681 .It Va kern.geom.eli.key_cache_hits
682 Reports how many times we were looking up a key and it was already in cache.
683 This sysctl is not updated for providers that need less keys than the limit
685 .Va kern.geom.eli.key_cache_limit .
686 .It Va kern.geom.eli.key_cache_misses
687 Reports how many times we were looking up a key and it was not in cache.
688 This sysctl is not updated for providers that need less keys than the limit
690 .Va kern.geom.eli.key_cache_limit .
693 Exit status is 0 on success, and 1 if the command fails.
695 Initialize a provider which is going to be encrypted with a
696 passphrase and random data from a file on the user's pen drive.
698 Attach the provider, create a file system and mount it.
700 Unmount the provider and detach it:
701 .Bd -literal -offset indent
702 # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
703 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
704 Enter new passphrase:
705 Reenter new passphrase:
706 # geli attach -k /mnt/pendrive/da2.key /dev/da2
708 # dd if=/dev/random of=/dev/da2.eli bs=1m
710 # mount /dev/da2.eli /mnt/secret
713 # geli detach da2.eli
716 Create an encrypted provider, but use two keys:
717 one for your employee and one for you as company's security officer
718 (so there is no tragedy if the employee
720 forgets his passphrase):
721 .Bd -literal -offset indent
723 Enter new passphrase: (enter security officer passphrase)
724 Reenter new passphrase:
725 # geli setkey -n 1 /dev/da2
726 Enter passphrase: (enter security officer passphrase)
727 Enter new passphrase: (let your employee enter his passphrase ...)
728 Reenter new passphrase: (... twice)
731 You are the security-person in your company.
732 Create an encrypted provider for use by the user, but remember that users
733 forget their passphrases, so back Master Key up with your own random key:
734 .Bd -literal -offset indent
735 # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
736 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ad0s1e
737 # geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
738 (use key number 0, so the encrypted Master Key by you will be overwritten)
739 # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
740 (allow the user to enter his passphrase)
741 Enter new passphrase:
742 Reenter new passphrase:
745 Encrypted swap partition setup:
746 .Bd -literal -offset indent
747 # dd if=/dev/random of=/dev/ad0s1b bs=1m
748 # geli onetime -d -e 3des ad0s1b
749 # swapon /dev/ad0s1b.eli
752 The example below shows how to configure two providers which will be attached
753 on boot (before the root file system is mounted).
754 One of them is using passphrase and three keyfiles and the other is using only a
756 .Bd -literal -offset indent
757 # dd if=/dev/random of=/dev/da0 bs=1m
758 # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
759 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
760 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
761 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
762 Enter new passphrase:
763 Reenter new passphrase:
764 # dd if=/dev/random of=/dev/da1s3a bs=1m
765 # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
766 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a
769 The providers are initialized, now we have to add those lines to
770 .Pa /boot/loader.conf :
771 .Bd -literal -offset indent
772 geli_da0_keyfile0_load="YES"
773 geli_da0_keyfile0_type="da0:geli_keyfile0"
774 geli_da0_keyfile0_name="/boot/keys/da0.key0"
775 geli_da0_keyfile1_load="YES"
776 geli_da0_keyfile1_type="da0:geli_keyfile1"
777 geli_da0_keyfile1_name="/boot/keys/da0.key1"
778 geli_da0_keyfile2_load="YES"
779 geli_da0_keyfile2_type="da0:geli_keyfile2"
780 geli_da0_keyfile2_name="/boot/keys/da0.key2"
782 geli_da1s3a_keyfile0_load="YES"
783 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
784 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
787 Not only configure encryption, but also data integrity verification using
789 .Bd -literal -offset indent
790 # geli init -a hmac/sha256 -s 4096 /dev/da0
791 Enter new passphrase:
792 Reenter new passphrase:
793 # geli attach /dev/da0
795 # dd if=/dev/random of=/dev/da0.eli bs=1m
797 # mount /dev/da0.eli /mnt/secret
801 backups metadata by default to the
802 .Pa /var/backups/<prov>.eli
804 If metadata is lost in any way (eg. by accidental overwrite), it can be restored.
805 Consider the following situation:
806 .Bd -literal -offset indent
808 Enter new passphrase:
809 Reenter new passphrase:
811 Metadata backup can be found in /var/backups/da0.eli and
812 can be restored with the following command:
814 # geli restore /var/backups/da0.eli /dev/da0
816 # geli clear /dev/da0
817 # geli attach /dev/da0
818 geli: Cannot read metadata from /dev/da0: Invalid argument.
819 # geli restore /var/backups/da0.eli /dev/da0
820 # geli attach /dev/da0
824 If an encrypted filesystem is extended, it is necessary to relocate and
826 .Bd -literal -offset indent
827 # gpart create -s GPT ada0
828 # gpart add -s 1g -t freebsd-ufs -i 1 ada0
829 # geli init -K keyfile -P ada0p1
830 # gpart resize -s 2g -i 1 ada0
831 # geli resize -s 1g ada0p1
832 # geli attach -k keyfile -p ada0p1
835 Initialize provider with passphrase split into two files.
836 The provider can be attached by giving those two files or by giving
841 .Bd -literal -offset indent
842 # echo foo > da0.pass0
843 # echo bar > da0.pass1
844 # geli init -J da0.pass0 -J da0.pass1 da0
845 # geli attach -j da0.pass0 -j da0.pass1 da0
848 Enter passphrase: foobar
853 devices, suspend a laptop, then resume devices one by one after resuming a
855 .Bd -literal -offset indent
859 # geli resume -p -k keyfile gpt/secret
860 # geli resume gpt/private
865 supports two encryption modes:
867 which was standardized as
871 with unpredictable IV.
876 is very similar to the mode
878 .Sh DATA AUTHENTICATION
880 can verify data integrity when an authentication algorithm is specified.
881 When data corruption/modification is detected,
883 will not return any data, but instead will return an error
885 The offset and size of the corrupted data will be printed on the console.
886 It is important to know against which attacks
888 provides protection for your data.
889 If data is modified in-place or copied from one place on the disk
890 to another even without modification,
892 should be able to detect such a change.
893 If an attacker can remember the encrypted data, he can overwrite any future
894 changes with the data he owns without notice.
897 will not protect your data against replay attacks.
899 It is recommended to write the whole provider before the first use,
900 in order to make sure that all sectors and their corresponding
901 checksums are properly initialized into a consistent state.
902 One can safely ignore data authentication errors that occur immediately
903 after the first time a provider is attached and before it is
904 initialized in this way.
920 block cipher is implemented by Yoshisato Yanagisawa in
923 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
projects / FreeBSD / releng / 9.2.git / blob