Date: Tue, 29 Apr 2014 15:23:56 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201404291523.s3TFNugF097334@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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.</para> <para>Regardless of how an attacker may have come into possession - of a hard drive or powered-down computer, both the GEOM Based - Disk Encryption (<command>gbde</command>) and - <command>geli</command> cryptographic subsystems in &os; are + of a hard drive or powered-down computer, the <acronym>GEOM</acronym>-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, - <command>gbde</command> and <command>geli</command> + Unlike encryption methods that encrypt individual files, the built-in + <command>gbde</command> and <command>geli</command> utilities can be used to transparently encrypt entire file systems. No cleartext ever touches the hard drive's platter.</para> + <para>This chapter demonstrates how to create an encrypted file + system on &os;. It first demonstrates the process using + <command>gbde</command> and then demonstrates the same example + using <command>geli</command>.</para> + <sect2> <title>Disk Encryption with <application>gbde</application></title> @@ -2760,23 +2764,21 @@ What about bsdinstall? </authorgroup> </info> - <para>An alternative cryptographic GEOM class is available - through &man.geli.8;. <command>geli</command> differs from - <command>gbde</command>; offers different features, and uses - a different scheme for doing cryptographic work.</para> - - <para>&man.geli.8; provides the following features:</para> + <para>An alternative cryptographic <acronym>GEOM</acronym> class is available + using <command>geli</command>. This control utility adds + some features and uses + a different scheme for doing cryptographic work. It provides + the following features:</para> <itemizedlist> <listitem> - <para>Utilizes the &man.crypto.9; framework and, when - cryptographic hardware is available, - <command>geli</command> uses it automatically.</para> + <para>Utilizes the &man.crypto.9; framework and automatically uses + cryptographic hardware when it is available.</para> </listitem> <listitem> <para>Supports multiple cryptographic algorithms such as - AES, Blowfish, and 3DES.</para> + <acronym>AES</acronym>, Blowfish, and <acronym>3DES</acronym>.</para> </listitem> <listitem> @@ -2786,13 +2788,11 @@ What about bsdinstall? </listitem> <listitem> - <para>Allows the use of two independent keys such as a - <quote>key</quote> and a - <quote>company key</quote>.</para> + <para>Allows the use of two independent keys.</para> </listitem> <listitem> - <para><command>geli</command> is fast as it performs simple + <para>It is fast as it performs simple sector-to-sector encryption.</para> </listitem> @@ -2809,61 +2809,57 @@ What about bsdinstall? </listitem> </itemizedlist> - <para>More <command>geli</command> features can be found in + <para>More features and usage examples can be found in &man.geli.8;.</para> - <para>This section describes how to enable support for - <command>geli</command> in the &os; kernel and explains how - to create and use a <command>geli</command> encryption - provider.</para> - - <para>Superuser privileges are required since modifications - to the kernel are necessary.</para> + <para>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 + <filename>/private</filename>. 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 + <command>geli</command> provider, create a file system on + it, mount it, work with it, and finally, how to detach + it.</para> <procedure> + <title>Encrypting a Partition with + <command>geli</command></title> + <step> - <title>Adding <command>geli</command> Support to the - Kernel</title> + <title>Load <command>geli</command> Support</title> + + <para>Support for <command>geli</command> is built into the + <filename>GENERIC</filename> kernel. To configure the + system to automatically load the module + at boot time, add the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>geom_eli_load="YES"</programlisting> + + <para>To load the kernel module now:</para> + + <screen>&prompt.root; <userinput>kldload geom_eli</userinput></screen> <para>For a custom kernel, ensure the kernel configuration file contains these lines:</para> <programlisting>options GEOM_ELI device crypto</programlisting> - - <para>Alternatively, the <command>geli</command> module can - be loaded at boot time by adding the following line to - <filename>/boot/loader.conf</filename>:</para> - - <programlisting>geom_eli_load="YES"</programlisting> - - <para>&man.geli.8; should now be supported by the - kernel.</para> </step> <step> - <title>Generating the Master Key</title> + <title>Generate the Master Key</title> - <para>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 - <filename>/private</filename>. 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 - <command>geli</command> provider, create a file system on - it, mount it, work with it, and finally, how to detach - it.</para> - - <para>It is recommended to use a bigger sector size, such as - 4kB, for better performance.</para> - - <para>The master key will be protected with a passphrase and - the data source for the key file will be - <filename>/dev/random</filename>. The sector size of - the provider <filename>/dev/da2.eli</filename> will be - 4kB.</para> + <para>The following commands generate a master key + (<filename>/root/da2.key</filename>) that is protected with a passphrase. + The data source for the key file is + <filename>/dev/random</filename> and the sector size of + the provider (<filename>/dev/da2.eli</filename>) is + 4kB as a bigger sector size provides + better performance:</para> <screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput> &prompt.root; <userinput>geli init -s 4096 -K /root/da2.key /dev/da2</userinput> @@ -2875,34 +2871,41 @@ Reenter new passphrase:</screen> used in isolation.</para> <para>If the key file is given as <quote>-</quote>, standard - input will be used. This example shows how more than one - key file can be used:</para> + input will be used. For example, this command generates three + key files:</para> <screen>&prompt.root; <userinput>cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2</userinput></screen> </step> <step> - <title>Attaching the Provider with the Generated Key</title> + <title>Attach the Provider with the Generated Key</title> + + <para>To attach the provider, specify the key file, the name + of the disk, and the passphrase:</para> <screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput> Enter passphrase:</screen> - <para>The new plaintext device will be named - <filename>/dev/<replaceable>da2</replaceable>.eli</filename>.</para> + <para>This creates a new device with an + <filename>.eli</filename> extension:</para> <screen>&prompt.root; <userinput>ls /dev/da2*</userinput> /dev/da2 /dev/da2.eli</screen> </step> <step> - <title>Creating the New File System</title> + <title>Create the New File System</title> + + <para>Next, format the device with the + <acronym>UFS</acronym> file system and mount it on an + existing mount point:</para> <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/da2.eli bs=1m</userinput> &prompt.root; <userinput>newfs /dev/da2.eli</userinput> -&prompt.root; <userinput>mount /dev/da2.eli /private</userinput></screen> +&prompt.root; <userinput>mount /dev/da2.eli <replaceable>/private</replaceable></userinput></screen> - <para>The encrypted file system should now be visible to - &man.df.1; and be available for use:</para> + <para>The encrypted file system should now be available for + use:</para> <screen>&prompt.root; <userinput>df -H</userinput> 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</screen> </step> - - <step> - <title>Unmounting and Detaching the Provider</title> + </procedure> <para>Once the work on the encrypted partition is done, and the <filename>/private</filename> - 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 <command>geli</command> encrypted partition from the kernel:</para> <screen>&prompt.root; <userinput>umount /private</userinput> &prompt.root; <userinput>geli detach da2.eli</userinput></screen> - </step> - </procedure> - - <para>More information about the use of &man.geli.8; can be - found in its manual page.</para> - - <sect3> - <title>Using the <filename>geli</filename> - <filename>rc.d</filename> Script</title> - <para><command>geli</command> comes with a - <filename>rc.d</filename> script which can be used to - simplify the usage of <command>geli</command>. An example - of configuring <command>geli</command> through - &man.rc.conf.5; follows:</para> + <para>An + <filename>rc.d</filename> script is provided to + simplify the mounting of <command>geli</command>-encrypted + devices at boot time. For this example, add these lines to + <filename>/etc/rc.conf</filename>:</para> - <programlisting>geli_devices="da2" -geli_da2_flags="-p -k /root/da2.key"</programlisting> + <programlisting>geli_devices="<replaceable>da2</replaceable>" +geli_da2_flags="-p -k /root/<replaceable>da2.key</replaceable>"</programlisting> <para>This configures <filename>/dev/da2</filename> as a <command>geli</command> provider with a master key - file of <filename>/root/da2.key</filename>. - <command>geli</command> will not use a passphrase when - attaching to the provider if - <option>-P</option> was given during the - <literal>geli init</literal> phase. The system will detach - the <command>geli</command> provider from the kernel before - the system shuts down.</para> - - <note> - <para>During the startup process, scripts prompt for the - passphrase before attaching the <acronym>GELI</acronym> + of <filename>/root/da2.key</filename>. + 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.</para> - - <para>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 - <filename>/etc/fstab</filename> (see - &man.fstab.5;).</para> - - <para>Later in the startup process, &os; configures - <acronym>GELI</acronym> providers to automatically detach. - <acronym>GELI</acronym> providers without any consumers - will detach at that time.</para> - </note> - - <para>More information about configuring - <filename>rc.d</filename> is provided in the - <link linkend="configtuning-rcd">rc.d</link> section of the - Handbook.</para> - </sect3> + other messages. Once the correct passphrase is entered, the provider is + attached. The file system is then mounted, + typically by an entry in + <filename>/etc/fstab</filename>. Refer to <xref + linkend="mount-unmount"/> for instructions on how to + configure a file system to mount at boot time.</para> </sect2> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404291523.s3TFNugF097334>