1.\" Copyright (c) 2005-2010 Pawel Jakub Dawidek <pjd@FreeBSD.org>
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: head/sbin/geom/class/eli/geli.8 213172 2010-09-25 17:38:57Z pjd $
26.\"
27.Dd September 25, 2010
28.Dt GELI 8
29.Os
30.Sh NAME
31.Nm geli
32.Nd "control utility for cryptographic GEOM class"
33.Sh SYNOPSIS
34To compile GEOM_ELI into your kernel, place the following lines in your kernel
35configuration file:
36.Bd -ragged -offset indent
37.Cd "device crypto"
38.Cd "options GEOM_ELI"
39.Ed
40.Pp
41Alternately, to load the GEOM_ELI module at boot time, place the following line
42in your
43.Xr loader.conf 5 :
44.Bd -literal -offset indent
45geom_eli_load="YES"
46.Ed
47.Pp
48Usage of the
49.Xr geli 8
50utility:
51.Pp
52.Nm
53.Cm init
54.Op Fl bPv
55.Op Fl a Ar aalgo
56.Op Fl B Ar backupfile
57.Op Fl e Ar ealgo
58.Op Fl i Ar iterations
59.Op Fl J Ar newpassfile
60.Op Fl K Ar newkeyfile
61.Op Fl l Ar keylen
62.Op Fl s Ar sectorsize
63.Ar prov
64.Nm
65.Cm label - an alias for
66.Cm init
67.Nm
68.Cm attach
69.Op Fl dprv
70.Op Fl j Ar passfile
71.Op Fl k Ar keyfile
72.Ar prov
73.Nm
74.Cm detach
75.Op Fl fl
76.Ar prov ...
77.Nm
78.Cm stop - an alias for
79.Cm detach
80.Nm
81.Cm onetime
82.Op Fl d
83.Op Fl a Ar aalgo
84.Op Fl e Ar ealgo
85.Op Fl l Ar keylen
86.Op Fl s Ar sectorsize
87.Ar prov
88.Nm
89.Cm configure
90.Op Fl bB
91.Ar prov ...
92.Nm
93.Cm setkey
94.Op Fl pPv
95.Op Fl i Ar iterations
96.Op Fl j Ar passfile
97.Op Fl J Ar newpassfile
98.Op Fl k Ar keyfile
99.Op Fl K Ar newkeyfile
100.Op Fl n Ar keyno
101.Ar prov
102.Nm
103.Cm delkey
104.Op Fl afv
105.Op Fl n Ar keyno
106.Ar prov
107.Nm
108.Cm kill
109.Op Fl av
110.Op Ar prov ...
111.Nm
112.Cm backup
113.Op Fl v
114.Ar prov
115.Ar file
116.Nm
117.Cm restore
118.Op Fl fv
119.Ar file
120.Ar prov
121.Nm
122.Cm resize
123.Op Fl v
124.Fl s Ar oldsize
125.Ar prov
126.Nm
127.Cm clear
128.Op Fl v
129.Ar prov ...
130.Nm
131.Cm dump
132.Op Fl v
133.Ar prov ...
134.Nm
135.Cm list
136.Nm
137.Cm status
138.Nm
139.Cm load
140.Nm
141.Cm unload
142.Sh DESCRIPTION
143The
144.Nm
145utility is used to configure encryption on GEOM providers.
146.Pp
147The following is a list of the most important features:
148.Pp
149.Bl -bullet -offset indent -compact
150.It
151Utilizes the
152.Xr crypto 9
153framework, so when there is crypto hardware available,
154.Nm
155will make use of it automatically.
156.It
157Supports many cryptographic algorithms (currently
158.Nm AES-XTS ,
159.Nm AES-CBC ,
160.Nm Blowfish-CBC ,
161.Nm Camellia-CBC
162and
163.Nm 3DES-CBC ) .
164.It
165Can optionally perform data authentication (integrity verification) utilizing
166one of the following algorithms:
167.Nm HMAC/MD5 ,
168.Nm HMAC/SHA1 ,
169.Nm HMAC/RIPEMD160 ,
170.Nm HMAC/SHA256 ,
171.Nm HMAC/SHA384
172or
173.Nm HMAC/SHA512 .
174.It
175Can create a key from a couple of components (user entered passphrase, random
176bits from a file, etc.).
177.It
178Allows to encrypt the root partition - the user will be asked for the
179passphrase before the root file system is mounted.
180.It
181The passphrase of the user is strengthened with:
182.Rs
183.%A B. Kaliski
184.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
185.%R RFC
186.%N 2898
187.Re
188.It
189Allows to use two independent keys (e.g.
190.Qq "user key"
191and
192.Qq "company key" ) .
193.It
194It is fast -
195.Nm
196performs simple sector-to-sector encryption.
197.It
198Allows to backup/restore Master Keys, so when a user has to quickly
199destroy his keys,
200it is possible to get the data back by restoring keys from the backup.
201.It
202Providers can be configured to automatically detach on last close
203(so users do not have to remember to detach providers after unmounting
204the file systems).
205.It
206Allows to attach a provider with a random, one-time key - useful for swap
207partitions and temporary file systems.
208.It
209Allows to verify data integrity (data authentication).
210.El
211.Pp
212The first argument to
213.Nm
214indicates an action to be performed:
215.Bl -tag -width ".Cm configure"
216.It Cm init
217Initialize provider which needs to be encrypted.
218Here you can set up the cryptographic algorithm to use, key length, etc.
219The last provider's sector is used to store metadata.
220The
221.Cm init
222subcommand also automatically backups metadata in
223.Pa /var/backups/<prov>.eli
224file.
225The metadata can be recovered with the
226.Cm restore
227subcommand described below.
228.Pp
229Additional options include:
230.Bl -tag -width ".Fl J Ar newpassfile"
231.It Fl a Ar aalgo
232Enable data integrity verification (authentication) using the given algorithm.
233This will reduce size of available storage and also reduce speed.
234For example, when using 4096 bytes sector and
235.Nm HMAC/SHA256
236algorithm, 89% of the original provider storage will be available for use.
237Currently supported algorithms are:
238.Nm HMAC/MD5 ,
239.Nm HMAC/SHA1 ,
240.Nm HMAC/RIPEMD160 ,
241.Nm HMAC/SHA256 ,
242.Nm HMAC/SHA384
243and
244.Nm HMAC/SHA512 .
245If the option is not given, there will be no authentication, only encryption.
246The recommended algorithm is
247.Nm HMAC/SHA256 .
248.It Fl b
249Ask for the passphrase on boot, before the root partition is mounted.
250This makes it possible to use an encrypted root partition.
251One will still need bootable unencrypted storage with a
252.Pa /boot/
253directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
254after boot.
255.It Fl B Ar backupfile
256File name to use for metadata backup instead of the default
257.Pa /var/backups/<prov>.eli .
258To inhibit backups, you can use
259.Pa none
260as the
261.Ar backupfile .
262.It Fl e Ar ealgo
263Encryption algorithm to use.
264Currently supported algorithms are:
265.Nm AES-XTS ,
266.Nm AES-CBC ,
267.Nm Blowfish-CBC ,
268.Nm Camellia-CBC
269and
270.Nm 3DES-CBC .
271The default and recommended algorithm is
272.Nm AES-XTS .
273.It Fl i Ar iterations
274Number of iterations to use with PKCS#5v2.
275If this option is not specified,
276.Nm
277will find the number of iterations which is equal to 2 seconds of crypto work.
278If 0 is given, PKCS#5v2 will not be used.
279.It Fl J Ar newpassfile
280Specifies a file which contains the passphrase or its part.
281If
282.Ar newpassfile
283is given as -, standard input will be used.
284Only the first line (excluding new-line character) is taken from the given file.
285This argument can be specified multiple times.
286.It Fl K Ar newkeyfile
287Specifies a file which contains part of the key.
288If
289.Ar newkeyfile
290is given as -, standard input will be used.
291This argument can be specified multiple times.
292.It Fl l Ar keylen
293Key length to use with the given cryptographic algorithm.
294If not given, the default key length for the given algorithm is used, which is:
295128 for
296.Nm AES-XTS ,
297.Nm AES-CBC ,
298.Nm Blowfish-CBC
299and
300.Nm Camellia-CBC
301and 192 for
302.Nm 3DES-CBC .
303.It Fl P
304Do not use passphrase as the key component.
305.It Fl s Ar sectorsize
306Change decrypted provider's sector size.
307Increasing sector size allows to increase performance, because we need to
308generate an IV and do encrypt/decrypt for every single sector - less number
309of sectors means less work to do.
310.El
311.It Cm attach
312Attach the given provider.
313The master key will be decrypted using the given
314passphrase/keyfile and a new GEOM provider will be created using the given
315provider's name with an
316.Qq .eli
317suffix.
318.Pp
319Additional options include:
320.Bl -tag -width ".Fl j Ar passfile"
321.It Fl d
322If specified, a decrypted provider will be detached automatically on last close.
323This can help with short memory - user does not have to remember to detach the
324provider after unmounting the file system.
325It only works when the provider was opened for writing, so it will not work if
326the file system on the provider is mounted read-only.
327Probably a better choice is the
328.Fl l
329option for the
330.Cm detach
331subcommand.
332.It Fl j Ar passfile
333Specifies a file which contains the passphrase or its part.
334For more information see the description of the
335.Fl J
336option for the
337.Cm init
338subcommand.
339.It Fl k Ar keyfile
340Specifies a file which contains part of the key.
341For more information see the description of the
342.Fl K
343option for the
344.Cm init
345subcommand.
346.It Fl p
347Do not use passphrase as the key component.
348.It Fl r
349Attach read-only provider.
350It will not be opened for writing.
351.El
352.It Cm detach
353Detach the given providers, which means remove the devfs entry
354and clear the keys from memory.
355.Pp
356Additional options include:
357.Bl -tag -width ".Fl f"
358.It Fl f
359Force detach - detach even if the provider is open.
360.It Fl l
361Mark provider to detach on last close.
362If this option is specified, the provider will not be detached
363until it is open, but when it will be closed last time, it will
364be automatically detached (even
365if it was only opened for reading).
366.El
367.It Cm onetime
368Attach the given providers with random, one-time keys.
369The command can be used to encrypt swap partitions or temporary file systems.
370.Pp
371Additional options include:
372.Bl -tag -width ".Fl a Ar sectorsize"
373.It Fl a Ar aalgo
374Enable data integrity verification (authentication).
375For more information, see the description of the
376.Cm init
377subcommand.
378.It Fl e Ar ealgo
379Encryption algorithm to use.
380For more information, see the description of the
381.Cm init
382subcommand.
383.It Fl d
384Detach on last close.
385Note, the option is not usable for temporary file systems as the provider will
386be detached after creating the file system on it.
387It still can (and should be) used for swap partitions.
388For more information, see the description of the
389.Cm attach
390subcommand.
391.It Fl l Ar keylen
392Key length to use with the given cryptographic algorithm.
393For more information, see the description of the
394.Cm init
395subcommand.
396.It Fl s Ar sectorsize
397Change decrypted provider's sector size.
398For more information, see the description of the
399.Cm init
400subcommand.
401.El
402.It Cm configure
403Change configuration of the given providers.
404.Pp
405Additional options include:
406.Bl -tag -width ".Fl b"
407.It Fl b
408Set the BOOT flag on the given providers.
409For more information, see the description of the
410.Cm init
411subcommand.
412.It Fl B
413Remove the BOOT flag from the given providers.
414.El
415.It Cm setkey
416Change or setup (if not yet initialized) selected key.
417There is one master key, which can be encrypted with two independent user keys.
418With the
419.Cm init
420subcommand, only key number 0 is initialized.
421The key can always be changed: for an attached provider,
422for a detached provider or on the backup file.
423When a provider is attached, the user does not have to provide
424an old passphrase/keyfile.
425.Pp
426Additional options include:
427.Bl -tag -width ".Fl J Ar newpassfile"
428.It Fl i Ar iterations
429Number of iterations to use with PKCS#5v2.
430If 0 is given, PKCS#5v2 will not be used.
431To be able to use this option with
432.Cm setkey
433subcommand, only one key have to be defined and this key has to be changed.
434.It Fl j Ar passfile
435Specifies a file which contains the old passphrase or its part.
436.It Fl J Ar newpassfile
437Specifies a file which contains the new passphrase or its part.
438.It Fl k Ar keyfile
439Specifies a file which contains part of the old key.
440.It Fl K Ar newkeyfile
441Specifies a file which contains part of the new key.
442.It Fl n Ar keyno
443Specifies the number of the key to change (could be 0 or 1).
444If the provider is attached and no key number is given, the key
445used for attaching the provider will be changed.
446If the provider is detached (or we are operating on a backup file)
447and no key number is given, the key decrypted with the passphrase/keyfile
448will be changed.
449.It Fl p
450Do not use passphrase as the old key component.
451.It Fl P
452Do not use passphrase as the new key component.
453.El
454.It Cm delkey
455Destroy (overwrite with random data) the selected key.
456If one is destroying keys for an attached provider, the provider
457will not be detached even if all keys will be destroyed.
458It can be even rescued with the
459.Cm setkey
460subcommand.
461.Bl -tag -width ".Fl a Ar keyno"
462.It Fl a
463Destroy all keys (does not need
464.Fl f
465option).
466.It Fl f
467Force key destruction.
468This option is needed to destroy the last key.
469.It Fl n Ar keyno
470Specifies the key number.
471If the provider is attached and no key number is given, the key
472used for attaching the provider will be destroyed.
473If provider is detached (or we are operating on a backup file) the key number
474has to be given.
475.El
476.It Cm kill
477This command should be used in emergency situations.
478It will destroy all keys on the given provider and will detach it forcibly
479(if it is attached).
480This is absolutely a one-way command - if you do not have a metadata
481backup, your data is gone for good.
482In case the provider was attached with the
483.Fl r
484flag, the keys will not be destroyed, only the provider will be detached.
485.Bl -tag -width ".Fl a"
486.It Fl a
487If specified, all currently attached providers will be killed.
488.El
489.It Cm backup
490Backup metadata from the given provider to the given file.
491.It Cm restore
492Restore metadata from the given file to the given provider.
493.Bl -tag -width ".Fl f"
494.It Fl f
495Metadata contains the size of the provider to ensure that the correct
496partition or slice is attached.
497If an attempt is made to restore metadata to a provider that has a different
498size,
499.Nm
500will refuse to restore the data unless the
501.Fl f
502switch is used.
503If the partition or slice has been grown, the
504.Cm resize
505subcommand should be used rather than attempting to relocate the metadata
506through
507.Cm backup
508and
509.Cm restore .
510.El
511.It Cm resize
512Inform
513.Nm
514that the provider has been resized.
515The old metadata block is relocated to the correct position at the end of the
516provider and the provider size is updated.
517.Bl -tag -width ".Fl s Ar oldsize"
518.It Fl s Ar oldsize
519The size of the provider before it was resized.
520.El
521.It Cm clear
522Clear metadata from the given providers.
523.It Cm dump
524Dump metadata stored on the given providers.
525.It Cm list
526See
527.Xr geom 8 .
528.It Cm status
529See
530.Xr geom 8 .
531.It Cm load
532See
533.Xr geom 8 .
534.It Cm unload
535See
536.Xr geom 8 .
537.El
538.Pp
539Additional options include:
540.Bl -tag -width ".Fl v"
541.It Fl v
542Be more verbose.
543.El
544.Sh SYSCTL VARIABLES
545The following
546.Xr sysctl 8
547variables can be used to control the behavior of the
548.Nm ELI
549GEOM class.
550The default value is shown next to each variable.
551All variables can also be set in
552.Pa /boot/loader.conf .
553.Bl -tag -width indent
554.It Va kern.geom.eli.debug : No 0
555Debug level of the
556.Nm ELI
557GEOM class.
558This can be set to a number between 0 and 3 inclusive.
559If set to 0, minimal debug information is printed.
560If set to 3, the
561maximum amount of debug information is printed.
562.It Va kern.geom.eli.tries : No 3
563Number of times a user is asked for the passphrase.
564This is only used for providers which should be attached on boot
565(before the root file system is mounted).
566If set to 0, attaching providers on boot will be disabled.
567This variable should be set in
568.Pa /boot/loader.conf .
569.It Va kern.geom.eli.overwrites : No 5
570Specifies how many times the Master-Key will be overwritten
571with random values when it is destroyed.
572After this operation it is filled with zeros.
573.It Va kern.geom.eli.visible_passphrase : No 0
574If set to 1, the passphrase entered on boot (before the root
575file system is mounted) will be visible.
576This possibility should be used with caution as the entered
577passphrase can be logged and exposed via
578.Xr dmesg 8 .
579This variable should be set in
580.Pa /boot/loader.conf .
581.It Va kern.geom.eli.threads : No 0
582Specifies how many kernel threads should be used for doing software
583cryptography.
584Its purpose is to increase performance on SMP systems.
585If hardware acceleration is available, only one thread will be started.
586If set to 0, CPU-bound thread will be started for every active CPU.
587.It Va kern.geom.eli.batch : No 0
588When set to 1, can speed-up crypto operations by using batching.
589Batching allows to reduce number of interrupts by responding on a group of
590crypto requests with one interrupt.
591The crypto card and the driver has to support this feature.
592.El
593.Sh EXIT STATUS
594Exit status is 0 on success, and 1 if the command fails.
595.Sh EXAMPLES
596Initialize a provider which is going to be encrypted with a
597passphrase and random data from a file on the user's pen drive.
598Use 4kB sector size.
599Attach the provider, create a file system and mount it.
600Do the work.
601Unmount the provider and detach it:
602.Bd -literal -offset indent
603# dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
604# geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
605Enter new passphrase:
606Reenter new passphrase:
607# geli attach -k /mnt/pendrive/da2.key /dev/da2
608Enter passphrase:
609# dd if=/dev/random of=/dev/da2.eli bs=1m
610# newfs /dev/da2.eli
611# mount /dev/da2.eli /mnt/secret
612\&...
613# umount /mnt/secret
614# geli detach da2.eli
615.Ed
616.Pp
617Create an encrypted provider, but use two keys:
618one for your girlfriend and one for
619you (so there will be no tragedy if she forgets her passphrase):
620.Bd -literal -offset indent
621# geli init /dev/da2
622Enter new passphrase: (enter your passphrase)
623Reenter new passphrase:
624# geli setkey -n 1 /dev/da2
625Enter passphrase: (enter your passphrase)
626Enter new passphrase: (let your girlfriend enter her passphrase ...)
627Reenter new passphrase: (... twice)
628.Ed
629.Pp
630You are the security-person in your company.
631Create an encrypted provider for use by the user, but remember that users
632forget their passphrases, so back Master Key up with your own random key:
633.Bd -literal -offset indent
634# dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
635# geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ad0s1e
636# geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
637(use key number 0, so the encrypted Master Key by you will be overwritten)
638# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
639(allow the user to enter his passphrase)
640Enter new passphrase:
641Reenter new passphrase:
642.Ed
643.Pp
644Encrypted swap partition setup:
645.Bd -literal -offset indent
646# dd if=/dev/random of=/dev/ad0s1b bs=1m
647# geli onetime -d -e 3des ad0s1b
648# swapon /dev/ad0s1b.eli
649.Ed
650.Pp
651The example below shows how to configure two providers which will be attached
652on boot (before the root file system is mounted).
653One of them is using passphrase and three keyfiles and the other is using only a
654keyfile:
655.Bd -literal -offset indent
656# dd if=/dev/random of=/dev/da0 bs=1m
657# dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
658# dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
659# dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
660# geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
661Enter new passphrase:
662Reenter new passphrase:
663# dd if=/dev/random of=/dev/da1s3a bs=1m
664# dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
665# geli init -b -P -K /boot/keys/da1s3a.key da1s3a
666.Ed
667.Pp
668The providers are initialized, now we have to add those lines to
669.Pa /boot/loader.conf :
670.Bd -literal -offset indent
671geli_da0_keyfile0_load="YES"
672geli_da0_keyfile0_type="da0:geli_keyfile0"
673geli_da0_keyfile0_name="/boot/keys/da0.key0"
674geli_da0_keyfile1_load="YES"
675geli_da0_keyfile1_type="da0:geli_keyfile1"
676geli_da0_keyfile1_name="/boot/keys/da0.key1"
677geli_da0_keyfile2_load="YES"
678geli_da0_keyfile2_type="da0:geli_keyfile2"
679geli_da0_keyfile2_name="/boot/keys/da0.key2"
680
681geli_da1s3a_keyfile0_load="YES"
682geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
683geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
684.Ed
685.Pp
686Not only configure encryption, but also data integrity verification using
687.Nm HMAC/SHA256 .
688.Bd -literal -offset indent
689# geli init -a hmac/sha256 -s 4096 /dev/da0
690Enter new passphrase:
691Reenter new passphrase:
692# geli attach /dev/da0
693Enter passphrase:
694# dd if=/dev/random of=/dev/da0.eli bs=1m
695# newfs /dev/da0.eli
696# mount /dev/da0.eli /mnt/secret
697.Ed
698.Pp
699.Cm geli
700backups metadata by default to the
701.Pa /var/backups/<prov>.eli
702file.
703If metadata is lost in any way (eg. by accidental overwrite), it can be restored.
704Consider the following situation:
705.Bd -literal -offset indent
706# geli init /dev/da0
707Enter new passphrase:
708Reenter new passphrase:
709
710Metadata backup can be found in /var/backups/da0.eli and
711can be restored with the following command:
712
713 # geli restore /var/backups/da0.eli /dev/da0
714
715# geli clear /dev/da0
716# geli attach /dev/da0
717geli: Cannot read metadata from /dev/da0: Invalid argument.
718# geli restore /var/backups/da0.eli /dev/da0
719# geli attach /dev/da0
720Enter passphrase:
721.Ed
722.Pp
723If an encrypted filesystem is extended, it is necessary to relocate and
724update the metadata:
725.Bd -literal -offset indent
726# gpart create -s GPT ada0
727# gpart add -s 1g -t freebsd-ufs -i 1 ada0
728# geli init -K keyfile -P ada0p1
729# gpart resize -s 2g -i 1 ada0
730# geli resize -s 1g ada0p1
731# geli attach -k keyfile -p ada0p1
732.Ed
733.Pp
734Initialize provider with passphrase split into two files.
735The provider can be attached by giving those two files or by giving
736.Dq foobar
737passphrase on
738.Nm
739prompt:
740.Bd -literal -offset indent
741# echo foo > da0.pass0
742# echo bar > da0.pass1
743# geli init -J da0.pass0 -J da0.pass1 da0
744# geli attach -j da0.pass0 -j da0.pass1 da0
745# geli detach da0
746# geli attach da0
747Enter passphrase: foobar
748.Ed
749.Sh ENCRYPTION MODES
750.Nm
751supports two encryption modes:
752.Nm XTS ,
753which was standarized as
754.Nm IEE P1619
755and
756.Nm CBC
757with unpredictable IV.
758The
759.Nm CBC
760mode used by
761.Nm
762is very similar to the mode
763.Nm ESSIV .
764.Sh DATA AUTHENTICATION
765.Nm
766can verify data integrity when an authentication algorithm is specified.
767When data corruption/modification is detected,
768.Nm
769will not return any data, but instead will return an error
770.Pq Er EINVAL .
771The offset and size of the corrupted data will be printed on the console.
772It is important to know against which attacks
773.Nm
774provides protection for your data.
775If data is modified in-place or copied from one place on the disk
776to another even without modification,
777.Nm
778should be able to detect such a change.
779If an attacker can remember the encrypted data, he can overwrite any future
780changes with the data he owns without notice.
781In other words
782.Nm
783will not protect your data against replay attacks.
784.Sh SEE ALSO
785.Xr crypto 4 ,
786.Xr gbde 4 ,
787.Xr geom 4 ,
788.Xr loader.conf 5 ,
789.Xr gbde 8 ,
790.Xr geom 8 ,
791.Xr crypto 9
792.Sh HISTORY
793The
794.Nm
795utility appeared in
796.Fx 6.0 .
797Support for
798.Nm Camellia
799block cipher is implemented by Yoshisato Yanagisawa in
800.Fx 7.0 .
801.Sh AUTHORS
802.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
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: head/sbin/geom/class/eli/geli.8 213172 2010-09-25 17:38:57Z pjd $
26.\"
27.Dd September 25, 2010
28.Dt GELI 8
29.Os
30.Sh NAME
31.Nm geli
32.Nd "control utility for cryptographic GEOM class"
33.Sh SYNOPSIS
34To compile GEOM_ELI into your kernel, place the following lines in your kernel
35configuration file:
36.Bd -ragged -offset indent
37.Cd "device crypto"
38.Cd "options GEOM_ELI"
39.Ed
40.Pp
41Alternately, to load the GEOM_ELI module at boot time, place the following line
42in your
43.Xr loader.conf 5 :
44.Bd -literal -offset indent
45geom_eli_load="YES"
46.Ed
47.Pp
48Usage of the
49.Xr geli 8
50utility:
51.Pp
52.Nm
53.Cm init
54.Op Fl bPv
55.Op Fl a Ar aalgo
56.Op Fl B Ar backupfile
57.Op Fl e Ar ealgo
58.Op Fl i Ar iterations
59.Op Fl J Ar newpassfile
60.Op Fl K Ar newkeyfile
61.Op Fl l Ar keylen
62.Op Fl s Ar sectorsize
63.Ar prov
64.Nm
65.Cm label - an alias for
66.Cm init
67.Nm
68.Cm attach
69.Op Fl dprv
70.Op Fl j Ar passfile
71.Op Fl k Ar keyfile
72.Ar prov
73.Nm
74.Cm detach
75.Op Fl fl
76.Ar prov ...
77.Nm
78.Cm stop - an alias for
79.Cm detach
80.Nm
81.Cm onetime
82.Op Fl d
83.Op Fl a Ar aalgo
84.Op Fl e Ar ealgo
85.Op Fl l Ar keylen
86.Op Fl s Ar sectorsize
87.Ar prov
88.Nm
89.Cm configure
90.Op Fl bB
91.Ar prov ...
92.Nm
93.Cm setkey
94.Op Fl pPv
95.Op Fl i Ar iterations
96.Op Fl j Ar passfile
97.Op Fl J Ar newpassfile
98.Op Fl k Ar keyfile
99.Op Fl K Ar newkeyfile
100.Op Fl n Ar keyno
101.Ar prov
102.Nm
103.Cm delkey
104.Op Fl afv
105.Op Fl n Ar keyno
106.Ar prov
107.Nm
108.Cm kill
109.Op Fl av
110.Op Ar prov ...
111.Nm
112.Cm backup
113.Op Fl v
114.Ar prov
115.Ar file
116.Nm
117.Cm restore
118.Op Fl fv
119.Ar file
120.Ar prov
121.Nm
122.Cm resize
123.Op Fl v
124.Fl s Ar oldsize
125.Ar prov
126.Nm
127.Cm clear
128.Op Fl v
129.Ar prov ...
130.Nm
131.Cm dump
132.Op Fl v
133.Ar prov ...
134.Nm
135.Cm list
136.Nm
137.Cm status
138.Nm
139.Cm load
140.Nm
141.Cm unload
142.Sh DESCRIPTION
143The
144.Nm
145utility is used to configure encryption on GEOM providers.
146.Pp
147The following is a list of the most important features:
148.Pp
149.Bl -bullet -offset indent -compact
150.It
151Utilizes the
152.Xr crypto 9
153framework, so when there is crypto hardware available,
154.Nm
155will make use of it automatically.
156.It
157Supports many cryptographic algorithms (currently
158.Nm AES-XTS ,
159.Nm AES-CBC ,
160.Nm Blowfish-CBC ,
161.Nm Camellia-CBC
162and
163.Nm 3DES-CBC ) .
164.It
165Can optionally perform data authentication (integrity verification) utilizing
166one of the following algorithms:
167.Nm HMAC/MD5 ,
168.Nm HMAC/SHA1 ,
169.Nm HMAC/RIPEMD160 ,
170.Nm HMAC/SHA256 ,
171.Nm HMAC/SHA384
172or
173.Nm HMAC/SHA512 .
174.It
175Can create a key from a couple of components (user entered passphrase, random
176bits from a file, etc.).
177.It
178Allows to encrypt the root partition - the user will be asked for the
179passphrase before the root file system is mounted.
180.It
181The passphrase of the user is strengthened with:
182.Rs
183.%A B. Kaliski
184.%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0."
185.%R RFC
186.%N 2898
187.Re
188.It
189Allows to use two independent keys (e.g.
190.Qq "user key"
191and
192.Qq "company key" ) .
193.It
194It is fast -
195.Nm
196performs simple sector-to-sector encryption.
197.It
198Allows to backup/restore Master Keys, so when a user has to quickly
199destroy his keys,
200it is possible to get the data back by restoring keys from the backup.
201.It
202Providers can be configured to automatically detach on last close
203(so users do not have to remember to detach providers after unmounting
204the file systems).
205.It
206Allows to attach a provider with a random, one-time key - useful for swap
207partitions and temporary file systems.
208.It
209Allows to verify data integrity (data authentication).
210.El
211.Pp
212The first argument to
213.Nm
214indicates an action to be performed:
215.Bl -tag -width ".Cm configure"
216.It Cm init
217Initialize provider which needs to be encrypted.
218Here you can set up the cryptographic algorithm to use, key length, etc.
219The last provider's sector is used to store metadata.
220The
221.Cm init
222subcommand also automatically backups metadata in
223.Pa /var/backups/<prov>.eli
224file.
225The metadata can be recovered with the
226.Cm restore
227subcommand described below.
228.Pp
229Additional options include:
230.Bl -tag -width ".Fl J Ar newpassfile"
231.It Fl a Ar aalgo
232Enable data integrity verification (authentication) using the given algorithm.
233This will reduce size of available storage and also reduce speed.
234For example, when using 4096 bytes sector and
235.Nm HMAC/SHA256
236algorithm, 89% of the original provider storage will be available for use.
237Currently supported algorithms are:
238.Nm HMAC/MD5 ,
239.Nm HMAC/SHA1 ,
240.Nm HMAC/RIPEMD160 ,
241.Nm HMAC/SHA256 ,
242.Nm HMAC/SHA384
243and
244.Nm HMAC/SHA512 .
245If the option is not given, there will be no authentication, only encryption.
246The recommended algorithm is
247.Nm HMAC/SHA256 .
248.It Fl b
249Ask for the passphrase on boot, before the root partition is mounted.
250This makes it possible to use an encrypted root partition.
251One will still need bootable unencrypted storage with a
252.Pa /boot/
253directory, which can be a CD-ROM disc or USB pen-drive, that can be removed
254after boot.
255.It Fl B Ar backupfile
256File name to use for metadata backup instead of the default
257.Pa /var/backups/<prov>.eli .
258To inhibit backups, you can use
259.Pa none
260as the
261.Ar backupfile .
262.It Fl e Ar ealgo
263Encryption algorithm to use.
264Currently supported algorithms are:
265.Nm AES-XTS ,
266.Nm AES-CBC ,
267.Nm Blowfish-CBC ,
268.Nm Camellia-CBC
269and
270.Nm 3DES-CBC .
271The default and recommended algorithm is
272.Nm AES-XTS .
273.It Fl i Ar iterations
274Number of iterations to use with PKCS#5v2.
275If this option is not specified,
276.Nm
277will find the number of iterations which is equal to 2 seconds of crypto work.
278If 0 is given, PKCS#5v2 will not be used.
279.It Fl J Ar newpassfile
280Specifies a file which contains the passphrase or its part.
281If
282.Ar newpassfile
283is given as -, standard input will be used.
284Only the first line (excluding new-line character) is taken from the given file.
285This argument can be specified multiple times.
286.It Fl K Ar newkeyfile
287Specifies a file which contains part of the key.
288If
289.Ar newkeyfile
290is given as -, standard input will be used.
291This argument can be specified multiple times.
292.It Fl l Ar keylen
293Key length to use with the given cryptographic algorithm.
294If not given, the default key length for the given algorithm is used, which is:
295128 for
296.Nm AES-XTS ,
297.Nm AES-CBC ,
298.Nm Blowfish-CBC
299and
300.Nm Camellia-CBC
301and 192 for
302.Nm 3DES-CBC .
303.It Fl P
304Do not use passphrase as the key component.
305.It Fl s Ar sectorsize
306Change decrypted provider's sector size.
307Increasing sector size allows to increase performance, because we need to
308generate an IV and do encrypt/decrypt for every single sector - less number
309of sectors means less work to do.
310.El
311.It Cm attach
312Attach the given provider.
313The master key will be decrypted using the given
314passphrase/keyfile and a new GEOM provider will be created using the given
315provider's name with an
316.Qq .eli
317suffix.
318.Pp
319Additional options include:
320.Bl -tag -width ".Fl j Ar passfile"
321.It Fl d
322If specified, a decrypted provider will be detached automatically on last close.
323This can help with short memory - user does not have to remember to detach the
324provider after unmounting the file system.
325It only works when the provider was opened for writing, so it will not work if
326the file system on the provider is mounted read-only.
327Probably a better choice is the
328.Fl l
329option for the
330.Cm detach
331subcommand.
332.It Fl j Ar passfile
333Specifies a file which contains the passphrase or its part.
334For more information see the description of the
335.Fl J
336option for the
337.Cm init
338subcommand.
339.It Fl k Ar keyfile
340Specifies a file which contains part of the key.
341For more information see the description of the
342.Fl K
343option for the
344.Cm init
345subcommand.
346.It Fl p
347Do not use passphrase as the key component.
348.It Fl r
349Attach read-only provider.
350It will not be opened for writing.
351.El
352.It Cm detach
353Detach the given providers, which means remove the devfs entry
354and clear the keys from memory.
355.Pp
356Additional options include:
357.Bl -tag -width ".Fl f"
358.It Fl f
359Force detach - detach even if the provider is open.
360.It Fl l
361Mark provider to detach on last close.
362If this option is specified, the provider will not be detached
363until it is open, but when it will be closed last time, it will
364be automatically detached (even
365if it was only opened for reading).
366.El
367.It Cm onetime
368Attach the given providers with random, one-time keys.
369The command can be used to encrypt swap partitions or temporary file systems.
370.Pp
371Additional options include:
372.Bl -tag -width ".Fl a Ar sectorsize"
373.It Fl a Ar aalgo
374Enable data integrity verification (authentication).
375For more information, see the description of the
376.Cm init
377subcommand.
378.It Fl e Ar ealgo
379Encryption algorithm to use.
380For more information, see the description of the
381.Cm init
382subcommand.
383.It Fl d
384Detach on last close.
385Note, the option is not usable for temporary file systems as the provider will
386be detached after creating the file system on it.
387It still can (and should be) used for swap partitions.
388For more information, see the description of the
389.Cm attach
390subcommand.
391.It Fl l Ar keylen
392Key length to use with the given cryptographic algorithm.
393For more information, see the description of the
394.Cm init
395subcommand.
396.It Fl s Ar sectorsize
397Change decrypted provider's sector size.
398For more information, see the description of the
399.Cm init
400subcommand.
401.El
402.It Cm configure
403Change configuration of the given providers.
404.Pp
405Additional options include:
406.Bl -tag -width ".Fl b"
407.It Fl b
408Set the BOOT flag on the given providers.
409For more information, see the description of the
410.Cm init
411subcommand.
412.It Fl B
413Remove the BOOT flag from the given providers.
414.El
415.It Cm setkey
416Change or setup (if not yet initialized) selected key.
417There is one master key, which can be encrypted with two independent user keys.
418With the
419.Cm init
420subcommand, only key number 0 is initialized.
421The key can always be changed: for an attached provider,
422for a detached provider or on the backup file.
423When a provider is attached, the user does not have to provide
424an old passphrase/keyfile.
425.Pp
426Additional options include:
427.Bl -tag -width ".Fl J Ar newpassfile"
428.It Fl i Ar iterations
429Number of iterations to use with PKCS#5v2.
430If 0 is given, PKCS#5v2 will not be used.
431To be able to use this option with
432.Cm setkey
433subcommand, only one key have to be defined and this key has to be changed.
434.It Fl j Ar passfile
435Specifies a file which contains the old passphrase or its part.
436.It Fl J Ar newpassfile
437Specifies a file which contains the new passphrase or its part.
438.It Fl k Ar keyfile
439Specifies a file which contains part of the old key.
440.It Fl K Ar newkeyfile
441Specifies a file which contains part of the new key.
442.It Fl n Ar keyno
443Specifies the number of the key to change (could be 0 or 1).
444If the provider is attached and no key number is given, the key
445used for attaching the provider will be changed.
446If the provider is detached (or we are operating on a backup file)
447and no key number is given, the key decrypted with the passphrase/keyfile
448will be changed.
449.It Fl p
450Do not use passphrase as the old key component.
451.It Fl P
452Do not use passphrase as the new key component.
453.El
454.It Cm delkey
455Destroy (overwrite with random data) the selected key.
456If one is destroying keys for an attached provider, the provider
457will not be detached even if all keys will be destroyed.
458It can be even rescued with the
459.Cm setkey
460subcommand.
461.Bl -tag -width ".Fl a Ar keyno"
462.It Fl a
463Destroy all keys (does not need
464.Fl f
465option).
466.It Fl f
467Force key destruction.
468This option is needed to destroy the last key.
469.It Fl n Ar keyno
470Specifies the key number.
471If the provider is attached and no key number is given, the key
472used for attaching the provider will be destroyed.
473If provider is detached (or we are operating on a backup file) the key number
474has to be given.
475.El
476.It Cm kill
477This command should be used in emergency situations.
478It will destroy all keys on the given provider and will detach it forcibly
479(if it is attached).
480This is absolutely a one-way command - if you do not have a metadata
481backup, your data is gone for good.
482In case the provider was attached with the
483.Fl r
484flag, the keys will not be destroyed, only the provider will be detached.
485.Bl -tag -width ".Fl a"
486.It Fl a
487If specified, all currently attached providers will be killed.
488.El
489.It Cm backup
490Backup metadata from the given provider to the given file.
491.It Cm restore
492Restore metadata from the given file to the given provider.
493.Bl -tag -width ".Fl f"
494.It Fl f
495Metadata contains the size of the provider to ensure that the correct
496partition or slice is attached.
497If an attempt is made to restore metadata to a provider that has a different
498size,
499.Nm
500will refuse to restore the data unless the
501.Fl f
502switch is used.
503If the partition or slice has been grown, the
504.Cm resize
505subcommand should be used rather than attempting to relocate the metadata
506through
507.Cm backup
508and
509.Cm restore .
510.El
511.It Cm resize
512Inform
513.Nm
514that the provider has been resized.
515The old metadata block is relocated to the correct position at the end of the
516provider and the provider size is updated.
517.Bl -tag -width ".Fl s Ar oldsize"
518.It Fl s Ar oldsize
519The size of the provider before it was resized.
520.El
521.It Cm clear
522Clear metadata from the given providers.
523.It Cm dump
524Dump metadata stored on the given providers.
525.It Cm list
526See
527.Xr geom 8 .
528.It Cm status
529See
530.Xr geom 8 .
531.It Cm load
532See
533.Xr geom 8 .
534.It Cm unload
535See
536.Xr geom 8 .
537.El
538.Pp
539Additional options include:
540.Bl -tag -width ".Fl v"
541.It Fl v
542Be more verbose.
543.El
544.Sh SYSCTL VARIABLES
545The following
546.Xr sysctl 8
547variables can be used to control the behavior of the
548.Nm ELI
549GEOM class.
550The default value is shown next to each variable.
551All variables can also be set in
552.Pa /boot/loader.conf .
553.Bl -tag -width indent
554.It Va kern.geom.eli.debug : No 0
555Debug level of the
556.Nm ELI
557GEOM class.
558This can be set to a number between 0 and 3 inclusive.
559If set to 0, minimal debug information is printed.
560If set to 3, the
561maximum amount of debug information is printed.
562.It Va kern.geom.eli.tries : No 3
563Number of times a user is asked for the passphrase.
564This is only used for providers which should be attached on boot
565(before the root file system is mounted).
566If set to 0, attaching providers on boot will be disabled.
567This variable should be set in
568.Pa /boot/loader.conf .
569.It Va kern.geom.eli.overwrites : No 5
570Specifies how many times the Master-Key will be overwritten
571with random values when it is destroyed.
572After this operation it is filled with zeros.
573.It Va kern.geom.eli.visible_passphrase : No 0
574If set to 1, the passphrase entered on boot (before the root
575file system is mounted) will be visible.
576This possibility should be used with caution as the entered
577passphrase can be logged and exposed via
578.Xr dmesg 8 .
579This variable should be set in
580.Pa /boot/loader.conf .
581.It Va kern.geom.eli.threads : No 0
582Specifies how many kernel threads should be used for doing software
583cryptography.
584Its purpose is to increase performance on SMP systems.
585If hardware acceleration is available, only one thread will be started.
586If set to 0, CPU-bound thread will be started for every active CPU.
587.It Va kern.geom.eli.batch : No 0
588When set to 1, can speed-up crypto operations by using batching.
589Batching allows to reduce number of interrupts by responding on a group of
590crypto requests with one interrupt.
591The crypto card and the driver has to support this feature.
592.El
593.Sh EXIT STATUS
594Exit status is 0 on success, and 1 if the command fails.
595.Sh EXAMPLES
596Initialize a provider which is going to be encrypted with a
597passphrase and random data from a file on the user's pen drive.
598Use 4kB sector size.
599Attach the provider, create a file system and mount it.
600Do the work.
601Unmount the provider and detach it:
602.Bd -literal -offset indent
603# dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1
604# geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2
605Enter new passphrase:
606Reenter new passphrase:
607# geli attach -k /mnt/pendrive/da2.key /dev/da2
608Enter passphrase:
609# dd if=/dev/random of=/dev/da2.eli bs=1m
610# newfs /dev/da2.eli
611# mount /dev/da2.eli /mnt/secret
612\&...
613# umount /mnt/secret
614# geli detach da2.eli
615.Ed
616.Pp
617Create an encrypted provider, but use two keys:
618one for your girlfriend and one for
619you (so there will be no tragedy if she forgets her passphrase):
620.Bd -literal -offset indent
621# geli init /dev/da2
622Enter new passphrase: (enter your passphrase)
623Reenter new passphrase:
624# geli setkey -n 1 /dev/da2
625Enter passphrase: (enter your passphrase)
626Enter new passphrase: (let your girlfriend enter her passphrase ...)
627Reenter new passphrase: (... twice)
628.Ed
629.Pp
630You are the security-person in your company.
631Create an encrypted provider for use by the user, but remember that users
632forget their passphrases, so back Master Key up with your own random key:
633.Bd -literal -offset indent
634# dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1
635# geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ad0s1e
636# geli backup /dev/ad0s1e /mnt/pendrive/backups/`hostname`
637(use key number 0, so the encrypted Master Key by you will be overwritten)
638# geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ad0s1e
639(allow the user to enter his passphrase)
640Enter new passphrase:
641Reenter new passphrase:
642.Ed
643.Pp
644Encrypted swap partition setup:
645.Bd -literal -offset indent
646# dd if=/dev/random of=/dev/ad0s1b bs=1m
647# geli onetime -d -e 3des ad0s1b
648# swapon /dev/ad0s1b.eli
649.Ed
650.Pp
651The example below shows how to configure two providers which will be attached
652on boot (before the root file system is mounted).
653One of them is using passphrase and three keyfiles and the other is using only a
654keyfile:
655.Bd -literal -offset indent
656# dd if=/dev/random of=/dev/da0 bs=1m
657# dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1
658# dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1
659# dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1
660# geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0
661Enter new passphrase:
662Reenter new passphrase:
663# dd if=/dev/random of=/dev/da1s3a bs=1m
664# dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1
665# geli init -b -P -K /boot/keys/da1s3a.key da1s3a
666.Ed
667.Pp
668The providers are initialized, now we have to add those lines to
669.Pa /boot/loader.conf :
670.Bd -literal -offset indent
671geli_da0_keyfile0_load="YES"
672geli_da0_keyfile0_type="da0:geli_keyfile0"
673geli_da0_keyfile0_name="/boot/keys/da0.key0"
674geli_da0_keyfile1_load="YES"
675geli_da0_keyfile1_type="da0:geli_keyfile1"
676geli_da0_keyfile1_name="/boot/keys/da0.key1"
677geli_da0_keyfile2_load="YES"
678geli_da0_keyfile2_type="da0:geli_keyfile2"
679geli_da0_keyfile2_name="/boot/keys/da0.key2"
680
681geli_da1s3a_keyfile0_load="YES"
682geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0"
683geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key"
684.Ed
685.Pp
686Not only configure encryption, but also data integrity verification using
687.Nm HMAC/SHA256 .
688.Bd -literal -offset indent
689# geli init -a hmac/sha256 -s 4096 /dev/da0
690Enter new passphrase:
691Reenter new passphrase:
692# geli attach /dev/da0
693Enter passphrase:
694# dd if=/dev/random of=/dev/da0.eli bs=1m
695# newfs /dev/da0.eli
696# mount /dev/da0.eli /mnt/secret
697.Ed
698.Pp
699.Cm geli
700backups metadata by default to the
701.Pa /var/backups/<prov>.eli
702file.
703If metadata is lost in any way (eg. by accidental overwrite), it can be restored.
704Consider the following situation:
705.Bd -literal -offset indent
706# geli init /dev/da0
707Enter new passphrase:
708Reenter new passphrase:
709
710Metadata backup can be found in /var/backups/da0.eli and
711can be restored with the following command:
712
713 # geli restore /var/backups/da0.eli /dev/da0
714
715# geli clear /dev/da0
716# geli attach /dev/da0
717geli: Cannot read metadata from /dev/da0: Invalid argument.
718# geli restore /var/backups/da0.eli /dev/da0
719# geli attach /dev/da0
720Enter passphrase:
721.Ed
722.Pp
723If an encrypted filesystem is extended, it is necessary to relocate and
724update the metadata:
725.Bd -literal -offset indent
726# gpart create -s GPT ada0
727# gpart add -s 1g -t freebsd-ufs -i 1 ada0
728# geli init -K keyfile -P ada0p1
729# gpart resize -s 2g -i 1 ada0
730# geli resize -s 1g ada0p1
731# geli attach -k keyfile -p ada0p1
732.Ed
733.Pp
734Initialize provider with passphrase split into two files.
735The provider can be attached by giving those two files or by giving
736.Dq foobar
737passphrase on
738.Nm
739prompt:
740.Bd -literal -offset indent
741# echo foo > da0.pass0
742# echo bar > da0.pass1
743# geli init -J da0.pass0 -J da0.pass1 da0
744# geli attach -j da0.pass0 -j da0.pass1 da0
745# geli detach da0
746# geli attach da0
747Enter passphrase: foobar
748.Ed
749.Sh ENCRYPTION MODES
750.Nm
751supports two encryption modes:
752.Nm XTS ,
753which was standarized as
754.Nm IEE P1619
755and
756.Nm CBC
757with unpredictable IV.
758The
759.Nm CBC
760mode used by
761.Nm
762is very similar to the mode
763.Nm ESSIV .
764.Sh DATA AUTHENTICATION
765.Nm
766can verify data integrity when an authentication algorithm is specified.
767When data corruption/modification is detected,
768.Nm
769will not return any data, but instead will return an error
770.Pq Er EINVAL .
771The offset and size of the corrupted data will be printed on the console.
772It is important to know against which attacks
773.Nm
774provides protection for your data.
775If data is modified in-place or copied from one place on the disk
776to another even without modification,
777.Nm
778should be able to detect such a change.
779If an attacker can remember the encrypted data, he can overwrite any future
780changes with the data he owns without notice.
781In other words
782.Nm
783will not protect your data against replay attacks.
784.Sh SEE ALSO
785.Xr crypto 4 ,
786.Xr gbde 4 ,
787.Xr geom 4 ,
788.Xr loader.conf 5 ,
789.Xr gbde 8 ,
790.Xr geom 8 ,
791.Xr crypto 9
792.Sh HISTORY
793The
794.Nm
795utility appeared in
796.Fx 6.0 .
797Support for
798.Nm Camellia
799block cipher is implemented by Yoshisato Yanagisawa in
800.Fx 7.0 .
801.Sh AUTHORS
802.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org