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