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