[PATCH] update for current password caching behaviour

Stefan Sperling stsp at elego.de
Sun Dec 7 10:29:52 CST 2008


On Sun, Dec 07, 2008 at 03:12:21PM +0000, Stefan Sperling wrote:
> Hi there,
> 
> in preparation for documenting the tree conflicts feature,
> I started reading the book sources thoroughly to get a feel for
> the style used in the book etc. (and DocBook!), and more or less
> immediately found outdated stuff that needed updating (and I could
> not stop myself from updating it, gah, so much for my Sunday
> afternoon...).
> 
> So here's a patch, comments welcome.

Updated patch, 2 changes:

* Do not lose the path of the auth cache on Windows,
  I ended up removing this in the first version of the patch.

* Fix an xref that pointed to "svn.serverconfig.netmodel.credcache"
  but should have pointed to "svn.advanced.confarea.opts".

Log message unchanged.

Stefan


[[[
* ch03-advanced-topics.xml
  (svn.serverconfig.netmodel.credcache): Remove references to
   implementation details of the auth cache which are repeated
   further down below anyway (and they didn't hold for all
   systems either, e.g. Mac OS X).
   Expand notes on UNIX-like systems about new support for
   GNOME Keyring and KDE Wallet, and explain the new default
   behaviour of prompting the user before caching passwords
   unencrypted.  Expand a bit on the assumptions behind
   security of file system permissions.

* ch02-basic-usage.xml
  (svn.tour.initial.disabling-password-caching): Document
   the new default behaviour of prompting the user before
   caching passwords unencrypted, and explain how to
   enable and disable plaintext caching by default.

   Remove a footnote arguing that plaintext caching was
   OK because "you can't really delete anything from
   Subversion". This argument is misleading because it does
   not cover the entire problem space. E.g. adding something
   can also cause trouble -- see the obliterate discussion.  
   And I don't think having the book argue in favour of either
   way is a good idea in the first place. Let's let our users
   make up their own minds. Now that we're truly giving them the
   necessary knobs to tweak, we can stay out of this discussion.

* ch07-customizing-svn.xml
  (svn.advanced.confarea.opts.servers): Document the new
   "store-plaintext-passwords" option. Also, add a TODO
   note regarding GNOME Keyring and KDE Wallet.
]]]


Index: ch03-advanced-topics.xml
===================================================================
--- ch03-advanced-topics.xml	(revision 3365)
+++ ch03-advanced-topics.xml	(working copy)
@@ -3851,14 +3851,9 @@
         this—a built-in system for caching authentication
         credentials on disk.  By default, whenever the command-line
         client successfully responds to a server's authentication
-        challenge, it saves the credentials in the user's private
-        runtime configuration area
-        (<filename>~/.subversion/auth/</filename> on Unix-like systems
-        or <filename>%APPDATA%/Subversion/auth/</filename> on Windows;
-        see <xref linkend="svn.advanced.confarea" /> for more details
-        about the runtime configuration system).  Successful
-        credentials are cached on disk and keyed on a combination of the
-        server's hostname, port, and authentication realm.</para>
+        challenge, credentials are cached on disk and keyed on a
+        combination of the server's hostname, port, and authentication
+        realm.</para>
 
       <para>When the client receives an authentication challenge, it
         first looks for the appropriate credentials in the user's disk
@@ -3882,9 +3877,11 @@
       <itemizedlist>
 
         <listitem>
-          <para>On Windows 2000 and later, the Subversion client uses
-            standard Windows cryptography services to encrypt the
-            password on disk.  Because the encryption key is managed
+          <para>On Windows, the Subversion client stores passwords
+            in the <filename>%APPDATA%/Subversion/auth/</filename>
+            directory. On Windows 2000 and later, the standard Windows
+            cryptography services are used to encrypt the password
+            on disk.  Because the encryption key is managed
             by Windows and is tied to the user's own login
             credentials, only the user can decrypt the cached
             password.  (Note that if the user's Windows account password
@@ -3906,11 +3903,21 @@
 
         <listitem>
           <para>For other Unix-like operating systems, no standard
-            <quote>keychain</quote> services exist.  However,
-            the <filename>auth/</filename> caching area is still
-            permission-protected so that only the user (owner) can
-            read data from it, not the world at large.  The operating
-            system's own file permissions protect the passwords.</para>
+            <quote>keychain</quote> services exist.  However, the
+            Subversion client knows how to store password securely
+            using the <quote>GNOME Keyring</quote> and
+            <quote>KDE Wallet</quote> services.
+            Also, before storing unencrypted passwords in the
+            <filename>~/.subversion/auth/</filename> caching area,
+            the Subversion client will ask the user for permission
+            to do so.  Note that the <filename>auth/</filename>
+            caching area is still permission-protected so that only
+            the user (owner) can read data from it, not the world at
+            large.  The operating system's own file permissions protect
+            the passwords from other non-administrative users on the
+            same system, provided they have no direct physical access
+            to the storage media of the home directory, or backups
+            thereof.</para>
         </listitem>
 
       </itemizedlist>
Index: ch02-basic-usage.xml
===================================================================
--- ch02-basic-usage.xml	(revision 3365)
+++ ch02-basic-usage.xml	(working copy)
@@ -323,27 +323,38 @@
       <title>Disabling Password Caching</title>
 
       <para>When you perform a Subversion operation that requires you
-        to authenticate, by default Subversion caches your
-        authentication credentials on disk.  This is done for
-        convenience so that you don't have to continually reenter
-        your password for future operations.  If you're concerned
-        about caching your Subversion passwords,
-        <footnote>
-          <para>Of course, you're not terribly worried—first
-            because you know that you can't
-            <emphasis>really</emphasis> delete anything from
-            Subversion, and second because your Subversion password
-            isn't the same as any of the other 3 million passwords
-            you have, right?  Right?</para>
-        </footnote>
-        you can disable caching either permanently or on a
-        case-by-case basis.</para>
+        to authenticate, by default Subversion tries to cache your
+        authentication credentials on disk in encrypted form.
+        On some systems, Subversion may be unable to encrypt your
+        authentication data. You will then be asked whether you
+        want to cache your credentials to disk in plaintext.
+        You can choose to do so for convenience so that you don't have
+        to continually reenter your password for future operations.
+        If you're concerned about caching your Subversion passwords
+        in plaintext and do not want to be asked about it again and
+        again, you can disable caching of plaintext passwords either
+        permanently, or on a server-per-server basis.</para>
 
-      <para>To disable password caching for a particular one-time
+      <para>To permanently disable caching of passwords in plaintext,
+        you can add the line
+        <literal>store-plaintext-passwords = no</literal>
+        to the global section in the <filename>servers</filename>
+        configuration file on the local machine.  To disable caching
+        of plaintext passwords for a particular server, use the same
+        setting in the appropriate group section in the
+        <filename>servers</filename> configuration file.
+        See <xref linkend="svn.advanced.confarea.opts"/>
+        in <xref linkend="svn.customization"/> for details.</para>
+
+      <para>You can also disable caching of authentication credentials
+        entirely, regardless of whether the credentials are stored
+        in encrypted form or not.</para>
+
+      <para>To disable password caching entirely for a particular one-time
         command, pass the <option >--no-auth-cache</option > option on
-        the command line.  To permanently disable caching, you can add
-        the line <literal>store-passwords = no</literal> to your local
-        machine's Subversion configuration file.  See <xref
+        the command line.  To permanently disable caching entirely,
+        you can add the line <literal>store-passwords = no</literal>
+        to your local machine's Subversion configuration file.  See <xref
         linkend="svn.serverconfig.netmodel.credcache"/> for
         details.</para>
 
Index: ch07-customizing-svn.xml
===================================================================
--- ch07-customizing-svn.xml	(revision 3365)
+++ ch07-customizing-svn.xml	(working copy)
@@ -450,6 +450,28 @@
                 passphrase.  You won't be prompted anymore.</para>
             </listitem>
           </varlistentry>
+          <varlistentry>
+            <term><literal>store-plaintext-passwords</literal></term>
+            <listitem>
+              <para>This variable is only important on UNIX-like systems.
+              It controls what the Subversion client does in case
+              the password for the current authentication realm can
+              only be cached on disk in unencrypted form, in the
+              <filename>~/.subversion/auth/</filename> caching area.
+            <!-- TODO: Using GNOME Keyring and KDE Wallet needs to
+                 be documented. Then:
+                 "See section xyz for information on how to configure
+                 an encrypted password cache on your system." -->
+              You can set it to <literal>yes</literal> or
+              <literal>no</literal> to enable or disable caching of
+              passwords in unencrypted form, respectively.
+              The default setting is <literal>ask</literal>, which causes
+              the Subversion client to ask you each time a
+              <emphasis>new</emphasis> password is about to be added to
+              the <filename>~/.subversion/auth/</filename> caching area.
+              </para>
+            </listitem>
+          </varlistentry>
         </variablelist>
 
       </sect3>




More information about the svnbook-dev mailing list