sbin/geom/class/eli/geli.8

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