1 .\" Copyright (c) 2005-2019 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 the cryptographic GEOM class"
34 To compile GEOM_ELI into your kernel, add the following lines to your kernel
36 .Bd -ragged -offset indent
38 .Cd "options GEOM_ELI"
41 Alternatively, to load the GEOM_ELI module at boot time, add 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
66 .Cm label - an alias for
80 .Cm stop - an alias for
88 .Op Fl s Ar sectorsize
97 .Op Fl i Ar iterations
99 .Op Fl J Ar newpassfile
101 .Op Fl K Ar newkeyfile
160 utility is used to configure encryption on GEOM providers.
162 The following is a list of the most important features:
164 .Bl -bullet -offset indent -compact
168 framework, so when there is crypto hardware available,
170 will make use of it automatically.
172 Supports many cryptographic algorithms (currently
180 Can optionally perform data authentication (integrity verification) utilizing
181 one of the following algorithms:
190 Can create a User Key from up to two, piecewise components: a passphrase
191 entered via prompt or read from one or more passfiles; a keyfile read from
194 Allows encryption of the root partition.
195 The user is asked for the passphrase before the root filesystem is mounted.
197 Strengthens the passphrase component of the User Key with:
200 .%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
205 Allows the use of two independent User Keys (e.g., a
208 .Qq "company key" ) .
212 performs simple sector-to-sector encryption.
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
219 Providers can be configured to automatically detach on last close,
220 so users do not have to remember to detach providers after unmounting
223 Allows attaching a provider with a random, one-time Master Key,
224 which is useful for swap partitions and temporary filesystems.
226 Allows verification of data integrity (data authentication).
228 Allows suspending and resuming encrypted devices.
231 The first argument to
233 indicates an action to be performed:
234 .Bl -tag -width ".Cm configure"
236 Initialize providers which need to be encrypted.
237 If multiple providers are listed as arguments, they will all be initialized
238 with the same passphrase and/or User Key.
239 A unique salt will be randomly generated for each provider to ensure the
240 Master Key for each is unique.
241 Here you can set up the cryptographic algorithm to use, Data Key length,
243 The last sector of the providers is used to store metadata.
246 subcommand also automatically writes metadata backups to
247 .Pa /var/backups/<prov>.eli
249 The metadata can be recovered with the
251 subcommand described below.
253 Additional options include:
254 .Bl -tag -width ".Fl J Ar newpassfile"
256 Enable data integrity verification (authentication) using the given algorithm.
257 This will reduce the size of storage available and also reduce speed.
258 For example, when using 4096 bytes sector and
260 algorithm, 89% of the original provider storage will be available for use.
261 Currently supported algorithms are:
269 If the option is not given, there will be no authentication, only encryption.
270 The recommended algorithm is
273 Try to decrypt this partition during boot, before the root partition is mounted.
274 This makes it possible to use an encrypted root partition.
275 One will still need bootable unencrypted storage with a
277 directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
279 .It Fl B Ar backupfile
280 File name to use for metadata backup instead of the default
281 .Pa /var/backups/<prov>.eli .
282 To inhibit backups, you can use
286 If multiple providers were initialized in the one command, you can use
288 (all upper-case) in the file name, and it will be replaced with the provider
292 is not found in the file name and multiple providers were initialized in the
295 will be appended to the end of the file name specified.
297 When entering the passphrase to boot from this encrypted root filesystem, echo
300 This makes the length of the passphrase visible.
302 Encryption algorithm to use.
303 Currently supported algorithms are:
311 The default and recommended algorithm is
316 Enable booting from this encrypted root filesystem.
317 The boot loader prompts for the passphrase and loads
319 from the encrypted partition.
320 .It Fl i Ar iterations
321 Number of iterations to use with PKCS#5v2 when processing User Key
322 passphrase component.
323 If this option is not specified,
325 will find the number of iterations which is equal to 2 seconds of crypto work.
326 If 0 is given, PKCS#5v2 will not be used.
327 PKCS#5v2 processing is performed once, after all parts of the passphrase
328 component have been read.
329 .It Fl J Ar newpassfile
330 Specifies a file which contains the passphrase component of the User Key
334 is given as -, standard input will be used.
335 Only the first line (excluding new-line character) is taken from the given file.
336 This argument can be specified multiple times, which has the effect of
337 reassembling a single passphrase split across multiple files.
338 Cannot be combined with the
341 .It Fl K Ar newkeyfile
342 Specifies a file which contains the keyfile component of the User Key
346 is given as -, standard input will be used.
347 This argument can be specified multiple times, which has the effect of
348 reassembling a single keyfile split across multiple keyfile parts.
350 Data Key length to use with the given cryptographic algorithm.
351 If the length is not specified, the selected algorithm uses its
354 .Bl -ohang -offset indent
358 .It Nm AES-CBC , Nm Camellia-CBC
364 + n * 32, for n=[0..10]
369 Do not use a passphrase as a component of the User Key.
370 Cannot be combined with the
373 .It Fl s Ar sectorsize
374 Change decrypted provider's sector size.
375 Increasing the sector size allows increased performance,
376 because encryption/decryption which requires an initialization vector
377 is done per sector; fewer sectors means less computational work.
379 Turn off automatic expansion.
380 By default, if the underlying provider grows, the encrypted provider will
381 grow automatically too.
382 The metadata will be moved to the new location.
383 If automatic expansion if turned off and the underlying provider changes
384 size, attaching encrypted provider will no longer be possible as the metadata
385 will no longer be located in the last sector.
388 will only log the previous size of the underlying provider, so metadata can
389 be found easier, if resize was done by mistake.
393 calls (i.e., TRIM/UNMAP).
394 This can prevent an attacker from knowing how much space you're actually
395 using and which sectors contain live data, but will also prevent the
396 backing store (SSD, etc) from reclaiming space you're not using, which
397 may degrade its performance and lifespan.
398 The underlying provider may or may not actually obliterate the deleted
399 sectors when TRIM is enabled, so it should not be considered to add any
402 Metadata version to use.
403 This option is helpful when creating a provider that may be used by older
408 section to find which metadata version is supported by which
411 Note that using an older version of metadata may limit the number of
415 Attach the given providers.
416 The encrypted Master Keys are loaded from the metadata and decrypted
417 using the given passphrase/keyfile and new GEOM providers are created
418 using the specified provider names.
421 suffix is added to the user specified provider names.
422 Multiple providers can only be attached with a single
424 command if they all have the same passphrase and keyfiles.
426 Additional options include:
427 .Bl -tag -width ".Fl j Ar passfile"
429 Do a dry-run decryption.
430 This is useful to verify passphrase and keyfile without decrypting the device.
432 If specified, the decrypted providers are detached automatically on last close,
433 so the user does not have to remember to detach
434 providers after unmounting the filesystems.
435 This only works when providers were opened for writing, and will not work if
436 the filesystems on the providers were mounted read-only.
437 Probably a better choice is the
443 Specifies the index number of the Master Key copy to use (could be 0 or 1).
444 If the index number is not provided all keys will be tested.
446 Specifies a file which contains the passphrase component of the User Key
448 For more information see the description of the
453 The same passfiles are used for all listed providers.
455 Specifies a file which contains the keyfile component of the User Key
457 For more information see the description of the
462 The same keyfiles are used for all listed providers.
464 Do not use a passphrase as a component of the User Keys.
465 Cannot be combined with the
469 Attach read-only providers.
470 They are not opened for writing.
473 Detach the given providers, which means remove the devfs entry
474 and clear the Master Key and Data Keys from memory.
476 Additional options include:
477 .Bl -tag -width ".Fl f"
479 Force detach - detach even if the provider is open.
481 Mark provider to detach on last close, after the last filesystem has been
483 If this option is specified, the provider will not be detached
484 while it is open, but will be automatically detached when it is closed for the
485 last time even if it was only opened for reading.
488 Attach the given providers with a random, one-time (ephemeral) Master Key.
489 The command can be used to encrypt swap partitions or temporary filesystems.
491 Additional options include:
492 .Bl -tag -width ".Fl a Ar sectorsize"
494 Enable data integrity verification (authentication).
495 For more information, see the description of the
499 Encryption algorithm to use.
500 For more information, see the description of the
504 Detach on last close, after the last filesystem has been unmounted.
505 Note: this option is not usable for temporary filesystems as the provider is
506 detached after the filesystem has been created.
507 It still can, and should, be used for swap partitions.
508 For more information, see the description of the
512 Data Key length to use with the given cryptographic algorithm.
513 For more information, see the description of the
516 .It Fl s Ar sectorsize
517 Change decrypted provider's sector size.
518 For more information, see the description of the
522 Turn off automatic expansion.
523 For more information, see the description of the
527 Disable TRIM/UNMAP passthru.
528 For more information, see the description of the
533 Change configuration of the given providers.
535 Additional options include:
536 .Bl -tag -width ".Fl b"
538 Set the BOOT flag on the given providers.
539 For more information, see the description of the
543 Remove the BOOT flag from the given providers.
545 When entering the passphrase to boot from this encrypted root filesystem, echo
548 This makes the length of the passphrase visible.
550 Disable echoing of any characters when a passphrase is entered to boot from this
551 encrypted root filesystem.
552 This hides the passphrase length.
554 Enable booting from this encrypted root filesystem.
555 The boot loader prompts for the passphrase and loads
557 from the encrypted partition.
559 Deactivate booting from this encrypted root partition.
561 Turn on automatic expansion.
562 For more information, see the description of the
566 Turn off automatic expansion.
568 Enable TRIM/UNMAP passthru.
569 For more information, see the description of the
573 Disable TRIM/UNMAP passthru.
576 Install a copy of the Master Key into the selected slot, encrypted with
578 If the selected slot is populated, replace the existing copy.
579 A provider has one Master Key, which can be stored in one or both slots,
580 each encrypted with an independent User Key.
583 subcommand, only key number 0 is initialized.
584 The User Key can be changed at any time: for an attached provider,
585 for a detached provider, or on the backup file.
586 When a provider is attached, the user does not have to provide
587 an existing passphrase/keyfile.
589 Additional options include:
590 .Bl -tag -width ".Fl J Ar newpassfile"
591 .It Fl i Ar iterations
592 Number of iterations to use with PKCS#5v2.
593 If 0 is given, PKCS#5v2 will not be used.
594 To be able to use this option with the
596 subcommand, only one key has to be defined and this key must be changed.
598 Specifies a file which contains the passphrase component of a current User Key
600 .It Fl J Ar newpassfile
601 Specifies a file which contains the passphrase component of the new User Key
604 Specifies a file which contains the keyfile component of a current User Key
606 .It Fl K Ar newkeyfile
607 Specifies a file which contains the keyfile component of the new User Key
610 Specifies the index number of the Master Key copy to change (could be 0 or 1).
611 If the provider is attached and no key number is given, the key
612 used for attaching the provider will be changed.
613 If the provider is detached (or we are operating on a backup file)
614 and no key number is given, the first Master Key copy to be successfully
615 decrypted with the provided User Key passphrase/keyfile will be changed.
617 Do not use a passphrase as a component of the current User Key.
618 Cannot be combined with the
622 Do not use a passphrase as a component of the new User Key.
623 Cannot be combined with the
628 Destroy (overwrite with random data) the selected Master Key copy.
629 If one is destroying keys for an attached provider, the provider
630 will not be detached even if all copies of the Master Key are destroyed.
631 It can even be rescued with the
633 subcommand because the Master Key is still in memory.
635 Additional options include:
636 .Bl -tag -width ".Fl a Ar keyno"
638 Destroy all copies of the Master Key (does not need
642 Force key destruction.
643 This option is needed to destroy the last copy of the Master Key.
645 Specifies the index number of the Master Key copy.
646 If the provider is attached and no key number is given, the key
647 used for attaching the provider will be destroyed.
648 If provider is detached (or we are operating on a backup file) the key number
652 This command should be used only in emergency situations.
653 It will destroy all copies of the Master Key on a given provider and will
654 detach it forcibly (if it is attached).
655 This is absolutely a one-way command - if you do not have a metadata
656 backup, your data is gone for good.
657 In case the provider was attached with the
659 flag, the keys will not be destroyed, only the provider will be detached.
661 Additional options include:
662 .Bl -tag -width ".Fl a"
664 If specified, all currently attached providers will be killed.
667 Backup metadata from the given provider to the given file.
669 Restore metadata from the given file to the given provider.
671 Additional options include:
672 .Bl -tag -width ".Fl f"
674 Metadata contains the size of the provider to ensure that the correct
675 partition or slice is attached.
676 If an attempt is made to restore metadata to a provider that has a different
679 will refuse to restore the data unless the
682 If the partition or slice has been grown, the
684 subcommand should be used rather than attempting to relocate the metadata
691 Suspend device by waiting for all inflight requests to finish, clearing all
692 sensitive information such as the Master Key and Data Keys from kernel memory,
693 and blocking all further I/O requests until the
695 subcommand is executed.
696 This functionality is useful for laptops.
697 Suspending a laptop should not leave an encrypted device attached.
700 subcommand can be used rather than closing all files and directories from
701 filesystems on the encrypted device, unmounting the filesystem, and
702 detaching the device.
703 Any access to the encrypted device will be blocked until the Master Key is
707 Thus there is no need to close nor unmount anything.
710 subcommand does not work with devices created with the
713 Please note that sensitive data might still be present in memory locations
714 such as the filesystem cache after suspending an encrypted device.
716 Additional options include:
717 .Bl -tag -width ".Fl a"
724 Resume previously suspended device.
725 The caller must ensure that executing this subcommand does not access the
726 suspended device, leading to a deadlock.
727 For example, suspending a device which contains the filesystem where the
729 utility is stored is a bad idea.
731 Additional options include:
732 .Bl -tag -width ".Fl j Ar passfile"
734 Specifies a file which contains the passphrase component of the User Key,
736 For more information see the description of the
742 Specifies a file which contains the keyfile component of the User Key,
744 For more information see the description of the
750 Do not use a passphrase as a component of the User Key.
751 Cannot be combined with the
758 that the provider has been resized.
759 The old metadata block is relocated to the correct position at the end of the
760 provider and the provider size is updated.
762 Additional options include:
763 .Bl -tag -width ".Fl s Ar oldsize"
765 The size of the provider before it was resized.
768 If no arguments are given, the
770 subcommand will print the version of
772 userland utility as well as the version of the
776 If GEOM providers are specified, the
778 subcommand will print metadata version used by each of them.
780 Clear metadata from the given providers.
782 This will erase with zeros the encrypted Master Key copies stored in the
785 Dump metadata stored on the given providers.
800 Additional options include:
801 .Bl -tag -width ".Fl v"
811 utility generates a random Master Key for the provider.
812 The Master Key never changes during the lifetime of the provider.
813 Each copy of the provider metadata, active or backed up to a file, can store
814 up to two, independently-encrypted copies of the Master Key.
816 Each stored copy of the Master Key is encrypted with a User Key, which
819 utility from a passphrase and/or a keyfile.
822 utility first reads all parts of the keyfile in the order specified on the
823 command line, then reads all parts of the stored passphrase in the order
824 specified on the command line.
825 If no passphrase parts are specified, the system prompts the user to enter
827 The passphrase is optionally strengthened by PKCS#5v2.
828 The User Key is a digest computed over the concatenated keyfile and passphrase.
830 During operation, one or more Data Keys are deterministically derived by
831 the kernel from the Master Key and cached in memory.
832 The number of Data Keys used by a given provider, and the way they are
833 derived, depend on the GELI version and whether the provider is configured to
834 use data authentication.
838 variables can be used to control the behavior of the
841 The default value is shown next to each variable.
842 Some variables can also be set in
843 .Pa /boot/loader.conf .
844 .Bl -tag -width indent
845 .It Va kern.geom.eli.version
846 Version number of the
849 .It Va kern.geom.eli.debug : No 0
853 This can be set to a number between 0 and 3 inclusive.
854 If set to 0, minimal debug information is printed.
856 maximum amount of debug information is printed.
857 .It Va kern.geom.eli.tries : No 3
858 Number of times a user is asked for the passphrase.
859 This is only used for providers which are attached on boot,
860 before the root filesystem is mounted.
861 If set to 0, attaching providers on boot will be disabled.
862 This variable should be set in
863 .Pa /boot/loader.conf .
864 .It Va kern.geom.eli.overwrites : No 5
865 Specifies how many times the Master Key is overwritten
866 with random values when it is destroyed.
867 After this operation it is filled with zeros.
868 .It Va kern.geom.eli.visible_passphrase : No 0
869 If set to 1, the passphrase entered on boot will be visible.
870 This alternative should be used with caution as the entered
871 passphrase can be logged and exposed via
873 This variable should be set in
874 .Pa /boot/loader.conf .
875 .It Va kern.geom.eli.threads : No 0
876 Specifies how many kernel threads should be used for doing software
878 Its purpose is to increase performance on SMP systems.
879 If set to 0, a CPU-pinned thread will be started for every active CPU.
880 .It Va kern.geom.eli.batch : No 0
881 When set to 1, can speed-up crypto operations by using batching.
882 Batching reduces the number of interrupts by responding to a group of
883 crypto requests with one interrupt.
884 The crypto card and the driver has to support this feature.
885 .It Va kern.geom.eli.key_cache_limit : No 8192
886 Specifies how many Data Keys to cache.
888 (8192 keys) will allow caching of all keys for a 4TB provider with 512 byte
889 sectors and will take around 1MB of memory.
890 .It Va kern.geom.eli.key_cache_hits
891 Reports how many times we were looking up a Data Key and it was already in
893 This sysctl is not updated for providers that need fewer Data Keys than
894 the limit specified in
895 .Va kern.geom.eli.key_cache_limit .
896 .It Va kern.geom.eli.key_cache_misses
897 Reports how many times we were looking up a Data Key and it was not in cache.
898 This sysctl is not updated for providers that need fewer Data Keys than the limit
900 .Va kern.geom.eli.key_cache_limit .
903 Exit status is 0 on success, and 1 if the command fails.
904 .Sh DEPRECATION NOTICE
909 cryptographic algorithms and
911 authentication algorithm will be removed in
913 New volumes cannot be created using these algorithms.
914 Existing volumes should be migrated to a new volume that uses
915 non-deprecated algorithms.
917 Initialize a provider which is going to be encrypted with a
918 passphrase and random data from a file on the user's pen drive.
920 Attach the provider, create a filesystem, and mount it.
922 Unmount the provider and detach it:
923 .Bd -literal -offset indent
924 # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
925 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
926 Enter new passphrase:
927 Reenter new passphrase:
928 # geli attach -k /mnt/pendrive/da2.key /dev/da2
930 # dd if=/dev/random of=/dev/da2.eli bs=1m
932 # mount /dev/da2.eli /mnt/secret
935 # geli detach da2.eli
938 Create an encrypted provider, but use two User Keys:
939 one for your employee and one for you as the company's security officer
940 (so it is not a tragedy if the employee
942 forgets his passphrase):
943 .Bd -literal -offset indent
945 Enter new passphrase: (enter security officer's passphrase)
946 Reenter new passphrase:
947 # geli setkey -n 1 /dev/da2
948 Enter passphrase: (enter security officer's passphrase)
949 Enter new passphrase: (let your employee enter his passphrase ...)
950 Reenter new passphrase: (... twice)
953 You are the security officer in your company.
954 Create an encrypted provider for use by the user, but remember that users
955 forget their passphrases, so backup the Master Key with your own random key:
956 .Bd -literal -offset indent
957 # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
958 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e
959 # geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname`
960 (use key number 0, so the encrypted Master Key will be re-encrypted by this)
961 # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e
962 (allow the user to enter his passphrase)
963 Enter new passphrase:
964 Reenter new passphrase:
967 Encrypted swap partition setup:
968 .Bd -literal -offset indent
969 # dd if=/dev/random of=/dev/ada0s1b bs=1m
970 # geli onetime -d -e 3des ada0s1b
971 # swapon /dev/ada0s1b.eli
974 The example below shows how to configure two providers which will be attached
975 on boot, before the root filesystem is mounted.
976 One of them is using passphrase and three keyfile parts and the other is
977 using only a keyfile in one part:
978 .Bd -literal -offset indent
979 # dd if=/dev/random of=/dev/da0 bs=1m
980 # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
981 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
982 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
983 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
984 Enter new passphrase:
985 Reenter new passphrase:
986 # dd if=/dev/random of=/dev/da1s3a bs=1m
987 # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
988 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a
991 The providers are initialized, now we have to add these lines to
992 .Pa /boot/loader.conf :
993 .Bd -literal -offset indent
994 geli_da0_keyfile0_load="YES"
995 geli_da0_keyfile0_type="da0:geli_keyfile0"
996 geli_da0_keyfile0_name="/boot/keys/da0.key0"
997 geli_da0_keyfile1_load="YES"
998 geli_da0_keyfile1_type="da0:geli_keyfile1"
999 geli_da0_keyfile1_name="/boot/keys/da0.key1"
1000 geli_da0_keyfile2_load="YES"
1001 geli_da0_keyfile2_type="da0:geli_keyfile2"
1002 geli_da0_keyfile2_name="/boot/keys/da0.key2"
1004 geli_da1s3a_keyfile0_load="YES"
1005 geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
1006 geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
1009 If there is only one keyfile, the index might be omitted:
1010 .Bd -literal -offset indent
1011 geli_da1s3a_keyfile_load="YES"
1012 geli_da1s3a_keyfile_type="da1s3a:geli_keyfile"
1013 geli_da1s3a_keyfile_name="/boot/keys/da1s3a.key"
1016 Not only configure encryption, but also data integrity verification using
1018 .Bd -literal -offset indent
1019 # geli init -a hmac/sha256 -s 4096 /dev/da0
1020 Enter new passphrase:
1021 Reenter new passphrase:
1022 # geli attach /dev/da0
1024 # dd if=/dev/random of=/dev/da0.eli bs=1m
1025 # newfs /dev/da0.eli
1026 # mount /dev/da0.eli /mnt/secret
1030 writes the metadata backup by default to the
1031 .Pa /var/backups/<prov>.eli
1033 If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored.
1034 Consider the following situation:
1035 .Bd -literal -offset indent
1036 # geli init /dev/da0
1037 Enter new passphrase:
1038 Reenter new passphrase:
1040 Metadata backup can be found in /var/backups/da0.eli and
1041 can be restored with the following command:
1043 # geli restore /var/backups/da0.eli /dev/da0
1045 # geli clear /dev/da0
1046 # geli attach /dev/da0
1047 geli: Cannot read metadata from /dev/da0: Invalid argument.
1048 # geli restore /var/backups/da0.eli /dev/da0
1049 # geli attach /dev/da0
1053 If an encrypted filesystem is extended, it is necessary to relocate and
1054 update the metadata:
1055 .Bd -literal -offset indent
1056 # gpart create -s GPT ada0
1057 # gpart add -s 1g -t freebsd-ufs -i 1 ada0
1058 # geli init -K keyfile -P ada0p1
1059 # gpart resize -s 2g -i 1 ada0
1060 # geli resize -s 1g ada0p1
1061 # geli attach -k keyfile -p ada0p1
1064 Initialize provider with the passphrase split into two files.
1065 The provider can be attached using those two files or by entering
1067 as the passphrase at the
1070 .Bd -literal -offset indent
1071 # echo foo > da0.pass0
1072 # echo bar > da0.pass1
1073 # geli init -J da0.pass0 -J da0.pass1 da0
1074 # geli attach -j da0.pass0 -j da0.pass1 da0
1077 Enter passphrase: foobar
1082 devices on a laptop, suspend the laptop, then resume devices one by one after
1083 resuming the laptop:
1084 .Bd -literal -offset indent
1087 <resume your laptop>
1088 # geli resume -p -k keyfile gpt/secret
1089 # geli resume gpt/private
1092 .Sh ENCRYPTION MODES
1094 supports two encryption modes:
1096 which was standardized as
1100 with unpredictable IV.
1105 is very similar to the mode
1107 .Sh DATA AUTHENTICATION
1109 can verify data integrity when an authentication algorithm is specified.
1110 When data corruption/modification is detected,
1112 will not return any data, but instead will return an error
1114 The offset and size of the corrupted data will be printed on the console.
1115 It is important to know against which attacks
1117 provides protection for your data.
1118 If data is modified in-place or copied from one place on the disk
1119 to another even without modification,
1121 should be able to detect such a change.
1122 If an attacker can remember the encrypted data, he can overwrite any future
1123 changes with the data he owns without it being noticed.
1126 will not protect your data against replay attacks.
1128 It is recommended to write to the whole provider before first use,
1129 in order to make sure that all sectors and their corresponding
1130 checksums are properly initialized into a consistent state.
1131 One can safely ignore data authentication errors that occur immediately
1132 after the first time a provider is attached and before it is
1133 initialized in this way.
1149 block cipher was implemented by Yoshisato Yanagisawa in
1154 metadata version supported by the given FreeBSD version:
1155 .Bl -column -offset indent ".Sy FreeBSD" ".Sy version"
1156 .It Sy FreeBSD Ta Sy GELI
1157 .It Sy version Ta Sy version
1180 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
projects / FreeBSD / FreeBSD.git / blob