From owner-svn-doc-head@FreeBSD.ORG Tue Apr 29 15:23:56 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id CF3FB852; Tue, 29 Apr 2014 15:23:56 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id AF08D1329; Tue, 29 Apr 2014 15:23:56 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3TFNurH097335; Tue, 29 Apr 2014 15:23:56 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3TFNugF097334; Tue, 29 Apr 2014 15:23:56 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404291523.s3TFNugF097334@svn.freebsd.org> From: Dru Lavigne Date: Tue, 29 Apr 2014 15:23:56 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44694 - head/en_US.ISO8859-1/books/handbook/disks X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Apr 2014 15:23:56 -0000 Author: dru Date: Tue Apr 29 15:23:56 2014 New Revision: 44694 URL: http://svnweb.freebsd.org/changeset/doc/44694 Log: Editorial review of geli section. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Apr 29 02:50:31 2014 (r44693) +++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Apr 29 15:23:56 2014 (r44694) @@ -2519,16 +2519,20 @@ Quotas for user test: analyze the data. Regardless of how an attacker may have come into possession - of a hard drive or powered-down computer, both the GEOM Based - Disk Encryption (gbde) and - geli cryptographic subsystems in &os; are + of a hard drive or powered-down computer, the GEOM-based + cryptographic subsystems built into &os; are able to protect the data on the computer's file systems against even highly-motivated attackers with significant resources. - Unlike encryption methods that encrypt individual files, - gbde and geli + Unlike encryption methods that encrypt individual files, the built-in + gbde and geli utilities can be used to transparently encrypt entire file systems. No cleartext ever touches the hard drive's platter. + This chapter demonstrates how to create an encrypted file + system on &os;. It first demonstrates the process using + gbde and then demonstrates the same example + using geli. + Disk Encryption with <application>gbde</application> @@ -2760,23 +2764,21 @@ What about bsdinstall? - An alternative cryptographic GEOM class is available - through &man.geli.8;. geli differs from - gbde; offers different features, and uses - a different scheme for doing cryptographic work. - - &man.geli.8; provides the following features: + An alternative cryptographic GEOM class is available + using geli. This control utility adds + some features and uses + a different scheme for doing cryptographic work. It provides + the following features: - Utilizes the &man.crypto.9; framework and, when - cryptographic hardware is available, - geli uses it automatically. + Utilizes the &man.crypto.9; framework and automatically uses + cryptographic hardware when it is available. Supports multiple cryptographic algorithms such as - AES, Blowfish, and 3DES. + AES, Blowfish, and 3DES. @@ -2786,13 +2788,11 @@ What about bsdinstall? - Allows the use of two independent keys such as a - key and a - company key. + Allows the use of two independent keys. - geli is fast as it performs simple + It is fast as it performs simple sector-to-sector encryption. @@ -2809,61 +2809,57 @@ What about bsdinstall? - More geli features can be found in + More features and usage examples can be found in &man.geli.8;. - This section describes how to enable support for - geli in the &os; kernel and explains how - to create and use a geli encryption - provider. - - Superuser privileges are required since modifications - to the kernel are necessary. + The following example describes how to generate a + key file which will be used as part of the master key for + the encrypted provider mounted under + /private. The key + file will provide some random data used to encrypt the + master key. The master key will also be protected by a + passphrase. The provider's sector size will be 4kB. + The example describes how to attach to the + geli provider, create a file system on + it, mount it, work with it, and finally, how to detach + it. + Encrypting a Partition with + <command>geli</command> + - Adding <command>geli</command> Support to the - Kernel + Load <command>geli</command> Support + + Support for geli is built into the + GENERIC kernel. To configure the + system to automatically load the module + at boot time, add the following line to + /boot/loader.conf: + + geom_eli_load="YES" + + To load the kernel module now: + + &prompt.root; kldload geom_eli For a custom kernel, ensure the kernel configuration file contains these lines: options GEOM_ELI device crypto - - Alternatively, the geli module can - be loaded at boot time by adding the following line to - /boot/loader.conf: - - geom_eli_load="YES" - - &man.geli.8; should now be supported by the - kernel. - Generating the Master Key + Generate the Master Key - The following example describes how to generate a - key file which will be used as part of the master key for - the encrypted provider mounted under - /private. The key - file will provide some random data used to encrypt the - master key. The master key will also be protected by a - passphrase. The provider's sector size will be 4kB. - The example will describe how to attach to the - geli provider, create a file system on - it, mount it, work with it, and finally, how to detach - it. - - It is recommended to use a bigger sector size, such as - 4kB, for better performance. - - The master key will be protected with a passphrase and - the data source for the key file will be - /dev/random. The sector size of - the provider /dev/da2.eli will be - 4kB. + The following commands generate a master key + (/root/da2.key) that is protected with a passphrase. + The data source for the key file is + /dev/random and the sector size of + the provider (/dev/da2.eli) is + 4kB as a bigger sector size provides + better performance: &prompt.root; dd if=/dev/random of=/root/da2.key bs=64 count=1 &prompt.root; geli init -s 4096 -K /root/da2.key /dev/da2 @@ -2875,34 +2871,41 @@ Reenter new passphrase: used in isolation. If the key file is given as -, standard - input will be used. This example shows how more than one - key file can be used: + input will be used. For example, this command generates three + key files: &prompt.root; cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2 - Attaching the Provider with the Generated Key + Attach the Provider with the Generated Key + + To attach the provider, specify the key file, the name + of the disk, and the passphrase: &prompt.root; geli attach -k /root/da2.key /dev/da2 Enter passphrase: - The new plaintext device will be named - /dev/da2.eli. + This creates a new device with an + .eli extension: &prompt.root; ls /dev/da2* /dev/da2 /dev/da2.eli - Creating the New File System + Create the New File System + + Next, format the device with the + UFS file system and mount it on an + existing mount point: &prompt.root; dd if=/dev/random of=/dev/da2.eli bs=1m &prompt.root; newfs /dev/da2.eli -&prompt.root; mount /dev/da2.eli /private +&prompt.root; mount /dev/da2.eli /private - The encrypted file system should now be visible to - &man.df.1; and be available for use: + The encrypted file system should now be available for + use: &prompt.root; df -H Filesystem Size Used Avail Capacity Mounted on @@ -2913,72 +2916,43 @@ Filesystem Size Used Avail Capaci /dev/ad0s1e 3.9G 1.3G 2.3G 35% /var /dev/da2.eli 150G 4.1K 138G 0% /private - - - Unmounting and Detaching the Provider + Once the work on the encrypted partition is done, and the /private - partition is no longer needed, it is prudent to consider + partition is no longer needed, it is prudent to put the + device into cold storage by unmounting and detaching the geli encrypted partition from the kernel: &prompt.root; umount /private &prompt.root; geli detach da2.eli - - - - More information about the use of &man.geli.8; can be - found in its manual page. - - - Using the <filename>geli</filename> - <filename>rc.d</filename> Script - geli comes with a - rc.d script which can be used to - simplify the usage of geli. An example - of configuring geli through - &man.rc.conf.5; follows: + An + rc.d script is provided to + simplify the mounting of geli-encrypted + devices at boot time. For this example, add these lines to + /etc/rc.conf: - geli_devices="da2" -geli_da2_flags="-p -k /root/da2.key" + geli_devices="da2" +geli_da2_flags="-p -k /root/da2.key" This configures /dev/da2 as a geli provider with a master key - file of /root/da2.key. - geli will not use a passphrase when - attaching to the provider if - was given during the - geli init phase. The system will detach - the geli provider from the kernel before - the system shuts down. - - - During the startup process, scripts prompt for the - passphrase before attaching the GELI + of /root/da2.key. + The system will automatically detach + the provider from the kernel before + the system shuts down. During the startup process, the script will prompt for the + passphrase before attaching the provider. Other kernel messages might be shown before and after the password prompt. If the boot process seems to stall, look carefully for the password prompt among the - other messages. - - When the correct password is given, the provider is - attached. A consumer, like a file system, is then mounted - on the provider, typically by an entry in - /etc/fstab (see - &man.fstab.5;). - - Later in the startup process, &os; configures - GELI providers to automatically detach. - GELI providers without any consumers - will detach at that time. - - - More information about configuring - rc.d is provided in the - rc.d section of the - Handbook. - + other messages. Once the correct passphrase is entered, the provider is + attached. The file system is then mounted, + typically by an entry in + /etc/fstab. Refer to for instructions on how to + configure a file system to mount at boot time.