[pkg-cryptsetup-devel] Bug#598237: document that cryptsetup key file must not have final newline

[Stephen Gildea]

Package: cryptsetup
Version: 2:1.1.3-3
Tags: patch

The only real problem I had setting up my first cryptsetup disks was
that the pass-phrase file cannot end in a newline.  I'm sure there's a
good technical reason for this bit of trickiness, but it needs to be
documented more thoroughly.  Appended are diffs to address this.

This patch also provides more complete cross-references to the other
manual pages and some English grammar fixes.

 < Stephen


--- debian/doc/cryptdisks_start.xml~	2008-06-19 04:29:25 -0700
+++ debian/doc/cryptdisks_start.xml	2010-09-25 21:19:01 -0700
@@ -17,7 +17,7 @@
 
  <refnamediv>
   <refname>cryptdisks_start</refname>
-  <refpurpose>wrapper around cryptsetup which parses /etc/crypttab.</refpurpose>
+  <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -31,16 +31,22 @@
   <title>DESCRIPTION</title>
   <simpara>
    <emphasis role="strong">cryptdisks_start</emphasis> is a wrapper around
-   <emphasis role="strong">cryptsetup</emphasis> which parses
+   <emphasis role="strong">cryptsetup</emphasis> that parses
    <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript
-   /etc/init.d/cryptdisks does, and starts the dm-crypt mapping which
+   /etc/init.d/cryptdisks does and starts the dm-crypt mapping that
    corresponds to <emphasis>&lt;name&gt;</emphasis>.
   </simpara>
+  <simpara>
+   Note that this wrapper passes <option>--key-file=-</option> to
+   <command moreinfo="refentry">cryptsetup</command>, so the passphase
+   in any referenced key file must not be followed by a newline character.
+  </simpara>
  </refsect1>
 
  <refsect1 id="cryptdisks_start.see_also">
   <title>SEE ALSO</title>
   <simpara>
+   <emphasis>cryptdisks_stop</emphasis>(8), 
    <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5)
   </simpara>
  </refsect1>
--- debian/doc/cryptdisks_stop.xml~	2008-06-19 04:29:40 -0700
+++ debian/doc/cryptdisks_stop.xml	2010-09-25 21:19:18 -0700
@@ -17,7 +17,7 @@
 
  <refnamediv>
   <refname>cryptdisks_stop</refname>
-  <refpurpose>wrapper around cryptsetup which parses /etc/crypttab.</refpurpose>
+  <refpurpose>wrapper around cryptsetup that parses /etc/crypttab.</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -31,9 +31,9 @@
   <title>DESCRIPTION</title>
   <simpara>
    <emphasis role="strong">cryptdisks_stop</emphasis> is a wrapper around
-   <emphasis role="strong">cryptsetup</emphasis> which parses
+   <emphasis role="strong">cryptsetup</emphasis> that parses
    <emphasis role="strong">/etc/crypttab</emphasis> just like the initscript
-   /etc/init.d/cryptdisks does, and stops the dm-crypt mapping which corresponds
+   /etc/init.d/cryptdisks does and stops the dm-crypt mapping that corresponds
    to <emphasis>&lt;name&gt;</emphasis>.
   </simpara>
  </refsect1>
@@ -41,6 +41,7 @@
  <refsect1 id="cryptdisks_stop.see_also">
   <title>SEE ALSO</title>
   <simpara>
+   <emphasis>cryptdisks_start</emphasis>(8), 
    <emphasis>cryptsetup</emphasis>(8), <emphasis>crypttab</emphasis>(5)
   </simpara>
  </refsect1>
--- debian/doc/crypttab.xml~	2010-07-21 01:27:48 -0700
+++ debian/doc/crypttab.xml	2010-09-25 21:00:49 -0700
@@ -25,7 +25,10 @@
   <simpara>
    The file <filename>/etc/crypttab</filename> contains descriptive
    information about encrypted filesystems. <filename>crypttab</filename>
-   is only read by programs, and not written; it is the duty of the system
+   is only read by programs (e.g.,
+   <command moreinfo="refentry">cryptdisks_start</command> and
+   <command moreinfo="refentry">cryptdisks_stop</command>),
+   and not written; it is the duty of the system
    administrator to properly create and maintain this file. Each filesystem is
    described on a separate line; fields on each line are separated by tabs or
    spaces. Lines starting with <quote>#</quote> are comments, empty lines are 
@@ -49,7 +52,12 @@
   <simpara>
    The third field, <emphasis>key file</emphasis>, describes the file to use
    as a key for decrypting the data of the <emphasis>source device</emphasis>.
-   It can also be a device name (e.g.
+   Note that the <emphasis>entire</emphasis> key file will be used as the
+   passphase; the passphase must <emphasis>not</emphasis> be
+   followed by a newline character.
+  </simpara>
+  <simpara>
+   It can also be a device name (e.g.,
    <filename class="devicefile">/dev/urandom</filename>), note however that
    LUKS requires a persistent key and therefore does <emphasis>not</emphasis>
    support random data keys.
@@ -62,7 +70,7 @@
   <simpara>
    The fourth field, <emphasis>options</emphasis>, describes the cryptsetup
    options associated with the encryption process. At minimum, the field should
-   contain the string <emphasis>luks</emphasis> or the
+   contain either the string <emphasis>luks</emphasis> or the
    <emphasis>cipher</emphasis>, <emphasis>hash</emphasis> and
    <emphasis>size</emphasis> options.
   </simpara>
@@ -451,7 +459,8 @@
   <title>SEE ALSO</title>
   <simplelist type="inline">
    <member><command moreinfo="refentry">cryptsetup</command>(8)</member>
-   <member><filename>/etc/crypttab</filename></member>
+   <member><command moreinfo="refentry">cryptdisks_start</command>(8)</member>
+   <member><command moreinfo="refentry">cryptdisks_stop</command>(8)</member>
   </simplelist>
  </refsect1>