[svnbook] r3921 committed - Finally finish issue #87 ("ch06: mention 'htdigest' tool when...

svnbook at googlecode.com svnbook at googlecode.com
Wed Jul 27 09:56:47 CDT 2011


Revision: 3921
Author:   cmpilato at gmail.com
Date:     Wed Jul 27 07:55:34 2011
Log:      Finally finish issue #87 ("ch06: mention 'htdigest' tool when
mentioning digest auth").

Patch by:  quinntaylor at mac.com
            (Tweaked by me.)

* src/en/book/ch06-server-configuration.xml
   Break coverage of the Digest authentication type out into its own
   section, and clean up / consistify other related text.
http://code.google.com/p/svnbook/source/detail?r=3921

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

=======================================
--- /trunk/src/en/book/ch06-server-configuration.xml	Fri Jul 15 10:05:32  
2011
+++ /trunk/src/en/book/ch06-server-configuration.xml	Wed Jul 27 07:55:34  
2011
@@ -86,7 +86,7 @@
          <tbody>
            <row>
              <entry>Authentication options</entry>
-            <entry>HTTP(S) basic auth, X.509 certificates, LDAP, NTLM, or
+            <entry>HTTP Basic or Digest auth, X.509 certificates, LDAP,  
NTLM, or
                any other mechanism available to Apache httpd</entry>
              <entry>CRAM-MD5 by default;  LDAP, NTLM, or any other mechanism
                available to SASL</entry>
@@ -114,7 +114,7 @@

            <row>
              <entry>Encryption</entry>
-            <entry>Available via optional SSL</entry>
+            <entry>Available via optional SSL (https)</entry>
              <entry>Available via optional SASL features</entry>
              <entry>Inherent in SSH connection</entry>
            </row>
@@ -1794,26 +1794,35 @@

        <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
-->
        <sect3 id="svn.serverconfig.httpd.authn.basic">
-        <title>Setting up HTTP authentication</title>
+        <title>Basic authentication</title>

          <para>The easiest way to authenticate a client is via the
            HTTP Basic authentication mechanism, which simply uses a
-          username and password to verify that a user is who she says
-          she is.  Apache provides an <command>htpasswd</command>
-          utility for managing the list of acceptable usernames and
-          passwords.  Let's grant commit access to
-          Sally and Harry.  First, we need to add them to the password
-          file:</para>
-
+          username and password to verify a user's identity.  Apache
+          provides the <command>htpasswd</command> utility
+          (<ulink  
url="http://httpd.apache.org/docs/current/programs/htpasswd.html"/>)
+          for managing files containing usernames and passwords.</para>
+
+        <warning>
+          <para>Basic authentication is <emphasis>extremely</emphasis>
+            insecure, because it sends passwords over the network
+            in very nearly plain text.  See
+            <xref linkend="svn.serverconfig.httpd.authn.digest"/> for
+            details on using the much safer Digest mechanism.</para>
+        </warning>
+
+        <para>First, create a password file and grant access to
+          users Harry and Sally:</para>
+
          <informalexample>
            <screen>
  $ ### First time: use -c to create the file
  $ ### Use -m to use MD5 encryption of the password, which is more secure
-$ htpasswd -cm /etc/svn-auth-file harry
+$ htpasswd -c -m /etc/svn-auth.htpasswd harry
  New password: *****
  Re-type new password: *****
  Adding password for user harry
-$ htpasswd -m /etc/svn-auth-file sally
+$ htpasswd -m /etc/svn-auth.htpasswd sally
  New password: *******
  Re-type new password: *******
  Adding password for user sally
@@ -1821,115 +1830,133 @@
  </screen>
          </informalexample>

-        <para>Next, you need to add some more
-          <filename>httpd.conf</filename> directives inside your
-          <literal>Location</literal> block to tell Apache what to do
-          with your new password file.  The
-          <literal>AuthType</literal> directive specifies the type of
-          authentication system to use.  In this case, we want to
-          specify the <literal>Basic</literal> authentication system.
-          <literal>AuthName</literal> is an arbitrary name that you
-          give for the authentication domain.  Most browsers will
-          display this name in the pop-up dialog box when the browser
-          is querying the user for her name and password.  Finally,
-          use the <literal>AuthUserFile</literal> directive to specify
-          the location of the password file you created using
-          <command>htpasswd</command>.</para>
-
-        <para>After adding these three directives, your
-          <literal><Location></literal> block should look
-          something like this:</para>
+        <para>Next, add some more directives inside the
+          <literal><Location></literal> block to tell Apache how
+          to use the password file:</para>

          <informalexample>
            <programlisting>
  <Location /svn>
    DAV svn
    SVNParentPath /var/svn
-  AuthType Basic
+
    AuthName "Subversion repository"
-  AuthUserFile /etc/svn-auth-file
+  AuthType Basic
+  AuthUserFile /etc/svn-auth.htpasswd
  </Location>
  </programlisting>
          </informalexample>

-        <para>This <literal><Location></literal> block is not
-          yet complete, and it will not do anything useful.  It's
-          merely telling Apache that whenever authorization is
-          required, Apache should harvest a username and password from
-          the Subversion client.  What's missing here, however, are
-          directives that tell Apache <emphasis>which</emphasis> sorts
-          of client requests require authorization.  Wherever
-          authorization is required, Apache will demand authentication
-          as well.  The simplest thing to do is protect all requests.
-          Adding <literal>Require valid-user</literal> tells Apache
-          that all requests require an authenticated user:</para>
+        <para>These directives work as follows:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para><literal>AuthName</literal> is an arbitrary name
+              that you choose for the authentication domain.  Most
+              browsers display this name in the dialog box when
+              prompting for username and password.</para>
+          </listitem>
+          <listitem>
+            <para><literal>AuthType</literal> specifies the type of
+              authentication to use.</para>
+          </listitem>
+          <listitem>
+            <para><literal>AuthUserFile</literal> specifies the
+              location of the password file to use.</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>However, this <literal><Location></literal> block
+          doesn't yet do anything useful.  It merely tells Apache that
+          <emphasis>if</emphasis> authorization were required, it
+          should challenge the Subversion client for a username and
+          password.  (When authorization is required, Apache requires
+          authentication as well.)  What's missing here, however, are
+          directives that tell Apache <emphasis>which sorts</emphasis>
+          of client requests require authorization; currently, none do.
+          The simplest thing is to specify that <emphasis>all</emphasis>
+          requests require authorization by adding
+          <literal>Require valid-user</literal> to the block:</para>

          <informalexample>
            <programlisting>
  <Location /svn>
    DAV svn
    SVNParentPath /var/svn
-  AuthType Basic
+
    AuthName "Subversion repository"
-  AuthUserFile /etc/svn-auth-file
+  AuthType Basic
+  AuthUserFile /etc/svn-auth.htpasswd
+
    Require valid-user
  </Location>
  </programlisting>
          </informalexample>

-        <para>Be sure to read the next section (<xref
-          linkend="svn.serverconfig.httpd.authz"/>) for more detail on the
-          <literal>Require</literal> directive and other ways to set
-          authorization policies.</para>
-
-        <para>One word of warning: HTTP Basic Auth passwords pass in
-          very nearly plain text over the network, and thus are
-          extremely insecure.</para>
-
-        <para>Another option is to not use Basic authentication, but to
-          use Digest authentication instead.  Digest authentication
-          allows the server to verify the client's
-          identity <emphasis>without</emphasis> passing the plain-text
-          password over the network.  Assuming that the client and
-          server both know the user's password, they can verify that
-          the password is the same by using it to apply a hashing
-          function to a one-time bit of information.  The server sends
-          a small random-ish string to the client; the client uses the
-          user's password to hash the string; the server then looks to
-          see whether the hashed value is what it expected.</para>
-
-        <para>Configuring Apache for Digest authentication is also
-          fairly easy, and only a small variation on our prior
-          example.  Be sure to consult Apache's documentation for full
-          details.</para>
+        <para>Refer to <xref linkend="svn.serverconfig.httpd.authz"/>
+          for more detail on the <literal>Require</literal> directive
+          and other ways to set authorization policies.</para>
+
+      </sect3>
+
+      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
-->
+      <sect3 id="svn.serverconfig.httpd.authn.digest">
+        <title>Digest authentication</title>
+
+        <para>Digest authentication is an improvement on Basic
+          authentication which allows the server to verify a client's
+          identity without sending the password over the network
+          unprotected.  Both client and server create a non-reversible
+          MD5 hash of the username, password, requested URI, and a
+          <firstterm>nonce</firstterm> (number used once) provided by
+          the server and changed each time authentication is required.
+          The client sends its hash to the server, and the server then
+          verifies that the hashes match.</para>
+
+        <para>Configuring Apache to use Digest authentication is
+          straightforward, with only small variations on our prior
+          example:</para>

          <informalexample>
            <programlisting>
  <Location /svn>
    DAV svn
    SVNParentPath /var/svn
-  AuthType Digest
+
    AuthName "Subversion repository"
-  AuthDigestDomain /svn/
-  AuthUserFile /etc/svn-auth-file
+  AuthType Digest
+  AuthUserFile /etc/svn-auth.htdigest
+
    Require valid-user
  </Location>
  </programlisting>
          </informalexample>

-        <para>If you're looking for maximum security, public key
-          cryptography is the best solution.  It may be best to use
-          some sort of SSL encryption, so that clients authenticate
-          via <literal>https://</literal> instead
-          of <literal>http://</literal>; at a bare minimum, you can
-          configure Apache to use a self-signed server
-          certificate.<footnote><para>While self-signed server
-          certificates are still vulnerable to
-          a <quote>man-in-the-middle</quote> attack, such an attack is
-          much more difficult for a casual observer to pull off,
-          compared to sniffing unprotected passwords.</para></footnote>
-          Consult Apache's documentation (and OpenSSL documentation)
-          about how to do that.</para>
+        <para>Notice that <literal>AuthType</literal> is now set to
+          <literal>Digest</literal>, and we specify a different path
+          for <literal>AuthUserFile</literal>.  Digest authentication
+          uses a different file format than Basic authentication;
+          it is created using Apache's <command>htdigest</command>
+          utility (<ulink  
url="http://httpd.apache.org/docs/current/programs/htdigest.html"/>)
+          rather than <command>htpasswd</command>.
+          Digest authentication also has the additional concept of a
+          <quote>realm</quote>, which must match the value of the
+          <literal>AuthName</literal> directive:</para>
+
+        <informalexample>
+          <screen>
+$ ### First time: use -c to create the file
+$ htdigest -c /etc/svn-auth.htdigest "Subversion repository" harry
+Adding password for harry in realm Subversion repository.
+New password: *****
+Re-type new password: *****
+$ htdigest /etc/svn-auth.htdigest "Subversion repository" sally
+Adding user sally in realm Subversion repository
+New password: *******
+Re-type new password: *******
+$
+</screen>
+        </informalexample>

        </sect3>

@@ -1955,13 +1982,11 @@
            read/write access to a repository.</para>

          <para>You can restrict access on all repository operations by
-          adding the <literal>Require valid-user</literal> directive
-          to your <literal><Location></literal> block.  Using
-          our previous example, this would mean that only clients that
-          claimed to be either <literal>harry</literal> or
-          <literal>sally</literal> and that provided the correct
-          password for their respective username would be allowed to
-          do anything with the Subversion repository:</para>
+          adding <literal>Require valid-user</literal> directly inside
+          the <literal><Location></literal> block.  The example
+          from <xref linkend="svn.serverconfig.httpd.authn.digest"/>
+          allows only clients that successfully authenticate to do
+          anything with the Subversion repository:</para>

          <informalexample>
            <programlisting>
@@ -1969,12 +1994,11 @@
    DAV svn
    SVNParentPath /var/svn

-  # how to authenticate a user
-  AuthType Basic
    AuthName "Subversion repository"
-  AuthUserFile /path/to/users/file
-
-  # only authenticated users may access the repository
+  AuthType Digest
+  AuthUserFile /etc/svn-auth.htdigest
+
+  # Only authenticated users may access the repository
    Require valid-user
  </Location>
  </programlisting>
@@ -1984,11 +2008,10 @@
            example, Subversion's own source code repository at
            <ulink url="http://svn.collab.net/repos/svn"/> allows anyone
            in the world to perform read-only repository tasks (such as
-          checking out working copies and browsing the repository with
-          a web browser), but restricts all write operations to
-          authenticated users.  To do this type of selective
-          restriction, you can use the <literal>Limit</literal> and
-          <literal>LimitExcept</literal> configuration directives.
+          checking out working copies and browsing the repository),
+          but restricts write operations to authenticated users.  The
+          <literal>Limit</literal> and <literal>LimitExcept</literal>
+          directives allow for this type of selective restriction.
            Like the <literal>Location</literal> directive, these blocks
            have starting and ending tags, and you would nest them
            inside your <literal><Location></literal>
@@ -1997,14 +2020,12 @@
          <para>The parameters present on the <literal>Limit</literal>
            and <literal>LimitExcept</literal> directives are HTTP
            request types that are affected by that block.  For example,
-          if you wanted to disallow all access to your repository
-          except the currently supported read-only operations, you
-          would use the <literal>LimitExcept</literal> directive,
-          passing the <literal>GET</literal>,
-          <literal>PROPFIND</literal>, <literal>OPTIONS</literal>, and
-          <literal>REPORT</literal> request type parameters.  Then the
-          previously mentioned <literal>Require valid-user</literal>
-          directive would be placed inside the
+          to allow anonymous read-only operations, you would use the
+          <literal>LimitExcept</literal> directive (passing the
+          <literal>GET</literal>, <literal>PROPFIND</literal>,
+          <literal>OPTIONS</literal>, and <literal>REPORT</literal>
+          request type parameters) and place the previously mentioned
+          <literal>Require valid-user</literal> directive inside the
            <literal><LimitExcept></literal> block instead of just
            inside the <literal><Location></literal> block.</para>

@@ -2014,10 +2035,9 @@
    DAV svn
    SVNParentPath /var/svn

-  # how to authenticate a user
-  AuthType Basic
    AuthName "Subversion repository"
-  AuthUserFile /path/to/users/file
+  AuthType Digest
+  AuthUserFile /etc/svn-auth.htdigest

    # For any operations other than these, require an authenticated user.
    <LimitExcept GET PROPFIND OPTIONS REPORT>
@@ -2041,9 +2061,8 @@
          <title>Per-directory access control</title>

          <para>It's possible to set up finer-grained permissions using
-          a second Apache httpd module,
-          <command>mod_authz_svn</command>.  This module grabs the
-          various opaque URLs passing from client to server, asks
+          <command>mod_authz_svn</command>.  This Apache module grabs
+          the various opaque URLs passing from client to server, asks
            <command>mod_dav_svn</command> to decode them, and then
            possibly vetoes requests based on access policies defined in
            a configuration file.</para>
@@ -2066,7 +2085,7 @@
          </informalexample>

          <para>To activate this module, you need to configure your
-          <literal>Location</literal> block to use the
+          <literal><Location></literal> block to use the
            <literal>AuthzSVNAccessFile</literal> directive, which
            specifies a file containing the permissions policy for paths
            within your repositories.  (In a moment, we'll discuss the
@@ -2079,11 +2098,11 @@
            documentation for much more detail on Apache authentication
            and authorization options.)</para>

-        <para>The simplest block is to allow open access to everyone.
-          In this scenario, Apache never sends authentication
-          challenges, so all users are treated as
-          <quote>anonymous.</quote> (See
-          <xref  
linkend="svn.serverconfig.httpd.authz.perdir.ex-1"/>.)</para>
+        <para>The most open approach is to allow access to everyone.
+          This means Apache never sends authentication challenges, and
+          all users are treated as <quote>anonymous</quote>.  (See
+          <xref linkend="svn.serverconfig.httpd.authz.perdir.ex-1"
+          />.)</para>

          <example id="svn.serverconfig.httpd.authz.perdir.ex-1">
            <title>A sample configuration for anonymous access</title>
@@ -2092,18 +2111,18 @@
    DAV svn
    SVNParentPath /var/svn

-  # our access control policy
    AuthzSVNAccessFile /path/to/access/file
+
+  # Any user may access the repository anonymously
  </Location>
  </programlisting>
          </example>

          <para>On the opposite end of the paranoia scale, you can
-          configure your block to demand authentication from everyone.
-          All clients must supply credentials to identify themselves.
-          Your block unconditionally requires authentication via the
-          <literal>Require valid-user</literal> directive, and it
-          defines a means to authenticate.  (See
+          configure Apache to authenticate all clients.
+          This block unconditionally requires authentication via the
+          <literal>Require valid-user</literal> directive, and defines
+          a means to authenticate valid users.  (See
            <xref  
linkend="svn.serverconfig.httpd.authz.perdir.ex-2"/>.)</para>

          <example id="svn.serverconfig.httpd.authz.perdir.ex-2">
@@ -2113,16 +2132,14 @@
    DAV svn
    SVNParentPath /var/svn

-  # our access control policy
    AuthzSVNAccessFile /path/to/access/file

-  # only authenticated users may access the repository
-  Require valid-user
-
-  # how to authenticate a user
-  AuthType Basic
    AuthName "Subversion repository"
-  AuthUserFile /path/to/users/file
+  AuthType Digest
+  AuthUserFile /etc/svn-auth.htdigest
+
+  # Only authenticated users may access the repository
+  Require valid-user
  </Location>
  </programlisting>
          </example>
@@ -2130,15 +2147,15 @@
          <para>A third very popular pattern is to allow a combination
            of authenticated and anonymous access.  For example, many
            administrators want to allow anonymous users to read certain
-          repository directories, but want only authenticated users to
-          read (or write) more sensitive areas.  In this setup, all
+          repository directories, but restrict access to more
+          sensitive areas to authenticated users.  In this setup, all
            users start out accessing the repository anonymously.  If
            your access control policy demands a real username at any
            point, Apache will demand authentication from the client.
            To do this, use both the <literal>Satisfy Any</literal>
-          and <literal>Require valid-user</literal> directives
-          together.  (See
-          <xref  
linkend="svn.serverconfig.httpd.authz.perdir.ex-3"/>.)</para>
+          and <literal>Require valid-user</literal> directives.  (See
+          <xref linkend="svn.serverconfig.httpd.authz.perdir.ex-3"
+          />.)</para>

          <example id="svn.serverconfig.httpd.authz.perdir.ex-3">
            <title>A sample configuration for mixed
@@ -2148,28 +2165,24 @@
    DAV svn
    SVNParentPath /var/svn

-  # our access control policy
    AuthzSVNAccessFile /path/to/access/file

-  # try anonymous access first, resort to real
-  # authentication if necessary.
+  AuthName "Subversion repository"
+  AuthType Digest
+  AuthUserFile /etc/svn-auth.htdigest
+
+  # Try anonymous access first, authenticate only if necessary
    Satisfy Any
    Require valid-user
-
-  # how to authenticate a user
-  AuthType Basic
-  AuthName "Subversion repository"
-  AuthUserFile /path/to/users/file
  </Location>
  </programlisting>
          </example>

-        <para>Once you've settled on one of these three
-          basic <filename>httpd.conf</filename> templates, you need to
-          create your file containing access rules for particular
-          paths within the repository.  We describe this later in
-          this chapter, in
-          <xref linkend="svn.serverconfig.pathbasedauthz"/>.</para>
+        <para>The next step is to create the authorization file
+          containing access rules for particular paths within the
+          repository.  We describe this later in this chapter, in this
+          chapter, in <xref linkend="svn.serverconfig.pathbasedauthz"
+          />.</para>

        </sect3>





More information about the svnbook-dev mailing list