Date: Wed, 30 Apr 2003 08:40:06 -0700 (PDT) From: "Bruce A. Mah" <bmah@freebsd.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/51598: Submission of disk encryption section the Handbook Message-ID: <200304301540.h3UFe6kv066190@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/51598; it has been noted by GNATS. From: "Bruce A. Mah" <bmah@freebsd.org> To: Lucky Green <shamrock@cypherpunks.to> Cc: FreeBSD-gnats-submit@freebsd.org, rwatson@freebsd.org, phk@freebsd.org Subject: Re: docs/51598: Submission of disk encryption section the Handbook Date: Wed, 30 Apr 2003 08:30:59 -0700 --k1lZvvs/B4yU6o8G Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable If memory serves me right, Lucky Green wrote: > >Description: > Attached is a patch to=20 > /usr/doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml [snip] Hi Lucky-- I learned a lot while reading through this. A few nitpicks on SGML markup and things inline but overall this is quite a nice job. > --- 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= >=09 > </listitem> > </itemizedlist> > </sect1> It looks like you added some whitespace at the end of this line. It'd be better not to do this. > *************** > *** 2730,2735 **** > --- 2733,3047 ---- > =20 > <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pi= d`</userinput></screen> > </sect2> > + </sect1> > + =20 > + =20 > + <sect1 id=3D"disks-encrypting"> > + <sect1info> > + <authorgroup> > + <author> > + <firstname>Lucky</firstname> > + <surname>Green</surname> > + <contrib>Contributed by </contrib> > + <affiliation> > + <address><email>shamrock@cypherpunks.to</email></address> > + </affiliation> > + </author> > + </authorgroup> > + <!-- 11 MARCH 2003 --> > + </sect1info> This element was indented kind of strangely. If you don't fix it, whomever commits the patch should be able to do this pretty easily. > +=20 > + <title>Encrypting Disk Partitions</title> > + <indexterm> > + <primary>disks</primary> > + <secondary>encrypting</secondary></indexterm> > +=20 > + <!-- I wonder if there is an SGML tag that would make Mandatory Acc= ess Control the hyperlink? -->=20 > + <para>FreeBSD offers excellent protections against users of a serve= r gaining > + unauthorized access to data. File permissions and Mandatory Acces= s Control (MAC)=20 > + (see <xref linkend=3D"mac">) prevent unauthorized=20 > + third-parties from accessing data while the operating system is active= and the=20 > + computer is powered up. However, permissions enforced by the operating= system=20 > + cannot prevent an attacker who obtained physical access to a lost, sto= len, or=20 > + seized computer from simply removing the computer's hard drive, mounti= ng=20 > + the drive on another server, and copying all of the data stored on the= drive for=20 > + further analysis.</para> A lot of your lines seem kind of long. We usually wrap around 72 characters, with the second line (and all succeeding lines) of each paragraph indented an additional two spaces. Again, if you don't fix this, whomever commits the patch should do it. > +=20 > + <para>Regardless of how an attacker may have come into possession o= f=20 > + a hard drive or powered-down computer, <application>GEOM Based Di= sk Encryption (gbde)</application> > + can protect the data on the computer's file systems against even= =20 > + highly-motivated attackers with significant resources. Unlike cum= bersome encryption methods that encrypt only individual=20 > + files, <application>gbde</application> transparently encrypts ent= ire file systems. No cleartext ever=20 > + touches the hard drive's platter.</para> > +=20 Somewhere in these first two paragraphs, mention that gdbe was first released in FreeBSD 5.0. You touch on this later on but I think it'd be better to say it sooner. > + <sect2> > + <title>Enabling gbde in the kernel</title> Capitalize initial letters in significant words of the title, except where a name is supposed to be lower-case, i.e. "Enabling gbde in the Kernel". > +=20 > + <procedure> > + <step> > + <title>Become root</title> > +=20 > + <para>Configuring <application>gbde</application> requires super-use= r privileges.</para> > +=20 > + <screen> > + &prompt.user; <userinput>su -</userinput> > + Password: > + </screen> The <screen> and </screen> tags should snuggle up to the text. All lines after the first line in a <screen></screen> element should be flush left (no leading space). It looks weird, but: <screen>&prompt.user; <userinput>su -</userinput> Password:</screen> =09 > + </step> > + =09 > + <step> > + <title>Verify the operating system version</title> > +=20 > + <para>&man.gbde.4; requires FreeBSD 5.0 or higher.</para> > +=20 > + <screen> > + &prompt.root; <userinput>uname -r</userinput> > + 5.0-RELEASE > + </screen> Ditto here. > + </step> > +=20 > + <step> > + <title>Add &man.gbde.4; support to the configuration file</title> It felt to me like either the title should include rebuilding and rebooting the kernel or you should break this step into multiple steps (i.e. you are doing more than just adding to the configuration file). > +=20 > + <para>Using your favorite text editor, add the following=20 > + line to your kernel configuration file:</para> > +=20 > + <para><filename>options GEOM_BDE</filename></para> Use <literal></literal> instead of <filename></filename>. > +=20 > + <para>Configure and recompile the FreeBSD kernel. If you=20 > + don't know how to create a custom kernel, see <xref linkend=3D"ker= nelconfig">.</para> > +=20 Between recompiling the kernel and rebooting, you need to install it. > + <para>Reboot into the new kernel.</para> > + </step> > + </procedure> > + </sect2> > +=20 > +=20 > + <sect2> > + <title>Preparing the encrypted hard drive</title> "Preparing the Encrypted Hard Drive". You get the idea. > +=20 > + <para>The following example assumes that you are adding a new har= d drive to your system that will hold a single encrypted=20 > + partition. This partition will be mounted as <filename>/private</filen= ame>. > + <application>gbde</application> can also be=20 > + used to encrypt <filename>/home</filename> and <filename>/var/mail</fi= lename>, > + but this requires more complex instructions which exceed the scope of = this introduction.</para> > +=20 > + <procedure> > + <step> > + <title>Add the new hard drive</title> > +=20 > + <para> > + Install the new drive to the system as explained in <xref linkend= =3D"disks-adding">. For the purposes of this example, the a new hard drive = partition has=20 > + been added as <filename>/dev/ad4s1c</filename>. A drive, <filena= me>/dev/ad0s1</filename>, which holds the normal FreeBSD=20 > + partitions, previously already existed on the example system.</p= ara> > +=20 > + <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> > +=20 > + <step> > + <title>Create a directory to hold GBDE lock files</title> > +=20 > + <screen> > + &prompt.root; <userinput>mkdir /etc/gbde</userinput> > + </screen> See prior comments on <screen></screen>. > +=20 > + <para>The <application>gbde</application> lock file contains informa= tion that <application>gbde</application> requires to access encrypted=20 > + partitions. Without access to the lock file, <application>gbde</ap= plication> will not be able to decrypt=20 > + the data contained in the encrypted partition without significant = manual=20 > + intervention which is not supported by the software. Each encrypte= d partition uses a separate lock file.</para> > + </step> > +=20 > + <step> > + <title>Initialize the gbde partition</title> > +=20 > + <para>A <application>gbde</application> partition must be initialize= d=20 > + before it can be used. This initialization needs to be performed o= nly once.</para> > +=20 > + <screen> > + &prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4= s1c</userinput> > + </screen> > +=20 > + <para>&man.gbde.8; will open your editor, permitting you to set vari= ous configuration options in a template. For use with UFS or UFS2, set the = sector_size to 2048.</para> Should this be "UFS1 or UFS2"? > +=20 > + <programlisting>$FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/2= 0 11:16:13 phk Exp $ > + # > + # Sector size is the smallest unit of data which can be read or wr= itten. > + # Making it too small decreases performance and decreases availabl= e space. > + # Making it too large may prevent filesystems from working. 512 i= s the > + # minimum and always safe. For UFS, use the fragment size > + # > + sector_size =3D 2048 > + [...] > + </programlisting> > +=20 > + <para>&man.gbde.8; will twice ask you to type the passphrase that sh= ould be used to secure the data. The passphrase must be=20 > + the same both times. <application>gbde's</application> ability to = protect your data depends entirely on=20 > + the quality of the passphrase that you choose.</para> > +=20 > + <para>For tips on how to select a secure passphrase that is easy to = remember, > + see the <ulink url=3D"http://world.std.com/~reinhold/diceware.html= ">Diceware Passphrase</ulink> website.</para> > +=20 > + <para>The <command>gbde init</command> command created a lock file f= or your <application>gbde</application> partition that in this example has = been=20 "creates a lock file" > + stored as <filename>/etc/gbde/ad4s1c</filename>.</para> > +=20 > + <caution> > + <para><application>gbde</application> lock files <emphasis>must</e= mphasis> be backed=20 > + up together with the contents of any encrypted partitions. While= deleting a lock=20 > + file alone cannot prevent a determined attacker from decrypting = a <application>gbde</application>=20 > + partition, without the lock file, the legitimate owner will be u= nable to=20 > + access the data on the encrypted partition without a significant= amount of work=20 > + that is totally unsupported by &man.gbde.8; and its designer.</p= ara> > + </caution> > + </step> > +=20 > + <step> > + <title>Attach the encrypted partition to the kernel</title> > +=20 > + <screen> > + &prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s= 1c</userinput> > + </screen> > +=20 > + <para> You will be asked to provide the passphrase that you selected= during the=20 > + initialization of the encrypted partition. The new encrypted devic= e will show up in=20 > + <filename>/dev</filename> as <filename>/dev/device_name.bde</filen= ame>:</para> =20 <filename>/dev/<replaceable>device_name</replaceable>.bde</filename> > +=20 > + <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> > +=20 > + <step> > + <title>Create a file system on the encrypted device</title> > +=20 > + <para>Once the encrypted device has been attached to the kernel, you= can create a file system on the device. To=20 > + create a file system on the encrypted device, use &man.newfs.8;. S= ince it is much=20 > + faster to initialize a new UFS2 file system than it is to initiali= ze=20 > + the old UFS file system, using &man.newfs.8; with the <command>-O2= </command> option is recommended.</para> <option>-O2</option> Maybe add somewhere a note to the effect that -O2 is the default on 5.1-RELEASE and later? > +=20 > + <screen> > + &prompt.root; <userinput>newfs -U -O2 /dev/ad4s1c.bde</userinput> > + </screen> > +=20 > + <note> > + <para>The newfs must be performed on an attached <application>gbde= </application> partition which is identified by a *.bde extension to the de= vice name.</para> &man.newfs.8; command <filename><replaceable>*</replaceable>.bde</filename> > + </note> > + </step> > +=20 > + <step> > + <title>Mount the encrypted partition</title> > +=20 > + <para>Create a mount point for the encrypted file system.</para> > +=20 > + <screen> > + &prompt.root; <userinput>mkdir /private</userinput> > + </screen> > +=20 > + <para>Mount the encrypted file system.</para> > +=20 > + <screen> > + &prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput> > + </screen> > + </step> > +=20 > + <step> > + <title>Verify that the encrypted file system is available</title> > +=20 > + <para>The encrypted file system should now be visible to &man.df.1; = and be available for use.</para> > +=20 > + <screen> > + &prompt.user; <userinput>df -H</userinput> > + Filesystem Size Used Avail Capacity Mounted on > + /dev/ad0s1a 1037M 72M 883M 8% =20 > + /devfs 1.0K 1.0K 0B 100% /dev=20 > + /dev/ad0s1f 8.1G 55K 7.5G 0% /home=20 > + /dev/ad0s1e 1037M 1.1M 953M 0% /tmp=20 > + /dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr=20 > + /dev/ad4s1c.bde 150G 4.1K 138G 0% /private > + </screen> > + </step> > + </procedure> > + </sect2> > +=20 > + <sect2> > + <title>Mounting existing encrypted file systems</title> > +=20 > + <para>After each boot, any encrypted file systems must be re-atta= ched to the kernel,=20 > + checked for errors, and mounted, before the file systems can be used. = The=20 > + required commands must be executed as user root.</para> > +=20 > + <procedure> > + <step> > + <title>Attach the gbde partition to the kernel</title> > +=20 > + <screen> > + &prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s= 1c</userinput> > + </screen> > + =20 > + <para>You will be asked to provide the passphrase that you selected = during=20 > + initialization of the encrypted gbde partition.</para> > + </step> > +=20 > + <step> > + <title>Check the file system for errors</title> > +=20 > + <para>Since the encrypted file system cannot yet automatically be mo= unted from <filename>/etc/fstab</filename>=20 "cannot yet automatically" sounds a little awkward. > + and therefore should not be listed in <filename>/etc/fstab</filena= me>, the file system must be=20 > + checked for errors by running &man.fsck.8; manually before the fil= e system is mounted.</para> > +=20 > + <screen> > + &prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput> > + </screen> > + </step> > +=20 > + <step> > + <title>Mount the encrypted file system</title> > +=20 > + <screen> > + &prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput> > + </screen> > + =20 > + <para>The encrypted file system is now available for use.</para> > + </step> > + </procedure> > +=20 > + <sect3> > + <title>Automatically mounting encrypted partitions</title> > +=20 > + <para>It is possible to create a script to automatically attach, check= , and mount an=20 > + encrypted partition, but for security reasons the script should not = contain the=20 > + &man.gbde.8; password. Instead, it is recommended that such scripts = be run manually while=20 > + providing the password via the console or &man.ssh.1;.</para> > + </sect3> > +=20 > + <sect2> > + <title>Cryptographic protections employed by gbde</title> > +=20 > + <para>&man.gbde.8; encrypts the sector payload using 128-bit AES in CB= C mode.=20 > + Each sector on the disk is encrypted with a different AES key. For m= ore=20 > + information on <application>gbde's</application> cryptographic desig= n, including how the sector keys are=20 > + derived from the user-supplied passphrase, see &man.gbde.4;.</para> > + </sect2> > +=20 > + <sect2> > + <title>Compatibility issues</title> > +=20 > + <para>&man.sysinstall.8; is incompatible with <application>gbde</appli= cation>-encrypted devices. All <devicename>*.bde</devicename> devices=20 <filename><replaceable>*</replaceable>.bde</filename> > + must be detached from the kernel before starting &man.sysinstall.8; = or it will=20 > + crash during its initial probing for devices. To detach the encrypte= d device used in=20 > + our example, use the following command:</para> > + <screen> > + &prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput> > + </screen> > + </sect2> If this is a bug that is expected to be fixed at some point, perhaps noting that might be helpful (as well as saying something like "As of FreeBSD 5.1-RELEASE..."). > +=20 > </sect1> > </chapter> > =20 I'm not trying to pick on your markup BTW...this was actually pretty complex. IMHO, it'd be great if you could make the changes I suggested (or whichever ones you agree with) and submit a new patch (or a URL to it?) as a follow-up to this PR. If nobody gets to committing this within a few days, prod me and I'll do it. Once again, nice job with this! Bruce. --k1lZvvs/B4yU6o8G Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+r+wy2MoxcVugUsMRAvvuAKC5IjXgiImNWQ5DOEgzL3hLV1G07QCg6jCn 1M7yrxB43wxLf517A8s57WM= =ttMc -----END PGP SIGNATURE----- --k1lZvvs/B4yU6o8G--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200304301540.h3UFe6kv066190>