svn commit: r54328 - head/en_US.ISO8859-1/books/handbook/disks

[Allan Jude]

Author: allanjude
Date: Sat Jul 11 16:18:22 2020
New Revision: 54328
URL: https://svnweb.freebsd.org/changeset/doc/54328

Log:
  Update the GELI handbook to be more accurate
  
  The description of the key file incorrectly identified it as the master key
  
  PR:		208578
  Submitted by:	Wout Decre <wout at canodus.be> (original version)
  Reviewed by:	bcr, oshogbo
  Sponsored by:	Klara Inc.
  Event:		July 2020 Bugathon
  Differential Revision:	https://reviews.freebsd.org/D15866

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	Sat Jul 11 15:48:48 2020	(r54327)
+++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml	Sat Jul 11 16:18:22 2020	(r54328)
@@ -2823,15 +2823,20 @@ device crypto</programlisting>
 	<step>
 	  <title>Generate the Master Key</title>
 
-	  <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>
+	  <para>The following commands generate a master key that all
+	    data will be encrypted with.  This key can never be changed.
+	    Rather than using it directly, it is encrypted with one
+	    or more user keys.  The user keys are made up of an
+	    optional combination of random bytes from a file,
+	    <filename>/root/da2.key</filename>, and/or a passphrase.
+	    In this case, the data source for the key file is
+	    <filename>/dev/random</filename>. This command also
+	    configures the sector size of the provider
+	    (<filename>/dev/da2.eli</filename>) as 4kB, for 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>
+&prompt.root; <userinput>geli init -K /root/da2.key -s 4096 /dev/da2</userinput>
 Enter new passphrase:
 Reenter new passphrase:</screen>