docs/51598: Submission of disk encryption section the Handbook
Lucky Green
shamrock at cypherpunks.to
Tue Apr 29 20:00:35 UTC 2003
>Number: 51598
>Category: docs
>Synopsis: Submission of disk encryption section the Handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Apr 29 13:00:32 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Lucky Green
>Release: FreeBSD 5.0-CURRENT i386
>Organization:
>Environment:
System: FreeBSD pakastelohi.cypherpunks.to 5.0-CURRENT FreeBSD 5.0-CURRENT #4: Sun Apr 20 22:10:13 CEST 2003 toor at pakastelohi.cypherpunks.to:/usr/obj/usr/src/sys/2003041501 i386
>Description:
Attached is a patch to
/usr/doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml
This patch adds a new subsection to the Handbook. The section explains how
to encrypt hard drives using gbde(4)(8). It is my hope that this documentation
will save others countless hours while increasing the use of drive
encryption.
Thanks go to phk@ for writing gbde and answering my numerous inquiries and to
the FreeBSD doc team for answering my newbie questions about the SGML markup process.
Thanks also to mike_home for showing me how to get the indentation right
using emacs.
>How-To-Repeat:
<code/input/activities to reproduce the problem (multiple lines)>
>How-To-Repeat:
>Fix:
--- chapter.sgml.diff begins here ---
*** chapter.sgml.dist Thu Apr 3 03:46:52 2003
--- chapter.sgml Tue Apr 29 12:02:33 2003
***************
*** 30,35 ****
--- 30,38 ----
<para>How to use quotas to limit disk space usage.</para>
</listitem>
<listitem>
+ <para>How to encrypt disks to secure them against attackers.</para>
+ </listitem>
+ <listitem>
<para>How to create and burn CDs and DVDs on FreeBSD.</para>
</listitem>
<listitem>
***************
*** 42,48 ****
<para>How to backup to floppy disks.</para>
</listitem>
<listitem>
! <para>What snapshots are and how to use them efficiently.</para>
</listitem>
</itemizedlist>
</sect1>
--- 45,51 ----
<para>How to backup to floppy disks.</para>
</listitem>
<listitem>
! <para>What snapshots are and how to use them efficiently.</para>
</listitem>
</itemizedlist>
</sect1>
***************
*** 2730,2735 ****
--- 2733,3047 ----
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
</sect2>
+ </sect1>
+
+
+ <sect1 id="disks-encrypting">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Lucky</firstname>
+ <surname>Green</surname>
+ <contrib>Contributed by </contrib>
+ <affiliation>
+ <address><email>shamrock at cypherpunks.to</email></address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ <!-- 11 MARCH 2003 -->
+ </sect1info>
+
+ <title>Encrypting Disk Partitions</title>
+ <indexterm>
+ <primary>disks</primary>
+ <secondary>encrypting</secondary></indexterm>
+
+ <!-- I wonder if there is an SGML tag that would make Mandatory Access Control the hyperlink? -->
+ <para>FreeBSD offers excellent protections against users of a server gaining
+ unauthorized access to data. File permissions and Mandatory Access Control (MAC)
+ (see <xref linkend="mac">) prevent unauthorized
+ third-parties from accessing data while the operating system is active and the
+ computer is powered up. However, permissions enforced by the operating system
+ cannot prevent an attacker who obtained physical access to a lost, stolen, or
+ seized computer from simply removing the computer's hard drive, mounting
+ the drive on another server, and copying all of the data stored on the drive for
+ further analysis.</para>
+
+ <para>Regardless of how an attacker may have come into possession of
+ a hard drive or powered-down computer, <application>GEOM Based Disk Encryption (gbde)</application>
+ can protect the data on the computer's file systems against even
+ highly-motivated attackers with significant resources. Unlike cumbersome encryption methods that encrypt only individual
+ files, <application>gbde</application> transparently encrypts entire file systems. No cleartext ever
+ touches the hard drive's platter.</para>
+
+ <sect2>
+ <title>Enabling gbde in the kernel</title>
+
+ <procedure>
+ <step>
+ <title>Become root</title>
+
+ <para>Configuring <application>gbde</application> requires super-user privileges.</para>
+
+ <screen>
+ &prompt.user; <userinput>su -</userinput>
+ Password:
+ </screen>
+ </step>
+
+ <step>
+ <title>Verify the operating system version</title>
+
+ <para>&man.gbde.4; requires FreeBSD 5.0 or higher.</para>
+
+ <screen>
+ &prompt.root; <userinput>uname -r</userinput>
+ 5.0-RELEASE
+ </screen>
+ </step>
+
+ <step>
+ <title>Add &man.gbde.4; support to the configuration file</title>
+
+ <para>Using your favorite text editor, add the following
+ line to your kernel configuration file:</para>
+
+ <para><filename>options GEOM_BDE</filename></para>
+
+ <para>Configure and recompile the FreeBSD kernel. If you
+ don't know how to create a custom kernel, see <xref linkend="kernelconfig">.</para>
+
+ <para>Reboot into the new kernel.</para>
+ </step>
+ </procedure>
+ </sect2>
+
+
+ <sect2>
+ <title>Preparing the encrypted hard drive</title>
+
+ <para>The following example assumes that you are adding a new hard drive to your system that will hold a single encrypted
+ partition. This partition will be mounted as <filename>/private</filename>.
+ <application>gbde</application> can also be
+ used to encrypt <filename>/home</filename> and <filename>/var/mail</filename>,
+ but this requires more complex instructions which exceed the scope of this introduction.</para>
+
+ <procedure>
+ <step>
+ <title>Add the new hard drive</title>
+
+ <para>
+ Install the new drive to the system as explained in <xref linkend="disks-adding">. For the purposes of this example, the a new hard drive partition has
+ been added as <filename>/dev/ad4s1c</filename>. A drive, <filename>/dev/ad0s1</filename>, which holds the normal FreeBSD
+ partitions, previously already existed on the example system.</para>
+
+ <screen>
+ &prompt.root; <userinput>ls /dev/ad*</userinput>
+ /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1
+ /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c
+ /dev/ad0s1a /dev/ad0s1d /dev/ad4
+ </screen>
+ </step>
+
+ <step>
+ <title>Create a directory to hold GBDE lock files</title>
+
+ <screen>
+ &prompt.root; <userinput>mkdir /etc/gbde</userinput>
+ </screen>
+
+ <para>The <application>gbde</application> lock file contains information that <application>gbde</application> requires to access encrypted
+ partitions. Without access to the lock file, <application>gbde</application> will not be able to decrypt
+ the data contained in the encrypted partition without significant manual
+ intervention which is not supported by the software. Each encrypted partition uses a separate lock file.</para>
+ </step>
+
+ <step>
+ <title>Initialize the gbde partition</title>
+
+ <para>A <application>gbde</application> partition must be initialized
+ before it can be used. This initialization needs to be performed only once.</para>
+
+ <screen>
+ &prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c</userinput>
+ </screen>
+
+ <para>&man.gbde.8; will open your editor, permitting you to set various configuration options in a template. For use with UFS or UFS2, set the sector_size to 2048.</para>
+
+ <programlisting>$FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $
+ #
+ # Sector size is the smallest unit of data which can be read or written.
+ # Making it too small decreases performance and decreases available space.
+ # Making it too large may prevent filesystems from working. 512 is the
+ # minimum and always safe. For UFS, use the fragment size
+ #
+ sector_size = 2048
+ [...]
+ </programlisting>
+
+ <para>&man.gbde.8; will twice ask you to type the passphrase that should be used to secure the data. The passphrase must be
+ the same both times. <application>gbde's</application> ability to protect your data depends entirely on
+ the quality of the passphrase that you choose.</para>
+
+ <para>For tips on how to select a secure passphrase that is easy to remember,
+ see the <ulink url="http://world.std.com/~reinhold/diceware.html">Diceware Passphrase</ulink> website.</para>
+
+ <para>The <command>gbde init</command> command created a lock file for your <application>gbde</application> partition that in this example has been
+ stored as <filename>/etc/gbde/ad4s1c</filename>.</para>
+
+ <caution>
+ <para><application>gbde</application> lock files <emphasis>must</emphasis> be backed
+ up together with the contents of any encrypted partitions. While deleting a lock
+ file alone cannot prevent a determined attacker from decrypting a <application>gbde</application>
+ partition, without the lock file, the legitimate owner will be unable to
+ access the data on the encrypted partition without a significant amount of work
+ that is totally unsupported by &man.gbde.8; and its designer.</para>
+ </caution>
+ </step>
+
+ <step>
+ <title>Attach the encrypted partition to the kernel</title>
+
+ <screen>
+ &prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput>
+ </screen>
+
+ <para> You will be asked to provide the passphrase that you selected during the
+ initialization of the encrypted partition. The new encrypted device will show up in
+ <filename>/dev</filename> as <filename>/dev/device_name.bde</filename>:</para>
+
+ <screen>
+ &prompt.root; <userinput>ls /dev/ad*</userinput>
+ /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1
+ /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c
+ /dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde
+ </screen>
+ </step>
+
+ <step>
+ <title>Create a file system on the encrypted device</title>
+
+ <para>Once the encrypted device has been attached to the kernel, you can create a file system on the device. To
+ create a file system on the encrypted device, use &man.newfs.8;. Since it is much
+ faster to initialize a new UFS2 file system than it is to initialize
+ the old UFS file system, using &man.newfs.8; with the <command>-O2</command> option is recommended.</para>
+
+ <screen>
+ &prompt.root; <userinput>newfs -U -O2 /dev/ad4s1c.bde</userinput>
+ </screen>
+
+ <note>
+ <para>The newfs must be performed on an attached <application>gbde</application> partition which is identified by a *.bde extension to the device name.</para>
+ </note>
+ </step>
+
+ <step>
+ <title>Mount the encrypted partition</title>
+
+ <para>Create a mount point for the encrypted file system.</para>
+
+ <screen>
+ &prompt.root; <userinput>mkdir /private</userinput>
+ </screen>
+
+ <para>Mount the encrypted file system.</para>
+
+ <screen>
+ &prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput>
+ </screen>
+ </step>
+
+ <step>
+ <title>Verify that the encrypted file system is available</title>
+
+ <para>The encrypted file system should now be visible to &man.df.1; and be available for use.</para>
+
+ <screen>
+ &prompt.user; <userinput>df -H</userinput>
+ Filesystem Size Used Avail Capacity Mounted on
+ /dev/ad0s1a 1037M 72M 883M 8%
+ /devfs 1.0K 1.0K 0B 100% /dev
+ /dev/ad0s1f 8.1G 55K 7.5G 0% /home
+ /dev/ad0s1e 1037M 1.1M 953M 0% /tmp
+ /dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr
+ /dev/ad4s1c.bde 150G 4.1K 138G 0% /private
+ </screen>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2>
+ <title>Mounting existing encrypted file systems</title>
+
+ <para>After each boot, any encrypted file systems must be re-attached to the kernel,
+ checked for errors, and mounted, before the file systems can be used. The
+ required commands must be executed as user root.</para>
+
+ <procedure>
+ <step>
+ <title>Attach the gbde partition to the kernel</title>
+
+ <screen>
+ &prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput>
+ </screen>
+
+ <para>You will be asked to provide the passphrase that you selected during
+ initialization of the encrypted gbde partition.</para>
+ </step>
+
+ <step>
+ <title>Check the file system for errors</title>
+
+ <para>Since the encrypted file system cannot yet automatically be mounted from <filename>/etc/fstab</filename>
+ and therefore should not be listed in <filename>/etc/fstab</filename>, the file system must be
+ checked for errors by running &man.fsck.8; manually before the file system is mounted.</para>
+
+ <screen>
+ &prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput>
+ </screen>
+ </step>
+
+ <step>
+ <title>Mount the encrypted file system</title>
+
+ <screen>
+ &prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput>
+ </screen>
+
+ <para>The encrypted file system is now available for use.</para>
+ </step>
+ </procedure>
+
+ <sect3>
+ <title>Automatically mounting encrypted partitions</title>
+
+ <para>It is possible to create a script to automatically attach, check, and mount an
+ encrypted partition, but for security reasons the script should not contain the
+ &man.gbde.8; password. Instead, it is recommended that such scripts be run manually while
+ providing the password via the console or &man.ssh.1;.</para>
+ </sect3>
+
+ <sect2>
+ <title>Cryptographic protections employed by gbde</title>
+
+ <para>&man.gbde.8; encrypts the sector payload using 128-bit AES in CBC mode.
+ Each sector on the disk is encrypted with a different AES key. For more
+ information on <application>gbde's</application> cryptographic design, including how the sector keys are
+ derived from the user-supplied passphrase, see &man.gbde.4;.</para>
+ </sect2>
+
+ <sect2>
+ <title>Compatibility issues</title>
+
+ <para>&man.sysinstall.8; is incompatible with <application>gbde</application>-encrypted devices. All <devicename>*.bde</devicename> devices
+ must be detached from the kernel before starting &man.sysinstall.8; or it will
+ crash during its initial probing for devices. To detach the encrypted device used in
+ our example, use the following command:</para>
+ <screen>
+ &prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput>
+ </screen>
+ </sect2>
+
</sect1>
</chapter>
--- chapter.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list