Minor consistency changes.

doc/docbook/acegi.xml

@@ -26,7 +26,7 @@
 
     <subtitle>Reference Documentation</subtitle>
 
-    <releaseinfo>0.8.0</releaseinfo>
+    <releaseinfo>0.8.1</releaseinfo>
 
     <authorgroup>
       <author>
@@ -2679,7 +2679,7 @@ key:              A private key to prevent modification of the nonce token
         login to take place. Acegi Security provides the necessary hooks so
         that such operations can take place, along with providing a concrete
         implementation that uses hashing to preserve the security of
-        cookie-based tokens. </para>
+        cookie-based tokens.</para>
 
         <para>Remember-me authentication is not used with digest or basic
         authentication, given they are often not used with
@@ -3812,106 +3812,158 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
     </sect1>
 
     <sect1 id="security-x509">
-        <title>X.509 Authentication</title>
-        <sect2 id="security-x509-overview">
-            <title>Overview</title>
-            <para>The most common use of X.509 certificate authentication is 
-                in verifying the identity of a server when using SSL, most commonly when using 
-                HTTPS from a browser. The browser will automatically check that the
-                certificate presented by a server has been issued (i.e. digitally 
-                signed) by one of a list of trusted certificate authorities which 
-                it maintains.                
-            </para>
-            <para>You can also use SSL with <quote>mutual authentication</quote>; 
-                the server will then request a valid certificate from the client
-                as part of the SSL handshake. The server will authenticate the client by checking
-                that it's certificate is signed by an acceptable authority. If a valid certificate
-                has been provided, it can be obtained through the servlet API in an application.
-                The Acegi X.509 module extracts the certificate using a filter and passes it to the
-                configured X.509 authentication provider to allow any additional application-specific
-                checks to be applied. It also maps the certificate to an application user and loads that
-                user's set of granted authorities for use with the standard Acegi infrastructure.
-            </para>
-            <para>You should be familiar with using certificates and setting up client authentication for your
-                servlet container before attempting to use it with Acegi. Most of the work is in
-                creating and installing suitable certificates and keys. For example, if you're using Tomcat then
-                read the instructions here <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"/>.
-                It's important that you get this working before trying it out with Acegi.
-            </para>            
-        </sect2>
-        <sect2 id="security-x509-details">
-            <title>X.509 with Acegi Security</title>
-            <para>With X.509 authentication, there is no explicit login procedure so the implementation 
-            is relatively simple; there is no need to redirect requests in order to interact with the
-            user. As a result, some of the classes behave slightly differently from their equivalents in other packages. 
-            For example, the default <quote>entry point</quote> class, which is normally responsible for starting the authentication 
-            process, is only invoked if the certificate is rejected and it always returns an error to the user.
-            With a suitable bean configuration, the normal sequence of events is as follows
-                <orderedlist>
-                    <listitem><para>The <classname>X509ProcessingFilter</classname> extracts the certificate
-                    from the request and uses it as the credentials for an authentication request. The
-                    request is an <classname>X509AuthenticationToken</classname>. The request is passed to
-                    the authentication manager.</para></listitem>
-                    <listitem><para>The <classname>X509AuthenticationProvider</classname> receives
-                    the token. It's main concern is to obtain the user information (in particular the user's
-                    granted authorities) which match the certificate. It delegates this responsibility
-                    to an <interfacename>X509AuthoritiesPopulator</interfacename>.</para></listitem>.                    
-                    <listitem><para>The populator's single method, 
-                    <methodname>getUserDetails(X509Certificate userCertificate)</methodname> is invoked.
-                    Implementations should return a <classname>UserDetails</classname> instance containing
-                    the set of <classname>GrantedAuthority</classname> objects for the user. This method can
-                    also choose to reject the certificate (for example if it doesn't contain a matching user name).
-                    It should then throw a <exceptionname>BadCredentialsException</exceptionname>. A dao-based
-                    implementation <classname>DaoX509AuthoritiesPopulator</classname> is provided which extracts 
-                    the user's name from the subject <quote>common name</quote> in the certificate. It also allows
-                    you to set your own regular expression to match a different part of the subject distinguished
-                    name. It uses an <classname>AuthenticationDao</classname> to load the user information.
-                        <!-- TODO: Give email matching as an example -->
-                    </para></listitem>
-                    <listitem><para>If everything has gone smoothly then there should be a valid 
-                    <classname>Authentication</classname> object in the secure context and the invocation will procede
-                    as normal. If no certificate was found, or the certificate was rejected, then the 
-                    <classname>SecurityEnforcementFilter</classname> will invoke the 
-                    <classname>X509ProcessingFilterEntryPoint</classname> which returns a 403 error to the
-                    user.</para></listitem>
-                </orderedlist>                
-            </para>
-        </sect2>
-        <sect2 id="security-x509-config">
-            <title>Configuring the X.509 Provider</title>
-            <para>There is a version of the <link linkend="security-sample">contacts sample application</link> which uses X.509.
-            Copy the beans and filter setup from this as a starting point for configuring your own application. 
-            A set of example certificates is also included which you can use to configure your server. These are
-
-            <itemizedlist>
-                <listitem><para><filename>marissa.p12</filename> A PKCS12 format file containing the client key and certificate. These should
-                be installed in your browser. It maps to the user <quote>marissa</quote> in the application.</para></listitem>
-                <listitem><para><filename>server.p12</filename> The server certificate and key for HTTPS connections.</para></listitem>
-                <listitem><para><filename>ca.jks</filename> A Java keystore containing the certificate for the authority which issued marissa's
-                certificate. This will be used by the container to validate client certificates.</para></listitem>
-            </itemizedlist>
-            
-            For JBoss 3.2.7 (with Tomcat 5.0), the SSL configuration in the <filename>server.xml</filename> file looks like this
-            <programlisting>
-       &lt;!-- SSL/TLS Connector configuration --&gt;
-      &lt;Connector port=&quot;8443&quot; address=&quot;${jboss.bind.address}&quot;
-           maxThreads=&quot;100&quot; minSpareThreads=&quot;5&quot; maxSpareThreads=&quot;15&quot;
-           scheme=&quot;https&quot; secure=&quot;true&quot;
-           sslProtocol = &quot;TLS&quot;
-           clientAuth=&quot;true&quot; keystoreFile=&quot;${jboss.server.home.dir}/conf/server.p12&quot;
-           keystoreType=&quot;PKCS12&quot; keystorePass=&quot;password&quot;
-           truststoreFile=&quot;${jboss.server.home.dir}/conf/ca.jks&quot;
-           truststoreType=&quot;JKS&quot; truststorePass=&quot;password&quot;
-      /&gt;       
-            </programlisting>
-            <parameter>clientAuth</parameter> can also be set to <parameter>want</parameter> if you still want SSL connections to
-            succeed even if the client doesn't provide a certificate. Obviously these clients won't be able to access any Acegi-secured
-            objects.
-            </para>
-        </sect2>
-        
+      <title>X509 Authentication</title>
+
+      <sect2 id="security-x509-overview">
+        <title>Overview</title>
+
+        <para>The most common use of X509 certificate authentication is in
+        verifying the identity of a server when using SSL, most commonly when
+        using HTTPS from a browser. The browser will automatically check that
+        the certificate presented by a server has been issued (ie digitally
+        signed) by one of a list of trusted certificate authorities which it
+        maintains.</para>
+
+        <para>You can also use SSL with <quote>mutual authentication</quote>;
+        the server will then request a valid certificate from the client as
+        part of the SSL handshake. The server will authenticate the client by
+        checking that it's certificate is signed by an acceptable authority.
+        If a valid certificate has been provided, it can be obtained through
+        the servlet API in an application. The Acegi Security X509 module
+        extracts the certificate using a filter and passes it to the
+        configured X509 authentication provider to allow any additional
+        application-specific checks to be applied. It also maps the
+        certificate to an application user and loads that user's set of
+        granted authorities for use with the standard Acegi Security
+        infrastructure.</para>
+
+        <para>You should be familiar with using certificates and setting up
+        client authentication for your servlet container before attempting to
+        use it with Acegi Security. Most of the work is in creating and
+        installing suitable certificates and keys. For example, if you're
+        using Tomcat then read the instructions here <ulink
+        url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
+        It's important that you get this working before trying it out with
+        Acegi Security.</para>
+      </sect2>
+
+      <sect2 id="security-x509-details">
+        <title>X509 with Acegi Security</title>
+
+        <para>With X509 authentication, there is no explicit login procedure
+        so the implementation is relatively simple; there is no need to
+        redirect requests in order to interact with the user. As a result,
+        some of the classes behave slightly differently from their equivalents
+        in other packages. For example, the default <quote>entry point</quote>
+        class, which is normally responsible for starting the authentication
+        process, is only invoked if the certificate is rejected and it always
+        returns an error to the user. With a suitable bean configuration, the
+        normal sequence of events is as follows <orderedlist>
+             
+
+            <listitem>
+              <para>The <classname>X509ProcessingFilter</classname> extracts
+              the certificate from the request and uses it as the credentials
+              for an authentication request. The generated authentication
+              request is an <classname>X509AuthenticationToken</classname>.
+              The request is passed to the authentication manager.</para>
+            </listitem>
+
+             
+
+            <listitem>
+              <para>The <classname>X509AuthenticationProvider</classname>
+              receives the token. Its main concern is to obtain the user
+              information (in particular the user's granted authorities) that
+              matches the certificate. It delegates this responsibility to an
+              <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
+            </listitem>
+
+            . 
+
+            <listitem>
+              <para>The populator's single method,
+              <methodname>getUserDetails(X509Certificate
+              userCertificate)</methodname> is invoked. Implementations should
+              return a <classname>UserDetails</classname> instance containing
+              the array of <classname>GrantedAuthority</classname> objects for
+              the user. This method can also choose to reject the certificate
+              (for example if it doesn't contain a matching user name). In
+              such cases it should throw a
+              <exceptionname>BadCredentialsException</exceptionname>. A
+              DAO-based implementation,
+              <classname>DaoX509AuthoritiesPopulator</classname>, is provided
+              which extracts the user's name from the subject <quote>common
+              name</quote> (CN) in the certificate. It also allows you to set
+              your own regular expression to match a different part of the
+              subject's distinguished name. An
+              <classname>AuthenticationDao</classname> is used to load the
+              user information. <!-- TODO: Give email matching as an example --></para>
+            </listitem>
+
+             
+
+            <listitem>
+              <para>If everything has gone smoothly then there should be a
+              valid <classname>Authentication</classname> object in the secure
+              context and the invocation will procede as normal. If no
+              certificate was found, or the certificate was rejected, then the
+              <classname>SecurityEnforcementFilter</classname> will invoke the
+              <classname>X509ProcessingFilterEntryPoint</classname> which
+              returns a 403 error (forbidden) to the user.</para>
+            </listitem>
+
+             
+          </orderedlist></para>
+      </sect2>
+
+      <sect2 id="security-x509-config">
+        <title>Configuring the X509 Provider</title>
+
+        <para>There is a version of the <link
+        linkend="security-sample">contacts sample application</link> which
+        uses X509. Copy the beans and filter setup from this as a starting
+        point for configuring your own application. A set of example
+        certificates is also included which you can use to configure your
+        server. These are <itemizedlist>
+            <listitem>
+              <para><filename>marissa.p12</filename>: A PKCS12 format file
+              containing the client key and certificate. These should be
+              installed in your browser. It maps to the user
+              <quote>marissa</quote> in the application.</para>
+            </listitem>
+
+            <listitem>
+              <para><filename>server.p12</filename>: The server certificate
+              and key for HTTPS connections.</para>
+            </listitem>
+
+            <listitem>
+              <para><filename>ca.jks</filename>: A Java keystore containing
+              the certificate for the authority which issued marissa's
+              certificate. This will be used by the container to validate
+              client certificates.</para>
+            </listitem>
+          </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
+        configuration in the <filename>server.xml</filename> file looks like
+        this <programlisting>&lt;!-- SSL/TLS Connector configuration --&gt;
+&lt;Connector port="8443" address="${jboss.bind.address}"
+  maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+  scheme="https" secure="true"
+  sslProtocol = "TLS"
+  clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
+  keystoreType="PKCS12" keystorePass="password"
+  truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
+  truststoreType="JKS" truststorePass="password"
+/&gt;</programlisting><parameter>clientAuth</parameter> can also be set to
+        <parameter>want</parameter> if you still want SSL connections to
+        succeed even if the client doesn't provide a certificate. Obviously
+        these clients won't be able to access any objects secured by Acegi
+        Security (unless you use a non-X509 authentication mechanism, such as
+        BASIC authentication, to authenticate the user).</para>
+      </sect2>
     </sect1>
-     
+
     <sect1 id="security-channels">
       <title>Channel Security</title>