diff --git a/lib/geom/eli/geli.8 b/lib/geom/eli/geli.8 index 098ba4d0485e..d34e15dc4ad8 100644 --- a/lib/geom/eli/geli.8 +++ b/lib/geom/eli/geli.8 @@ -1,1291 +1,1289 @@ .\" Copyright (c) 2005-2019 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd April 24, 2024 .Dt GELI 8 .Os .Sh NAME .Nm geli .Nd "control utility for the cryptographic GEOM class" .Sh SYNOPSIS To compile GEOM_ELI into your kernel, add the following lines to your kernel configuration file: .Bd -ragged -offset indent .Cd "device crypto" .Cd "options GEOM_ELI" .Ed .Pp Alternatively, to load the GEOM_ELI module at boot time, add the following line to your .Xr loader.conf 5 : .Bd -literal -offset indent geom_eli_load="YES" .Ed .Pp .No Usage of the Nm utility: .Pp .Nm .Cm init .Op Fl bdgPRTv .Op Fl a Ar aalgo .Op Fl B Ar backupfile .Op Fl e Ar ealgo .Op Fl i Ar iterations .Op Fl J Ar newpassfile .Op Fl K Ar newkeyfile .Op Fl l Ar keylen .Op Fl s Ar sectorsize .Op Fl V Ar version .Ar prov ... .Nm .Cm label - an alias for .Cm init .Nm .Cm attach .Op Fl Cdprv .Op Fl n Ar keyno .Op Fl j Ar passfile .Op Fl k Ar keyfile .Ar prov ... .Nm .Cm detach .Op Fl fl .Ar prov ... .Nm .Cm stop - an alias for .Cm detach .Nm .Cm onetime .Op Fl dRT .Op Fl a Ar aalgo .Op Fl e Ar ealgo .Op Fl l Ar keylen .Op Fl s Ar sectorsize .Ar prov .Nm .Cm configure .Op Fl bBdDgGrRtT .Ar prov ... .Nm .Cm setkey .Op Fl pPv .Op Fl i Ar iterations .Op Fl j Ar passfile .Op Fl J Ar newpassfile .Op Fl k Ar keyfile .Op Fl K Ar newkeyfile .Op Fl n Ar keyno .Ar prov .Nm .Cm delkey .Op Fl afv .Op Fl n Ar keyno .Ar prov .Nm .Cm kill .Op Fl av .Op Ar prov ... .Nm .Cm backup .Op Fl v .Ar prov .Ar file .Nm .Cm restore .Op Fl fv .Ar file .Ar prov .Nm .Cm suspend .Op Fl v .Fl a | Ar prov ... .Nm .Cm resume .Op Fl pv .Op Fl j Ar passfile .Op Fl k Ar keyfile .Ar prov .Nm .Cm resize .Op Fl v .Fl s Ar oldsize .Ar prov .Nm .Cm version .Op Ar prov ... .Nm .Cm clear .Op Fl v .Ar prov ... .Nm .Cm dump .Op Fl v .Ar prov ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used to configure encryption on GEOM providers. .Pp The following is a list of the most important features: .Pp .Bl -bullet -offset indent -compact .It Utilizes the .Xr crypto 9 framework, so when there is crypto hardware available, .Nm will make use of it automatically. .It Supports many cryptographic algorithms (currently .Nm AES-XTS , .Nm AES-CBC , and .Nm Camellia-CBC ) . .It Can optionally perform data authentication (integrity verification) utilizing one of the following algorithms: .Nm HMAC/SHA1 , .Nm HMAC/RIPEMD160 , .Nm HMAC/SHA256 , .Nm HMAC/SHA384 or .Nm HMAC/SHA512 . .It Can create a User Key from up to two, piecewise components: a passphrase entered via prompt or read from one or more passfiles; a keyfile read from one or more files. .It Allows encryption of the root partition. The user is asked for the passphrase before the root filesystem is mounted. .It Strengthens the passphrase component of the User Key with: .Rs .%A B. Kaliski .%T "PKCS #5: Password-Based Cryptography Specification, Version 2.0." .%R RFC .%N 2898 .Re .It Allows the use of two independent User Keys (e.g., a .Qq "user key" and a .Qq "company key" ) . .It It is fast - .Nm performs simple sector-to-sector encryption. .It Allows the encrypted Master Key to be backed up and restored, so that if a user has to quickly destroy key material, it is possible to get the data back by restoring keys from backup. .It Providers can be configured to automatically detach on last close, so users do not have to remember to detach providers after unmounting the filesystems. .It Allows attaching a provider with a random, one-time Master Key, which is useful for swap partitions and temporary filesystems. .It Allows verification of data integrity (data authentication). .It Allows suspending and resuming encrypted devices. .El .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm configure" .It Cm init Initialize providers which need to be encrypted. If multiple providers are listed as arguments, they will all be initialized with the same passphrase and/or User Key. A unique salt will be randomly generated for each provider to ensure the Master Key for each is unique. Here you can set up the cryptographic algorithm to use, Data Key length, etc. The last sector of the providers is used to store metadata. The .Cm init subcommand also automatically writes metadata backups to .Pa /var/backups/.eli file. The metadata can be recovered with the .Cm restore subcommand described below. .Pp Additional options include: .Bl -tag -width ".Fl J Ar newpassfile" .It Fl a Ar aalgo Enable data integrity verification (authentication) using the given algorithm. This will reduce the size of storage available and also reduce speed. For example, when using 4096 bytes sector and .Nm HMAC/SHA256 algorithm, 89% of the original provider storage will be available for use. Currently supported algorithms are: .Nm HMAC/SHA1 , .Nm HMAC/RIPEMD160 , .Nm HMAC/SHA256 , .Nm HMAC/SHA384 and .Nm HMAC/SHA512 . If the option is not given, there will be no authentication, only encryption. The recommended algorithm is .Nm HMAC/SHA256 . .It Fl b Try to decrypt this partition during boot, before the root partition is mounted. This makes it possible to use an encrypted root partition. One will still need bootable unencrypted storage with a .Pa /boot/ directory, which can be a CD-ROM disc or USB pen-drive, that can be removed after boot. .It Fl B Ar backupfile File name to use for metadata backup instead of the default .Pa /var/backups/.eli . To inhibit backups, you can use .Pa none as the .Ar backupfile . If multiple providers were initialized in the one command, you can use .Pa PROV (all upper-case) in the file name, and it will be replaced with the provider name. If .Pa PROV is not found in the file name and multiple providers were initialized in the one command, .Pa - will be appended to the end of the file name specified. .It Fl d When entering the passphrase to boot from this encrypted root filesystem, echo .Ql * characters. This makes the length of the passphrase visible. .It Fl e Ar ealgo Encryption algorithm to use. Currently supported algorithms are: .Nm AES-XTS , .Nm AES-CBC , .Nm Camellia-CBC , and .Nm NULL . The default and recommended algorithm is .Nm AES-XTS . .Nm NULL is unencrypted. .It Fl g Enable booting from this encrypted root filesystem. The boot loader prompts for the passphrase and loads .Xr loader 8 from the encrypted partition. .It Fl i Ar iterations Number of iterations to use with PKCS#5v2 when processing User Key passphrase component. If this option is not specified, .Nm will find the number of iterations which is equal to 2 seconds of crypto work. If 0 is given, PKCS#5v2 will not be used. PKCS#5v2 processing is performed once, after all parts of the passphrase component have been read. .It Fl J Ar newpassfile Specifies a file which contains the passphrase component of the User Key (or part of it). If .Ar newpassfile is given as -, standard input will be used. Only the first line (excluding new-line character) is taken from the given file. This argument can be specified multiple times, which has the effect of reassembling a single passphrase split across multiple files. Cannot be combined with the .Fl P option. .It Fl K Ar newkeyfile Specifies a file which contains the keyfile component of the User Key (or part of it). If .Ar newkeyfile is given as -, standard input will be used. This argument can be specified multiple times, which has the effect of reassembling a single keyfile split across multiple keyfile parts. .It Fl l Ar keylen Data Key length to use with the given cryptographic algorithm. If the length is not specified, the selected algorithm uses its .Em default key length. .Bl -ohang -offset indent .It Nm AES-XTS .Em 128 , 256 .It Nm AES-CBC , Nm Camellia-CBC .Em 128 , 192, 256 .El .It Fl P Do not use a passphrase as a component of the User Key. Cannot be combined with the .Fl J option. .It Fl s Ar sectorsize Change decrypted provider's sector size. Increasing the sector size allows increased performance, because encryption/decryption which requires an initialization vector is done per sector; fewer sectors means less computational work. .It Fl R Turn off automatic expansion. By default, if the underlying provider grows, the encrypted provider will grow automatically too. The metadata will be moved to the new location. If automatic expansion if turned off and the underlying provider changes size, attaching encrypted provider will no longer be possible as the metadata will no longer be located in the last sector. In this case .Nm GELI will only log the previous size of the underlying provider, so metadata can be found easier, if resize was done by mistake. .It Fl T Don't pass through .Dv BIO_DELETE calls (i.e., TRIM/UNMAP). This can prevent an attacker from knowing how much space you're actually using and which sectors contain live data, but will also prevent the backing store (SSD, etc) from reclaiming space you're not using, which may degrade its performance and lifespan. The underlying provider may or may not actually obliterate the deleted sectors when TRIM is enabled, so it should not be considered to add any security. .It Fl V Ar version Metadata version to use. This option is helpful when creating a provider that may be used by older .Nm FreeBSD/GELI versions. Consult the .Sx HISTORY section to find which metadata version is supported by which .Fx version. Note that using an older version of metadata may limit the number of features available. .El .It Cm attach Attach the given providers. The encrypted Master Keys are loaded from the metadata and decrypted using the given passphrase/keyfile and new GEOM providers are created using the specified provider names. A .Qq .eli suffix is added to the user specified provider names. Multiple providers can only be attached with a single .Cm attach command if they all have the same passphrase and keyfiles. .Pp Additional options include: .Bl -tag -width ".Fl j Ar passfile" .It Fl C Do a dry-run decryption. This is useful to verify passphrase and keyfile without decrypting the device. .It Fl d If specified, the decrypted providers are detached automatically on last close, so the user does not have to remember to detach providers after unmounting the filesystems. This only works when providers were opened for writing, and will not work if the filesystems on the providers were mounted read-only. Probably a better choice is the .Fl l option for the .Cm detach subcommand. .It Fl n Ar keyno Specifies the index number of the Master Key copy to use (could be 0 or 1). If the index number is not provided all keys will be tested. .It Fl j Ar passfile Specifies a file which contains the passphrase component of the User Key (or part of it). For more information see the description of the .Fl J option for the .Cm init subcommand. The same passfiles are used for all listed providers. .It Fl k Ar keyfile Specifies a file which contains the keyfile component of the User Key (or part of it). For more information see the description of the .Fl K option for the .Cm init subcommand. The same keyfiles are used for all listed providers. .It Fl p Do not use a passphrase as a component of the User Keys. Cannot be combined with the .Fl j option. .It Fl r Attach read-only providers. They are not opened for writing. .El .It Cm detach Detach the given providers, which means remove the devfs entry and clear the Master Key and Data Keys from memory. .Pp Additional options include: .Bl -tag -width ".Fl f" .It Fl f Force detach - detach even if the provider is open. .It Fl l Mark provider to detach on last close, after the last filesystem has been unmounted. If this option is specified, the provider will not be detached while it is open, but will be automatically detached when it is closed for the last time even if it was only opened for reading. .El .It Cm onetime Attach the given providers with a random, one-time (ephemeral) Master Key. The command can be used to encrypt swap partitions or temporary filesystems. .Pp Additional options include: .Bl -tag -width ".Fl a Ar sectorsize" .It Fl a Ar aalgo Enable data integrity verification (authentication). For more information, see the description of the .Cm init subcommand. .It Fl e Ar ealgo Encryption algorithm to use. For more information, see the description of the .Cm init subcommand. .It Fl d Detach on last close, after the last filesystem has been unmounted. Note: this option is not usable for temporary filesystems as the provider is detached after the filesystem has been created. It still can, and should, be used for swap partitions. For more information, see the description of the .Cm attach subcommand. .It Fl l Ar keylen Data Key length to use with the given cryptographic algorithm. For more information, see the description of the .Cm init subcommand. .It Fl s Ar sectorsize Change decrypted provider's sector size. For more information, see the description of the .Cm init subcommand. .It Fl R Turn off automatic expansion. For more information, see the description of the .Cm init subcommand. .It Fl T Disable TRIM/UNMAP passthru. For more information, see the description of the .Cm init subcommand. .El .It Cm configure Change configuration of the given providers. .Pp Additional options include: .Bl -tag -width ".Fl b" .It Fl b Set the BOOT flag on the given providers. For more information, see the description of the .Cm init subcommand. .It Fl B Remove the BOOT flag from the given providers. .It Fl d When entering the passphrase to boot from this encrypted root filesystem, echo .Ql * characters. This makes the length of the passphrase visible. .It Fl D Disable echoing of any characters when a passphrase is entered to boot from this encrypted root filesystem. This hides the passphrase length. .It Fl g Enable booting from this encrypted root filesystem. The boot loader prompts for the passphrase and loads .Xr loader 8 from the encrypted partition. .It Fl G Deactivate booting from this encrypted root partition. .It Fl r Turn on automatic expansion. For more information, see the description of the .Cm init subcommand. .It Fl R Turn off automatic expansion. .It Fl t Enable TRIM/UNMAP passthru. For more information, see the description of the .Cm init subcommand. .It Fl T Disable TRIM/UNMAP passthru. .El .It Cm setkey Install a copy of the Master Key into the selected slot, encrypted with a new User Key. If the selected slot is populated, replace the existing copy. A provider has one Master Key, which can be stored in one or both slots, each encrypted with an independent User Key. With the .Cm init subcommand, only key number 0 is initialized. The User Key can be changed at any time: for an attached provider, for a detached provider, or on the backup file. When a provider is attached, the user does not have to provide an existing passphrase/keyfile. .Pp Additional options include: .Bl -tag -width ".Fl J Ar newpassfile" .It Fl i Ar iterations Number of iterations to use with PKCS#5v2. If 0 is given, PKCS#5v2 will not be used. To be able to use this option with the .Cm setkey subcommand, only one key has to be defined and this key must be changed. .It Fl j Ar passfile Specifies a file which contains the passphrase component of a current User Key (or part of it). .It Fl J Ar newpassfile Specifies a file which contains the passphrase component of the new User Key (or part of it). .It Fl k Ar keyfile Specifies a file which contains the keyfile component of a current User Key (or part of it). .It Fl K Ar newkeyfile Specifies a file which contains the keyfile component of the new User Key (or part of it). .It Fl n Ar keyno Specifies the index number of the Master Key copy to change (could be 0 or 1). If the provider is attached and no key number is given, the key used for attaching the provider will be changed. If the provider is detached (or we are operating on a backup file) and no key number is given, the first Master Key copy to be successfully decrypted with the provided User Key passphrase/keyfile will be changed. .It Fl p Do not use a passphrase as a component of the current User Key. Cannot be combined with the .Fl j option. .It Fl P Do not use a passphrase as a component of the new User Key. Cannot be combined with the .Fl J option. .El .It Cm delkey Destroy (overwrite with random data) the selected Master Key copy. If one is destroying keys for an attached provider, the provider will not be detached even if all copies of the Master Key are destroyed. It can even be rescued with the .Cm setkey subcommand because the Master Key is still in memory. .Pp Additional options include: .Bl -tag -width ".Fl a Ar keyno" .It Fl a Destroy all copies of the Master Key (does not need .Fl f option). .It Fl f Force key destruction. This option is needed to destroy the last copy of the Master Key. .It Fl n Ar keyno Specifies the index number of the Master Key copy. If the provider is attached and no key number is given, the key used for attaching the provider will be destroyed. If provider is detached (or we are operating on a backup file) the key number has to be given. .El .It Cm kill This command should be used only in emergency situations. It will destroy all copies of the Master Key on a given provider and will detach it forcibly (if it is attached). This is absolutely a one-way command - if you do not have a metadata backup, your data is gone for good. In case the provider was attached with the .Fl r flag, the keys will not be destroyed, only the provider will be detached. .Pp Additional options include: .Bl -tag -width ".Fl a" .It Fl a If specified, all currently attached providers will be killed. .El .It Cm backup Backup metadata from the given provider to the given file. .It Cm restore Restore metadata from the given file to the given provider. .Pp Additional options include: .Bl -tag -width ".Fl f" .It Fl f Metadata contains the size of the provider to ensure that the correct partition or slice is attached. If an attempt is made to restore metadata to a provider that has a different size, .Nm will refuse to restore the data unless the .Fl f switch is used. If the partition or slice has been grown, the .Cm resize subcommand should be used rather than attempting to relocate the metadata through .Cm backup and .Cm restore . .El .It Cm suspend Suspend device by waiting for all inflight requests to finish, clearing all sensitive information such as the Master Key and Data Keys from kernel memory, and blocking all further I/O requests until the .Cm resume subcommand is executed. This functionality is useful for laptops. Suspending a laptop should not leave an encrypted device attached. The .Cm suspend subcommand can be used rather than closing all files and directories from filesystems on the encrypted device, unmounting the filesystem, and detaching the device. Any access to the encrypted device will be blocked until the Master Key is reloaded through the .Cm resume subcommand. Thus there is no need to close nor unmount anything. The .Cm suspend subcommand does not work with devices created with the .Cm onetime subcommand. Please note that sensitive data might still be present in memory locations such as the filesystem cache after suspending an encrypted device. .Pp Additional options include: .Bl -tag -width ".Fl a" .It Fl a Suspend all .Nm devices. .El .It Cm resume Resume previously suspended device. The caller must ensure that executing this subcommand does not access the suspended device, leading to a deadlock. For example, suspending a device which contains the filesystem where the .Nm utility is stored is a bad idea. .Pp Additional options include: .Bl -tag -width ".Fl j Ar passfile" .It Fl j Ar passfile Specifies a file which contains the passphrase component of the User Key, or part of it. For more information see the description of the .Fl J option for the .Cm init subcommand. .It Fl k Ar keyfile Specifies a file which contains the keyfile component of the User Key, or part of it. For more information see the description of the .Fl K option for the .Cm init subcommand. .It Fl p Do not use a passphrase as a component of the User Key. Cannot be combined with the .Fl j option. .El .It Cm resize Inform .Nm that the provider has been resized. The old metadata block is relocated to the correct position at the end of the provider and the provider size is updated. .Pp Additional options include: .Bl -tag -width ".Fl s Ar oldsize" .It Fl s Ar oldsize The size of the provider before it was resized. .El .It Cm version If no arguments are given, the .Cm version subcommand will print the version of .Nm userland utility as well as the version of the .Nm ELI GEOM class. .Pp If GEOM providers are specified, the .Cm version subcommand will print metadata version used by each of them. .It Cm clear Clear metadata from the given providers. .Em WARNING : This will erase with zeros the encrypted Master Key copies stored in the metadata. .It Cm dump Dump metadata stored on the given providers. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Pp Additional options include: .Bl -tag -width ".Fl v" .It Fl v Be more verbose. .El .Sh KEY SUMMARY .Ss Master Key Upon .Cm init , the .Nm utility generates a random Master Key for the provider. The Master Key never changes during the lifetime of the provider. Each copy of the provider metadata, active or backed up to a file, can store up to two, independently-encrypted copies of the Master Key. .Ss User Key Each stored copy of the Master Key is encrypted with a User Key, which is generated by the .Nm utility from a passphrase and/or a keyfile. The .Nm utility first reads all parts of the keyfile in the order specified on the command line, then reads all parts of the stored passphrase in the order specified on the command line. If no passphrase parts are specified, the system prompts the user to enter the passphrase. The passphrase is optionally strengthened by PKCS#5v2. The User Key is a digest computed over the concatenated keyfile and passphrase. .Ss Data Key During operation, one or more Data Keys are deterministically derived by the kernel from the Master Key and cached in memory. The number of Data Keys used by a given provider, and the way they are derived, depend on the GELI version and whether the provider is configured to use data authentication. .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to control the behavior of the .Nm ELI GEOM class. The default value is shown next to each variable. Some variables can also be set in .Pa /boot/loader.conf . .Bl -tag -width indent .It Va kern.geom.eli.version Version number of the .Nm ELI GEOM class. .It Va kern.geom.eli.debug : No 0 Debug level of the .Nm ELI GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0, minimal debug information is printed. If set to 3, the maximum amount of debug information is printed. .It Va kern.geom.eli.tries : No 3 Number of times a user is asked for the passphrase. This is only used for providers which are attached on boot, before the root filesystem is mounted. If set to 0, attaching providers on boot will be disabled. This variable should be set in .Pa /boot/loader.conf . .It Va kern.geom.eli.overwrites : No 5 Specifies how many times the Master Key is overwritten with random values when it is destroyed. After this operation it is filled with zeros. .It Va kern.geom.eli.use_uma_bytes .Nm must allocate a buffer for every write operation, used when performing encryption. This sysctl reports the maximum size in bytes for which geli will perform the allocation using .Xr UMA 9 , as opposed to .Xr malloc 9 . .It Va kern.geom.eli.visible_passphrase : No 0 If set to 1, the passphrase entered on boot will be visible. This alternative should be used with caution as the entered passphrase can be logged and exposed via .Xr dmesg 8 . This variable should be set in .Pa /boot/loader.conf . .It Va kern.geom.eli.threads : No 0 Specifies how many kernel threads should be used for doing software cryptography. Its purpose is to increase performance on SMP systems. If set to 0, a CPU-pinned thread will be started for every active CPU. Note that this variable must be set prior to attaching .Nm to a disk. .It Va kern.geom.eli.batch : No 0 When set to 1, can speed-up crypto operations by using batching. Batching reduces the number of interrupts by responding to a group of crypto requests with one interrupt. The crypto card and the driver have to support this feature. .It Va kern.geom.eli.key_cache_limit : No 8192 Specifies how many Data Keys to cache. The default limit (8192 keys) will allow caching of all keys for a 4TB provider with 512 byte sectors and will take around 1MB of memory. .It Va kern.geom.eli.key_cache_hits Reports how many times we were looking up a Data Key and it was already in cache. This sysctl is not updated for providers that need fewer Data Keys than the limit specified in .Va kern.geom.eli.key_cache_limit . .It Va kern.geom.eli.key_cache_misses Reports how many times we were looking up a Data Key and it was not in cache. This sysctl is not updated for providers that need fewer Data Keys than the limit specified in .Va kern.geom.eli.key_cache_limit . .It Va kern.geom.eli.unmapped_io Enable support for unmapped I/O buffers, currently implemented only on 64-bit platforms. This is an optimization which reduces the overhead of I/O processing. This variable is intended for debugging purposes and must be set in .Pa /boot/loader.conf . .El .Sh PERFORMANCE CONSIDERATIONS The default value of .Va kern.geom.eli.threads is usually good for a system with one SSD. However, it may need to be lowered on systems with many disks, so as to avoid creating too much thread-switching overhead. On systems with more disks than CPUs, it's best to set this variable to 1. .Pp .Nm internally uses .Xr malloc 9 to allocate memory for operations larger than .Va kern.geom.eli.use_uma_bytes , but malloc is slow for allocations larger than .Va vm.kmem_zmax . So it's best to avoid writing more than .Ms MAX(kern.geom.eli.use_uma_bytes, vm.kmem_zmax) in a single write operation. On systems that format .Xr zfs 4 on top of .Nm , the maximum write size can be controlled by .Va vfs.zfs.vdev.aggregation_limit and .Va vfs.zfs.vdev.aggregation_limit_non_rotating for HDDs and SSDs, respectively. .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES Initialize a provider which is going to be encrypted with a passphrase and random data from a file on the user's pen drive. Use 4kB sector size. Attach the provider, create a filesystem, and mount it. Do the work. Unmount the provider and detach it: .Bd -literal -offset indent # dd if=/dev/random of=/mnt/pendrive/da2.key bs=64 count=1 # geli init -s 4096 -K /mnt/pendrive/da2.key /dev/da2 Enter new passphrase: Reenter new passphrase: # geli attach -k /mnt/pendrive/da2.key /dev/da2 Enter passphrase: # dd if=/dev/random of=/dev/da2.eli bs=1m # newfs /dev/da2.eli # mount /dev/da2.eli /mnt/secret \&... # umount /mnt/secret # geli detach da2.eli .Ed .Pp Create an encrypted provider, but use two User Keys: one for your employee and one for you as the company's security officer (so it is not a tragedy if the employee .Qq accidentally forgets his passphrase): .Bd -literal -offset indent # geli init /dev/da2 Enter new passphrase: (enter security officer's passphrase) Reenter new passphrase: # geli setkey -n 1 /dev/da2 Enter passphrase: (enter security officer's passphrase) Enter new passphrase: (let your employee enter his passphrase ...) Reenter new passphrase: (... twice) .Ed .Pp You are the security officer in your company. Create an encrypted provider for use by the user, but remember that users forget their passphrases, so backup the Master Key with your own random key: .Bd -literal -offset indent # dd if=/dev/random of=/mnt/pendrive/keys/`hostname` bs=64 count=1 # geli init -P -K /mnt/pendrive/keys/`hostname` /dev/ada0s1e # geli backup /dev/ada0s1e /mnt/pendrive/backups/`hostname` (use key number 0, so the encrypted Master Key will be re-encrypted by this) # geli setkey -n 0 -k /mnt/pendrive/keys/`hostname` /dev/ada0s1e (allow the user to enter his passphrase) Enter new passphrase: Reenter new passphrase: .Ed .Pp Encrypted swap partition setup: .Bd -literal -offset indent # dd if=/dev/random of=/dev/ada0s1b bs=1m # geli onetime -d ada0s1b # swapon /dev/ada0s1b.eli .Ed .Pp The example below shows how to configure two providers which will be attached on boot, before the root filesystem is mounted. One of them is using passphrase and three keyfile parts and the other is using only a keyfile in one part: .Bd -literal -offset indent # dd if=/dev/random of=/dev/da0 bs=1m # dd if=/dev/random of=/boot/keys/da0.key0 bs=32k count=1 # dd if=/dev/random of=/boot/keys/da0.key1 bs=32k count=1 # dd if=/dev/random of=/boot/keys/da0.key2 bs=32k count=1 # geli init -b -K /boot/keys/da0.key0 -K /boot/keys/da0.key1 -K /boot/keys/da0.key2 da0 Enter new passphrase: Reenter new passphrase: # dd if=/dev/random of=/dev/da1s3a bs=1m # dd if=/dev/random of=/boot/keys/da1s3a.key bs=128k count=1 # geli init -b -P -K /boot/keys/da1s3a.key da1s3a .Ed .Pp The providers are initialized, now we have to add these lines to .Pa /boot/loader.conf : .Bd -literal -offset indent geli_da0_keyfile0_load="YES" geli_da0_keyfile0_type="da0:geli_keyfile0" geli_da0_keyfile0_name="/boot/keys/da0.key0" geli_da0_keyfile1_load="YES" geli_da0_keyfile1_type="da0:geli_keyfile1" geli_da0_keyfile1_name="/boot/keys/da0.key1" geli_da0_keyfile2_load="YES" geli_da0_keyfile2_type="da0:geli_keyfile2" geli_da0_keyfile2_name="/boot/keys/da0.key2" geli_da1s3a_keyfile0_load="YES" geli_da1s3a_keyfile0_type="da1s3a:geli_keyfile0" geli_da1s3a_keyfile0_name="/boot/keys/da1s3a.key" .Ed .Pp If there is only one keyfile, the index might be omitted: .Bd -literal -offset indent geli_da1s3a_keyfile_load="YES" geli_da1s3a_keyfile_type="da1s3a:geli_keyfile" geli_da1s3a_keyfile_name="/boot/keys/da1s3a.key" .Ed .Pp By convention, these loader variables are called .Sm off .Va geli_ No < Ar device No > Va _load . .Sm on However, the actual name prefix before .Va _load , _type , or .Va _name does not matter. At boot time, the .Nm module searches through all .Sm off .No < Va prefix No > Va _type No -like .Sm on variables that have a value of .Sm off .Dq < Ar device No > :geli_keyfile . .Sm on The paths to keyfiles are then extracted from .Sm off .No < Ar prefix No > Va _name .Sm on variables. In the example above, .Ar prefix is .Dq Li geli_da1s3a_keyfile . .Pp Not only configure encryption, but also data integrity verification using .Nm HMAC/SHA256 . .Bd -literal -offset indent # geli init -a hmac/sha256 -s 4096 /dev/da0 Enter new passphrase: Reenter new passphrase: # geli attach /dev/da0 Enter passphrase: # dd if=/dev/random of=/dev/da0.eli bs=1m # newfs /dev/da0.eli # mount /dev/da0.eli /mnt/secret .Ed .Pp .Cm geli writes the metadata backup by default to the .Pa /var/backups/.eli file. If the metadata is lost in any way (e.g., by accidental overwrite), it can be restored. Consider the following situation: .Bd -literal -offset indent # geli init /dev/da0 Enter new passphrase: Reenter new passphrase: Metadata backup can be found in /var/backups/da0.eli and can be restored with the following command: # geli restore /var/backups/da0.eli /dev/da0 # geli clear /dev/da0 # geli attach /dev/da0 geli: Cannot read metadata from /dev/da0: Invalid argument. # geli restore /var/backups/da0.eli /dev/da0 # geli attach /dev/da0 Enter passphrase: .Ed .Pp If an encrypted filesystem is extended, it is necessary to relocate and update the metadata: .Bd -literal -offset indent # gpart create -s GPT ada0 # gpart add -s 1g -t freebsd-ufs -i 1 ada0 # geli init -K keyfile -P ada0p1 # gpart resize -s 2g -i 1 ada0 # geli resize -s 1g ada0p1 # geli attach -k keyfile -p ada0p1 .Ed .Pp Initialize provider with the passphrase split into two files. The provider can be attached using those two files or by entering .Dq foobar as the passphrase at the .Nm prompt: .Bd -literal -offset indent # echo foo > da0.pass0 # echo bar > da0.pass1 # geli init -J da0.pass0 -J da0.pass1 da0 # geli attach -j da0.pass0 -j da0.pass1 da0 # geli detach da0 # geli attach da0 Enter passphrase: foobar .Ed .Pp Suspend all .Nm devices on a laptop, suspend the laptop, then resume devices one by one after resuming the laptop: .Bd -literal -offset indent # geli suspend -a # zzz # geli resume -p -k keyfile gpt/secret # geli resume gpt/private Enter passphrase: .Ed .Pp To create a .Nm encrypted filesystem with a file as storage device follow this example. First a file named private0 is created in .Pa /usr and attached as a memory disk like .Pa /dev/md0 for example. .Bd -literal -offset indent # dd if=/dev/zero of=/usr/private0 bs=1m count=256 # chmod 0600 /usr/private0 # mdconfig -t vnode -f /usr/private0 .Ed .Pp It is recommended to place the following line in .Xr rc.conf 5 to have the memory disk automatically created during boot. .Bd -literal -offset indent mdconfig_md0="-t vnode -f /usr/private0" .Ed .Pp After .Pa /dev/md0 is created a random key has to be generated and stored in a secure location, like .Pa /root for example. This key should be protected by a passphrase, which is requested when geli init is called. .Bd -literal -offset indent # dd if=/dev/random of=/root/private0.key bs=64 count=1 # geli init -K /root/private0.key -s 4096 /dev/md0 Enter new passphrase: Reenter new passphrase: # geli attach -k /root/private0.key /dev/md0 Enter passphrase: # dd if=/dev/random of=/dev/md0.eli bs=1m .Ed .Pp Once the initialization of the .Pa /dev/md0.eli device is ready create a UFS filesystem and mount it for example in .Pa /private . .Bd -literal -offset indent # newfs /dev/md0.eli # mount /dev/md0.eli /private .Ed .Pp After a system reboot the .Nm device can be mounted again with the following commands. The call of geli attach will ask for the passphrase. It is recommended to do this procedure after the boot, because otherwise the boot process would be waiting for the passphrase input. .Bd -literal -offset indent # geli attach -k /root/private0.key /dev/md0 Enter passphrase: # mount /dev/md0.eli /private .Ed .Sh ENCRYPTION MODES .Nm supports two encryption modes: .Nm XTS , which was standardized as .Nm IEEE P1619 and .Nm CBC with unpredictable IV. The .Nm CBC mode used by .Nm is very similar to the mode .Nm ESSIV . .Sh DATA AUTHENTICATION .Nm can verify data integrity when an authentication algorithm is specified. When data corruption/modification is detected, .Nm will not return any data, but instead will return an error .Pq Er EINVAL . The offset and size of the corrupted data will be printed on the console. It is important to know against which attacks .Nm provides protection for your data. If data is modified in-place or copied from one place on the disk to another even without modification, .Nm should be able to detect such a change. If an attacker can remember the encrypted data, he can overwrite any future changes with the data he owns without it being noticed. In other words .Nm will not protect your data against replay attacks. .Pp It is recommended to write to the whole provider before first use, in order to make sure that all sectors and their corresponding checksums are properly initialized into a consistent state. One can safely ignore data authentication errors that occur immediately after the first time a provider is attached and before it is initialized in this way. .Sh SEE ALSO .Xr crypto 4 , -.Xr gbde 4 , .Xr geom 4 , .Xr loader.conf 5 , -.Xr gbde 8 , .Xr geom 8 , .Xr crypto 9 .Sh HISTORY The .Nm utility appeared in .Fx 6.0 . Support for the .Nm Camellia block cipher was implemented by Yoshisato Yanagisawa in .Fx 7.0 . .Pp Highest .Nm GELI metadata version supported by the given .Fx version: .Bl -column -offset indent ".Sy FreeBSD" ".Sy version" .It Sy FreeBSD Ta Sy GELI .It Sy version Ta Sy version .Pp .It Li 6.0 Ta 0 .It Li 6.1 Ta 0 .It Li 6.2 Ta 3 .It Li 6.3 Ta 3 .It Li 6.4 Ta 3 .Pp .It Li 7.0 Ta 3 .It Li 7.1 Ta 3 .It Li 7.2 Ta 3 .It Li 7.3 Ta 3 .It Li 7.4 Ta 3 .Pp .It Li 8.0 Ta 3 .It Li 8.1 Ta 3 .It Li 8.2 Ta 5 .Pp .It Li 9.0 Ta 6 .Pp .It Li 10.0 Ta 7 .El .Sh AUTHORS .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org diff --git a/lib/geom/shsec/gshsec.8 b/lib/geom/shsec/gshsec.8 index 9430fde13c52..d4477de3a71e 100644 --- a/lib/geom/shsec/gshsec.8 +++ b/lib/geom/shsec/gshsec.8 @@ -1,128 +1,127 @@ .\" Copyright (c) 2005 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd October 1, 2013 .Dt GSHSEC 8 .Os .Sh NAME .Nm gshsec .Nd "control utility for shared secret devices" .Sh SYNOPSIS .Nm .Cm label .Op Fl hv .Ar name .Ar prov prov ... .Nm .Cm stop .Op Fl fv .Ar name ... .Nm .Cm clear .Op Fl v .Ar prov ... .Nm .Cm dump .Ar prov ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used for setting up a device which contains a shared secret. The secret is shared between the given providers. To collect the secret, all providers are needed. If one of the components is missing, there is no way to get any useful data from the rest of them. The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm destroy" .It Cm label Set up a shared secret device from the given components with the specified .Ar name . Metadata are stored in the last sector of every component. .It Cm stop Turn off an existing shared secret device by its .Ar name . This command does not touch on-disk metadata! .It Cm clear Clear metadata on the given providers. .It Cm dump Dump metadata stored on the given providers. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Pp Additional options: .Bl -tag -width ".Fl f" .It Fl f Force the removal of the specified shared secret device. .It Fl h Hardcode providers' names in metadata. .It Fl v Be more verbose. .El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES The following example shows how to create a shared secret device. The secret will be split between a slice on a local disk and a USB Pen drive. .Bd -literal -offset indent gshsec label -v secret /dev/ada0s1 /dev/da0 newfs /dev/shsec/secret .Ed .Pp From now on, when the USB Pen drive is inserted, it will be automatically detected and connected, making the secret available via the .Pa /dev/shsec/secret device. .Sh SEE ALSO .Xr geom 4 , -.Xr gbde 8 , .Xr geom 8 , .Xr newfs 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.4 . .Sh AUTHORS .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org diff --git a/libexec/rc/rc.d/geli b/libexec/rc/rc.d/geli index 312d76a361ad..16d24efd1e39 100755 --- a/libexec/rc/rc.d/geli +++ b/libexec/rc/rc.d/geli @@ -1,125 +1,124 @@ #!/bin/sh # # Copyright (c) 2005 Pawel Jakub Dawidek # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # # # PROVIDE: disks # KEYWORD: nojail . /etc/rc.subr name="geli" desc="GELI disk encryption" start_precmd='[ -n "$(geli_make_list)" -o -n "${geli_groups}" ]' start_cmd="geli_start" stop_cmd="geli_stop" required_modules="geom_eli:g_eli" geli_start() { devices=`geli_make_list` if [ -z "${geli_tries}" ]; then if [ -n "${geli_attach_attempts}" ]; then - # Compatibility with rc.d/gbde. geli_tries=${geli_attach_attempts} else geli_tries=`${SYSCTL_N} kern.geom.eli.tries` fi fi for provider in ${devices}; do provider_=`ltr ${provider} '/-' '_'` eval "flags=\${geli_${provider_}_flags}" if [ -z "${flags}" ]; then flags=${geli_default_flags} fi if [ -e "/dev/${provider}" -a ! -e "/dev/${provider}.eli" ]; then echo "Configuring Disk Encryption for ${provider}." count=1 while [ ${count} -le ${geli_tries} ]; do geli attach ${flags} ${provider} if [ -e "/dev/${provider}.eli" ]; then break fi echo "Attach failed; attempt ${count} of ${geli_tries}." count=$((count+1)) done fi done for group in ${geli_groups}; do group_=`ltr ${group} '/-' '_'` eval "flags=\${geli_${group_}_flags}" if [ -z "${flags}" ]; then flags=${geli_default_flags} fi eval "providers=\${geli_${group_}_devices}" if [ -z "${providers}" ]; then echo "No devices listed in geli group ${group}." continue fi if [ -e "/dev/${providers%% *}" -a ! -e "/dev/${providers%% *}.eli" ]; then echo "Configuring Disk Encryption for geli group ${group}, containing ${providers}." count=1 while [ ${count} -le ${geli_tries} ]; do geli attach ${flags} ${providers} if [ -e "/dev/${providers%% *}.eli" ]; then break fi echo "Attach failed; attempt ${count} of ${geli_tries}." count=$((count+1)) done fi done } geli_stop() { devices=`geli_make_list` for group in ${geli_groups}; do group_=`ltr ${group} '/-' '_'` eval "providers=\${geli_${group_}_devices}" devices="${devices} ${providers}" done for provider in ${devices}; do if [ -e "/dev/${provider}.eli" ]; then umount "/dev/${provider}.eli" 2>/dev/null geli detach "${provider}" fi done } load_rc_config $name run_rc_command "$1" diff --git a/sbin/ggate/ggatel/ggatel.8 b/sbin/ggate/ggatel/ggatel.8 index 1ac41ed9eaa7..816a5b9a6e0e 100644 --- a/sbin/ggate/ggatel/ggatel.8 +++ b/sbin/ggate/ggatel/ggatel.8 @@ -1,162 +1,144 @@ .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd September 8, 2016 .Dt GGATEL 8 .Os .Sh NAME .Nm ggatel .Nd "GEOM Gate local control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl s Ar sectorsize .Op Fl t Ar timeout .Op Fl u Ar unit .Ar path .Nm .Cm destroy .Op Fl f .Fl u Ar unit .Nm .Cm list .Op Fl v .Op Fl u Ar unit .Nm .Cm rescue .Op Fl v .Op Fl o Cm ro | wo | rw .Fl u Ar unit .Ar path .Sh DESCRIPTION The .Nm utility is a local GEOM Gate class consumer. It can be used as a replacement for .Xr md 4 devices or as a .Dq GEOMificator for non GEOM-aware devices, but it was mainly created as an example on how to use and how to communicate with the GEOM Gate kernel subsystem. .Pp Available commands: .Bl -tag -width ".Cm destroy" .It Cm create Create a .Nm ggate provider related to the given regular file or device. .It Cm destroy Destroy the given .Nm ggate provider. .It Cm list List .Nm ggate providers. .It Cm rescue Take over a previously created provider and handle pending and future requests. This is useful if the initial .Nm process died. To prevent data loss, the given path must lead to the regular file or device that was used to create the provider. .El .Pp Available options: .Bl -tag -width ".Fl s Cm ro | wo | rw" .It Fl f Forcibly destroy .Nm ggate provider (cancels all pending requests). .It Fl o Cm ro | wo | rw Specify permissions to use when opening the file or device: read-only .Pq Cm ro , write-only .Pq Cm wo , or read-write .Pq Cm rw . Default is .Cm rw . .It Fl s Ar sectorsize Sector size for .Nm ggate provider. If not specified, it is taken from the device, or set to 512 bytes for files. .It Fl t Ar timeout Number of seconds to wait before an I/O request will be canceled. 0 means no timeout. Default is 30. .It Fl u Ar unit Unit number to use. .It Fl v Do not fork, run in foreground and print debug information on standard output. .It Ar path Path to a regular file or device. .El .Sh EXIT STATUS Exit status is 0 on success, or 1 if the command fails. To get details about the failure, .Nm should be called with the .Fl v option. -.Sh EXAMPLES -.Dq GEOMify -the -.Dq Li fd0 -device and use -.Xr gbde 8 -to encrypt data on a floppy disk. -.Bd -literal -offset indent -ggatel create -u 5 /dev/fd0 -gbde init /dev/ggate5 -gbde attach ggate5 -newfs /dev/ggate5.bde -mount /dev/ggate5.bde /secret -cp /private/foo /secret/ -umount /secret -gbde detach ggate5 -ggatel destroy -u 5 .Ed .Sh SEE ALSO .Xr geom 4 , -.Xr gbde 8 , .Xr ggatec 8 , .Xr ggated 8 , .Xr mount 8 , .Xr newfs 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.3 . .Sh AUTHORS The .Nm utility as well as this manual page was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/share/man/man4/disk.4 b/share/man/man4/disk.4 index 6451ff0e7370..a6316d3fd268 100644 --- a/share/man/man4/disk.4 +++ b/share/man/man4/disk.4 @@ -1,208 +1,206 @@ .\" Copyright (c) 2020 M. Warner Losh .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd November 20, 2020 .Dt disk 4 .Os .Sh NAME .Nm disk .Nd common disk interfaces .Sh SYNOPSIS .Cd device cd .Sh DESCRIPTION Common block device IOCTLs .Pp All the block devices in the system should support these disk .Xr ioctl 2 commands defined here. Much of this information is also available via the .Xr geom 2 attributes. .Sh IOCTLS The following .Xr ioctl 2 calls apply to disk drives, and are defined in the .In sys/disk.h header file. .Bl -tag -width DIOCGPROVIDERNAME .It Dv DIOCGSECTORSIZE .Pq Li "u_int" Get the sector or block size of the device in bytes. The sector size is the smallest unit of data which can be transferred from this device. This is usually a power of 2 but it might not be (e.g. CDROM audio). Operations to block devices such as .Xr lseek 2 , .Xr read 2 , and .Xr write may only be performed at file offsets that are integral multiple of this size. .It Dv DIOCGMEDIASIZE .Pq Li "off_t" Get the size of the entire device in bytes. This should be a multiple of the sector size. .It Dv DIOCGFWSECTORS .Pq Li "u_int" Return the firmware's notion of number of sectors per track. This value is mostly used for compatibility with various ill designed disk label formats. Use this value only when absolutely required. Its interpretation and use is largely obsolete. .It Dv DIOCGFWHEADS .Pq Li "u_int" Return the firmware's notion of number of heads per cylinder. This value is mostly used for compatibility with various ill designed disk label formats. Use this value only when absolutely required. Its interpretation and use is largely obsolete. .It Dv DIOCGFLUSH Flush write cache of the device. .It Dv DIOCGDELETE .Pq Li "off_t[2]" Mark data on the device as unused. The first element is the offset to start deleting. The second element is the length to delete. Providers may use this information to free storage or instruct storage devices the contents can be discarded. .It Dv DIOCGIDENT .Pq Li "char[DISK_IDENT_SIZE]" Get the ident for this provider. Ident is a unique and fixed identifier for this provider. Ident's properties are as follow: .Bl -bullet .It preserved between reboots, .It preserved across a provider being detached/attached, .It provider's name can change - ident can't, .It ident value should not be based on on-disk metadata; in other words, copying whole data from one disk to another should not yield the same ident for the other disk, .It there can be more than one provider with the same ident, but only if they point at exactly the same physical storage, this is the case for multipathing for example, .It GEOM classes that consume a single provider and provide single provider, like .Xr geli 8 , -and -.Xr gbde 8 , the identifier should be formed by attaching that provider's class name to the ident of the underlying provider, .It ident is an NUL-terminated ASCII string (is printable), .It ident is optional and applications can't relay on its presence. .El .It Dv DIOCGPROVIDERNAME .Pq Li "char[MAXPATHLEN]" Store the provider name for the device in a buffer. The buffer must be at least MAXPATHLEN bytes long. .It Dv DIOCGSTRIPESIZE .Pq Li "off_t" Get the size of the device's optimal access block in bytes. This should be a multiple of the sector size. .It Dv DIOCGSTRIPEOFFSET .Pq Li "off_t" Get the offset of the first device's optimal access block in bytes. This should be a multiple of the sector size. .It Dv DIOCGPHYSPATH .Pq Li "char[MAXPATHLEN]" Get a string defining the physical path for a given provider. This has similar rules to ident, but is intended to uniquely identify the physical location of the device, not the current occupant of that location. The buffer must be at least MAXPATHLEN bytes long. .It Dv DIOCGATTR .Pq Li "struct diocgattr_arg" .Bd -literal -offset indent struct diocgattr_arg { char name[64]; int len; union { char str[DISK_IDENT_SIZE]; off_t off; int i; uint16_t u16; } value; }; .Ed Get a geom attribute from the provider. Format of the returned data is specific to the attribute. .It Dv DIOCZONECMD .Pq Li "struct disk_zone_arg" Send disk zone commands. .It Dv DIOCSKERNELDUMP .Pq Li "struct diocskerneldump_arg" Enable/Disable the device for kernel core dumps. .It Dv DIOCGKERNELDUMP .Pq Li "struct diocskerneldump_arg" Get current kernel netdump configuration details for a given index. .Bd -literal -offset indent /* * Sentinel values for kda_index. * * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. * * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified * device are cleared. * * If kda_index is KDA_REMOVE, only the specified dump configuration for the * given device is removed from the list of fallback dump configurations. * * If kda_index is KDA_APPEND, the dump configuration is added after all * existing dump configurations. * * Otherwise, the new configuration is inserted into the fallback dump list at * index 'kda_index'. */ #define KDA_REMOVE UINT8_MAX #define KDA_REMOVE_ALL (UINT8_MAX - 1) #define KDA_REMOVE_DEV (UINT8_MAX - 2) #define KDA_APPEND (UINT8_MAX - 3) struct diocskerneldump_arg { uint8_t kda_index; uint8_t kda_compression; uint8_t kda_encryption; uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; uint32_t kda_encryptedkeysize; uint8_t *kda_encryptedkey; char kda_iface[IFNAMSIZ]; union kd_ip kda_server; union kd_ip kda_client; union kd_ip kda_gateway; uint8_t kda_af; }; .Ed .El .Sh HISTORY The manual page was written by .An M Warner Losh Aq Mt imp@FreeBSD.org from text largely derived from .In sys/disk.h . diff --git a/sys/sys/bufobj.h b/sys/sys/bufobj.h index d70327e31a37..a6a9c5c2bf01 100644 --- a/sys/sys/bufobj.h +++ b/sys/sys/bufobj.h @@ -1,139 +1,139 @@ /*- * SPDX-License-Identifier: BSD-2-Clause * * Copyright (c) 2004 Poul-Henning Kamp * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ /* * Architectural notes: * * bufobj is a new object which is what buffers hang from in the buffer * cache. * * This used to be vnodes, but we need non-vnode code to be able - * to use the buffer cache as well, specifically geom classes like gbde, + * to use the buffer cache as well, specifically geom classes like * raid3 and raid5. * * All vnodes will contain a bufobj initially, but down the road we may * want to only allocate bufobjs when they are needed. There could be a * large number of vnodes in the system which wouldn't need a bufobj during * their lifetime. * * The exact relationship to the vmobject is not determined at this point, * it may in fact be that we find them to be two sides of the same object * once things starts to crystalize. */ #ifndef _SYS_BUFOBJ_H_ #define _SYS_BUFOBJ_H_ #if defined(_KERNEL) || defined(_KVM_VNODE) #include #include #include #include struct bufobj; struct buf_ops; extern struct buf_ops buf_ops_bio; TAILQ_HEAD(buflists, buf); /* A Buffer list & trie */ struct bufv { struct buflists bv_hd; /* Sorted blocklist */ struct pctrie bv_root; /* Buf trie */ int bv_cnt; /* Number of buffers */ }; typedef void b_strategy_t(struct bufobj *, struct buf *); typedef int b_write_t(struct buf *); typedef int b_sync_t(struct bufobj *, int waitfor); typedef void b_bdflush_t(struct bufobj *, struct buf *); struct buf_ops { const char *bop_name; b_write_t *bop_write; b_strategy_t *bop_strategy; b_sync_t *bop_sync; b_bdflush_t *bop_bdflush; }; #define BO_STRATEGY(bo, bp) ((bo)->bo_ops->bop_strategy((bo), (bp))) #define BO_SYNC(bo, w) ((bo)->bo_ops->bop_sync((bo), (w))) #define BO_WRITE(bo, bp) ((bo)->bo_ops->bop_write((bp))) #define BO_BDFLUSH(bo, bp) ((bo)->bo_ops->bop_bdflush((bo), (bp))) /* * Locking notes: * 'S' is sync_mtx * 'v' is the vnode lock which embeds the bufobj. * '-' Constant and unchanging after initialization. */ struct bufobj { struct rwlock bo_lock; /* Lock which protects "i" things */ struct buf_ops *bo_ops; /* - Buffer operations */ struct vm_object *bo_object; /* v Place to store VM object */ LIST_ENTRY(bufobj) bo_synclist; /* S dirty vnode list */ void *bo_private; /* private pointer */ struct bufv bo_clean; /* i Clean buffers */ struct bufv bo_dirty; /* i Dirty buffers */ int bo_numoutput; /* i Writes in progress */ u_int bo_flag; /* i Flags */ int bo_domain; /* - Clean queue affinity */ int bo_bsize; /* - Block size for i/o */ }; /* * XXX BO_ONWORKLST could be replaced with a check for NULL list elements * in v_synclist. */ #define BO_ONWORKLST (1 << 0) /* On syncer work-list */ #define BO_WWAIT (1 << 1) /* Wait for output to complete */ #define BO_DEAD (1 << 2) /* Dead; only with INVARIANTS */ #define BO_NOBUFS (1 << 3) /* No bufs allowed */ #define BO_LOCKPTR(bo) (&(bo)->bo_lock) #define BO_LOCK(bo) rw_wlock(BO_LOCKPTR((bo))) #define BO_UNLOCK(bo) rw_wunlock(BO_LOCKPTR((bo))) #define BO_RLOCK(bo) rw_rlock(BO_LOCKPTR((bo))) #define BO_RUNLOCK(bo) rw_runlock(BO_LOCKPTR((bo))) #define ASSERT_BO_WLOCKED(bo) rw_assert(BO_LOCKPTR((bo)), RA_WLOCKED) #define ASSERT_BO_LOCKED(bo) rw_assert(BO_LOCKPTR((bo)), RA_LOCKED) #define ASSERT_BO_UNLOCKED(bo) rw_assert(BO_LOCKPTR((bo)), RA_UNLOCKED) void bufobj_init(struct bufobj *bo, void *priv); void bufobj_wdrop(struct bufobj *bo); void bufobj_wref(struct bufobj *bo); void bufobj_wrefl(struct bufobj *bo); int bufobj_invalbuf(struct bufobj *bo, int flags, int slpflag, int slptimeo); int bufobj_wwait(struct bufobj *bo, int slpflag, int timeo); int bufsync(struct bufobj *bo, int waitfor); void bufbdflush(struct bufobj *bo, struct buf *bp); #endif /* defined(_KERNEL) || defined(_KVM_VNODE) */ #endif /* _SYS_BUFOBJ_H_ */ diff --git a/sys/sys/disk.h b/sys/sys/disk.h index 73ae5ce5756e..b8e29cef1de5 100644 --- a/sys/sys/disk.h +++ b/sys/sys/disk.h @@ -1,181 +1,181 @@ /*- * SPDX-License-Identifier: Beerware * * ---------------------------------------------------------------------------- * "THE BEER-WARE LICENSE" (Revision 42): * wrote this file. As long as you retain this notice you * can do whatever you want with this stuff. If we meet some day, and you think * this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp * ---------------------------------------------------------------------------- * */ #ifndef _SYS_DISK_H_ #define _SYS_DISK_H_ #include #include #include #include #include #ifdef _KERNEL void disk_err(struct bio *bp, const char *what, int blkdone, int nl); #endif #define DIOCGSECTORSIZE _IOR('d', 128, u_int) /* * Get the sector size of the device in bytes. The sector size is the * smallest unit of data which can be transferred from this device. * Usually this is a power of 2 but it might not be (i.e. CDROM audio). */ #define DIOCGMEDIASIZE _IOR('d', 129, off_t) /* Get media size in bytes */ /* * Get the size of the entire device in bytes. This should be a * multiple of the sector size. */ #define DIOCGFWSECTORS _IOR('d', 130, u_int) /* Get firmware's sectorcount */ /* * Get the firmware's notion of number of sectors per track. This * value is mostly used for compatibility with various ill designed * disk label formats. Don't use it unless you have to. */ #define DIOCGFWHEADS _IOR('d', 131, u_int) /* Get firmware's headcount */ /* * Get the firmwares notion of number of heads per cylinder. This * value is mostly used for compatibility with various ill designed * disk label formats. Don't use it unless you have to. */ #define DIOCGFLUSH _IO('d', 135) /* Flush write cache */ /* * Flush write cache of the device. */ #define DIOCGDELETE _IOW('d', 136, off_t[2]) /* Delete data */ /* * Mark data on the device as unused. */ #define DISK_IDENT_SIZE 256 #define DIOCGIDENT _IOR('d', 137, char[DISK_IDENT_SIZE]) /*- * Get the ident of the given provider. Ident is (most of the time) * a uniqe and fixed provider's identifier. Ident's properties are as * follow: * - ident value is preserved between reboots, * - provider can be detached/attached and ident is preserved, * - provider's name can change - ident can't, * - ident value should not be based on on-disk metadata; in other * words copying whole data from one disk to another should not * yield the same ident for the other disk, * - there could be more than one provider with the same ident, but * only if they point at exactly the same physical storage, this is * the case for multipathing for example, * - GEOM classes that consumes single providers and provide single - * providers, like geli, gbde, should just attach class name to the + * providers, like geli, should just attach class name to the * ident of the underlying provider, * - ident is an ASCII string (is printable), * - ident is optional and applications can't relay on its presence. */ #define DIOCGPROVIDERNAME _IOR('d', 138, char[MAXPATHLEN]) /* * Store the provider name, given a device path, in a buffer. The buffer * must be at least MAXPATHLEN bytes long. */ #define DIOCGSTRIPESIZE _IOR('d', 139, off_t) /* Get stripe size in bytes */ /* * Get the size of the device's optimal access block in bytes. * This should be a multiple of the sector size. */ #define DIOCGSTRIPEOFFSET _IOR('d', 140, off_t) /* Get stripe offset in bytes */ /* * Get the offset of the first device's optimal access block in bytes. * This should be a multiple of the sector size. */ #define DIOCGPHYSPATH _IOR('d', 141, char[MAXPATHLEN]) /* * Get a string defining the physical path for a given provider. * This has similar rules to ident, but is intended to uniquely * identify the physical location of the device, not the current * occupant of that location. */ struct diocgattr_arg { char name[64]; int len; union { char str[DISK_IDENT_SIZE]; off_t off; int i; uint16_t u16; } value; }; #define DIOCGATTR _IOWR('d', 142, struct diocgattr_arg) #define DIOCZONECMD _IOWR('d', 143, struct disk_zone_args) #ifndef WITHOUT_NETDUMP #include #include union kd_ip { struct in_addr in4; struct in6_addr in6; }; /* * Sentinel values for kda_index. * * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. * * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified * device are cleared. * * If kda_index is KDA_REMOVE, only the specified dump configuration for the * given device is removed from the list of fallback dump configurations. * * If kda_index is KDA_APPEND, the dump configuration is added after all * existing dump configurations. * * Otherwise, the new configuration is inserted into the fallback dump list at * index 'kda_index'. */ #define KDA_REMOVE UINT8_MAX #define KDA_REMOVE_ALL (UINT8_MAX - 1) #define KDA_REMOVE_DEV (UINT8_MAX - 2) #define KDA_APPEND (UINT8_MAX - 3) struct diocskerneldump_arg { uint8_t kda_index; uint8_t kda_compression; uint8_t kda_encryption; uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; uint32_t kda_encryptedkeysize; uint8_t *kda_encryptedkey; char kda_iface[IFNAMSIZ]; union kd_ip kda_server; union kd_ip kda_client; union kd_ip kda_gateway; uint8_t kda_af; }; #define DIOCSKERNELDUMP _IOW('d', 145, struct diocskerneldump_arg) /* * Enable/Disable the device for kernel core dumps. */ #define DIOCGKERNELDUMP _IOWR('d', 146, struct diocskerneldump_arg) /* * Get current kernel netdump configuration details for a given index. */ #endif #endif /* _SYS_DISK_H_ */