[svnbook commit] r2888 - trunk/src/en/book

sussman noreply at red-bean.com
Sun Nov 25 10:39:42 CST 2007


Author: sussman
Date: Sun Nov 25 10:39:41 2007
New Revision: 2888

Log:
Finish documenting SASL.  Trac issue 79.

Thanks to Vlad Georgescu <vgeorgescu at gmail.com> for his excellent
notes in notes/sasl.txt.  This is essentially a rewrite of the same
content.

* src/en/book/ch06-server-configuration.xml
  (Using <command>svnserve</command> with SASL):  fill out section.

* src/en/book/ch00-preface.xml:  add Vlad to acknowledgements.



Modified:
   trunk/src/en/book/ch00-preface.xml
   trunk/src/en/book/ch06-server-configuration.xml

Modified: trunk/src/en/book/ch00-preface.xml
==============================================================================
--- trunk/src/en/book/ch00-preface.xml	(original)
+++ trunk/src/en/book/ch00-preface.xml	Sun Nov 25 10:39:41 2007
@@ -478,21 +478,21 @@
       John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo
       DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben Elliston, Justin
       Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin
-      Furter, Dave Gilbert, Eric Gillespie, David Glasser, Matthew
-      Gregan, Art Haas, Eric Hanchrow, Greg Hudson, Alexis Huxley,
-      Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto
-      King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai, Scott
-      Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce
-      A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth
-      McCaughan, Jon Middleton, Tim Moloney, Christopher Ness, Mats
-      Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy
-      Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel
-      Rall, Jack Repenning, Tobias Ringstrom, Garrett Rooney, Joel
-      Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander
-      Striker, Erik Sjoelund, Johan Sundstroem, John Szakmeister,
-      Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad
-      Whitacre, Josef Wolf, Blair Zajac, and the entire Subversion
-      community.</para>
+      Furter, Vlad Georgescu, Dave Gilbert, Eric Gillespie, David
+      Glasser, Matthew Gregan, Art Haas, Eric Hanchrow, Greg Hudson,
+      Alexis Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon,
+      Mark Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt
+      Kraai, Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul
+      Lussier, Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick
+      Mayweg, Gareth McCaughan, Jon Middleton, Tim Moloney,
+      Christopher Ness, Mats Nilsson, Joe Orton, Amy Lyn Pilato, Kevin
+      Pilch-Bisson, Dmitriy Popkov, Michael Price, Mark Proctor,
+      Steffen Prohaska, Daniel Rall, Jack Repenning, Tobias Ringstrom,
+      Garrett Rooney, Joel Rosdahl, Christian Sauer, Larry Shatzer,
+      Russell Steicke, Sander Striker, Erik Sjoelund, Johan
+      Sundstroem, John Szakmeister, Mason Thomas, Eric Wadsworth,
+      Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf, Blair
+      Zajac, and the entire Subversion community.</para>
 
     <!-- =============================================================== -->
     <sect2 id="svn.preface.acks.sussman">

Modified: trunk/src/en/book/ch06-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch06-server-configuration.xml	(original)
+++ trunk/src/en/book/ch06-server-configuration.xml	Sun Nov 25 10:39:41 2007
@@ -888,7 +888,7 @@
 
     <!-- =============================================================== -->
     <sect2 id="svn.serverconfig.svnserve.sasl">
-      <title>Authenticating with SASL</title>
+      <title>Using <command>svnserve</command> with SASL</title>
 
       <para>For many teams, the built-in CRAM-MD5 authentication is
         all they need from <command>svnserve</command>.  However, if
@@ -900,39 +900,192 @@
       <sidebar>
         <title>What is SASL?</title>
         <para>The Cyrus Simple Authentication and Security Layer is
-              open-source software written by Carnegie Mellon
-              University.  It adds generic authentication and
-              encryption capabilities to any network protocol, and as
-              of Subversion 1.5 and later, <command>svnserve</command>
-              knows how to make use of this library.  It may or may
-              not be available to you: if you're building Subversion
-              yourself, you'll need to have at least version 2.1 of
-              SASL installed on your system and you'll need to make
-              sure that it's detected during Subversion's build
-              process.  If you're using a pre-built Subversion binary
-              package, you'll have to check with the package
-              maintainer as to whether SASL support was compiled in.
-              SASL also comes with a number of pluggable modules that
-              represent different authentication systems: Kerberos
-              (GSSAPI), NTLM, PAM, One-Time-Passwords, DIGEST-MD5,
-              LDAP, Secure-Remote-Password, and others.  Certain
-              mechanisms may or may not be available to you; be sure
-              to check which modules are provided.</para>
+          open-source software written by Carnegie Mellon University.
+          It adds generic authentication and encryption capabilities
+          to any network protocol, and as of Subversion 1.5 and later,
+          both the <command>svnserve</command> server
+          and <command>svn</command> client know how to make use of
+          this library.  It may or may not be available to you: if
+          you're building Subversion yourself, you'll need to have at
+          least version 2.1 of SASL installed on your system and
+          you'll need to make sure that it's detected during
+          Subversion's build process.  If you're using a pre-built
+          Subversion binary package, you'll have to check with the
+          package maintainer as to whether SASL support was compiled
+          in.  SASL comes with a number of pluggable modules that
+          represent different authentication systems: Kerberos
+          (GSSAPI), NTLM, One-Time-Passwords (OTP), DIGEST-MD5, LDAP,
+          Secure-Remote-Password (SRP), and others.  Certain
+          mechanisms may or may not be available to you; be sure to
+          check which modules are provided.</para>
+
+        <para>You can download Cyrus SASL (both code and
+          documentation) from
+          <ulink url="http://asg.web.cmu.edu/sasl/sasl-library.html"/>.</para>
       </sidebar>
 
+      <para>Normally, when a subversion client connects
+        to <command>svnserve</command>, the server sends a greeting
+        which advertises a list of capabilities it supports, and the
+        client responds with a similar list of capabilities.  If the
+        server is configured to require authentication, it then sends
+        a challenge which lists the authentication mechanisms
+        available; the client responds by choosing one of the
+        mechanisms, and then authentication is carried out in some
+        number of roundtrip messages.  Even when SASL capabilities
+        aren't present, the client and server inherently know how to
+        use the CRAM-MD5 and ANONYMOUS mechanisms (see
+        <xref linkend="svn.serverconfig.svnserve.auth"/>).  If server
+        and client were linked against SASL, then a number of other
+        authentication mechanisms may also be available.  However,
+        you'll need to explicitly configure SASL on the server-side to
+        advertise them.</para>
+
+      <sect3 id="svn.serverconfig.svnserve.sasl.authn">
+        <title>Authenticating with SASL</title>
+
+        <para>To activate specific SASL mechanisms on the server, you'll
+          need to do two things.  First, create
+          a <literal>[sasl]</literal> section in your
+          repository's <filename>svnserve.conf</filename> file, with
+          this key-value pair:</para>
+
+        <screen>
+          use-sasl = true
+</screen>
+
+        <para>Second, create a file
+          called <filename>subversion.conf</filename> in a place where
+          the SASL library can find it—typically in the
+          directory where SASL plugins are located.  You'll have to
+          locate the plugin directory on your particular system, such
+          as <filename>/usr/lib/sasl2/</filename>
+          or <filename>/etc/sasl2/</filename>.  (Note that this
+          is <emphasis>not</emphasis>
+          the <filename>svnserve.conf</filename> file that lives
+          within a repository!)</para>
+
+        <para>On a Windows server, you'll have to also edit the
+          registry (using a tool like <command>regedit</command>) to
+          tell SASL where to find things.  Create a registry key
+          named <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie
+          Mellon\Project Cyrus\SASL Library]</literal>, and place two
+          keys inside it: a key called <literal>SearchPath</literal>
+          (whose value is a path containing the
+          SASL <filename>.dll</filename> plugins), and a key
+          called <literal>ConfFile</literal> (whose value is a path
+          containing the <filename>subversion.conf</filename>
+          file.)</para>
+
+        <para>Because SASL provides so many different kinds of
+          authentication mechanisms, it would be foolish (and far
+          beyond the scope of this book) to try and describe every
+          possible server-side configuration.  Instead, we recommend
+          that you read the documentation supplied in
+          the <filename>doc/</filename> subdirectory of the SASL
+          source code.  It goes into great detail about each mechanism
+          and how to configure the server appropriately for each.  For
+          the purposes of this discussion, we'll just demonstrate a
+          simple example of configuring the DIGEST-MD5 mechanism.  For
+          example, if your <filename>subversion.conf</filename>
+          contains:</para>
+
+        <screen>
+pwcheck_method: auxprop
+auxprop_plugin: sasldb
+mech_list: DIGEST-MD5
+</screen>
+
+        <para>...then you've told SASL to advertise the DIGEST-MD5
+          mechanism to clients, and to check user passwords against a
+          private password database (typically stored
+          in <filename>/etc/sasldb2</filename>).  A system
+          administrator can then use
+          the <command>saslpasswd2</command> program to add or modify
+          usernames and passwords in the database:</para>
+
+        <screen>
+$ saslpasswd2 -c -u realm username
+</screen>
+
+        <para>A few words of warning: first, make sure that the
+          "realm" argument to <command>saslpasswd2</command> matches
+          the same "realm" you've defined in your
+          repository's <filename>svnserve.conf</filename> file; if
+          they don't match, authentication will fail.  Also, due to a
+          shortcoming in SASL, the common realm must be a string with
+          no space characters.  Finally, if you decide to go with the
+          standard SASL password database, make sure that
+          the <command>svnserve</command> program has read access to
+          the file (and possibly write access as well, if you're using
+          a mechanism such as OTP.)</para>
+
+        <para>This is just one simple way of configuring SASL.  Many
+          other authentication mechanisms available, and passwords can
+          be stored in other places such as in LDAP or a SQL database.
+          Consult the full SASL documentation for details.</para>
+
+        <para>Remember that if you configure your server to only allow
+          certain SASL authentication mechanisms, this can also have
+          the effect of forcing all of connecting clients to have SASL
+          support as well.  Any Subversion client built without SASL
+          support (which includes all pre-1.5 clients) will be unable
+          to authenticate.  On the one hand, this sort of restriction
+          may be exactly what you want (<quote>my clients must all use
+          Kerberos!</quote>).  However, if you still want non-SASL
+          clients to be able to authenticate, be sure to advertise the
+          CRAM-MD5 mechanism as an option.  All clients are able to
+          use CRAM-MD5, whether they have SASL support or not.</para>
+
+        </sect3>
+
+      <sect3 id="svn.serverconfig.svnserve.sasl.encryption">
+        <title>SASL Encryption</title>
+
+        <para>SASL is also able to perform data-encryption if a
+          particular mechanism supports it.  The built-in CRAM-MD5
+          mechanism doesn't support encryption, but DIGEST-MD5 does,
+          and mechanisms like SRP actually require use of the OpenSSL
+          library .  To enable or disable different levels of
+          encryption, you can set two values in your
+          repository's <filename>svnserve.conf</filename> file:</para>
+
+        <screen>
+[sasl]
+use-sasl = true
+min-encryption = 128
+max-encryption = 256
+</screen>
+
+        <para>The <literal>min-encryption</literal>
+          and <literal>max-encryption</literal> variables control the
+          level of encryption demanded by the server.  To disable
+          encryption completely, set both values to 0.  To enable
+          simple checksumming of data (i.e. prevent tampering and
+          guarantee data integrity without encryption), set both
+          values to 1.  If you wish to allow—but not
+          require—encryption, set the minimum value to 0, and
+          the maximum value to some bit-length.  To require encryption
+          unconditionally, set both values to numbers greater than 1.
+          In our example above, we require clients to do at least
+          128-bit encryption, but no more than 256-bit
+          encryption.</para>
+
+        </sect3>
+
       </sect2>
 
     <!-- =============================================================== -->
     <sect2 id="svn.serverconfig.svnserve.sshauth">
       <title>Tunneling over SSH</title>
 
-      <para><command>svnserve</command>'s built-in authentication can
-        be very handy, because it avoids the need to create real
-        system accounts.  On the other hand, some administrators
-        already have well-established SSH authentication frameworks in
-        place.  In these situations, all of the project's users
-        already have system accounts and the ability to <quote>SSH
-        into</quote> the server machine.</para>
+      <para><command>svnserve</command>'s built-in authentication (and
+        SASL support) can be very handy, because it avoids the need to
+        create real system accounts.  On the other hand, some
+        administrators already have well-established SSH
+        authentication frameworks in place.  In these situations, all
+        of the project's users already have system accounts and the
+        ability to <quote>SSH into</quote> the server machine.</para>
 
       <para>It's easy to use SSH in conjunction with
         <command>svnserve</command>.  The client simply uses the




More information about the svnbook-dev mailing list