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