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