Converted to docbook5

src/docbkx/anon-auth-provider.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anonymous"><info><title>Anonymous Authentication</title></info>
 
-<chapter id="anonymous">
-<title>Anonymous Authentication</title>
 
-<sect1 id="anonymous-overview">
-    <title>Overview</title>
+<section xml:id="anonymous-overview"><info><title>Overview</title></info>
+    
     
     <para>Particularly in the case of web request URI security, sometimes
         it is more convenient to assign configuration attributes against every
@@ -22,10 +18,10 @@
         <literal>SecurityContextHolder</literal> always contains an
         <literal>Authentication</literal> object, and never
         <literal>null</literal>.</para>
-</sect1>
+</section>
 
-<sect1 id="anonymous-config">
-    <title>Configuration</title>
+<section xml:id="anonymous-config"><info><title>Configuration</title></info>
+    
     
     <para>Spring Security provides three classes that together provide an
         anonymous authentication feature.
@@ -105,5 +101,5 @@
         principals would always be deemed "authenticated" and never be given
         an opportunity to login via form, basic, digest or some other normal
         authentication mechanism</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/authorization-common.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authorization-common"><info><title>Common Authorization Concepts</title></info>
+  
 
-<chapter id="authorization-common">
-  <title>Common Authorization Concepts</title>
-
-  <sect1 id="authorities">
-    <title>Authorities</title>
+  <section xml:id="authorities"><info><title>Authorities</title></info>
+    
 
     <para>As briefly mentioned in the Authentication section, all
     <literal>Authentication</literal> implementations are required to
@@ -53,10 +49,10 @@
     <literal>AuthenticationProvider</literal>s included with the security
     architecture use <literal>GrantedAuthorityImpl</literal> to populate
     the <literal>Authentication</literal> object.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="pre-invocation">
-    <title>Pre-Invocation Handling</title>
+  <section xml:id="pre-invocation"><info><title>Pre-Invocation Handling</title></info>
+    
 
     <para>The <literal>AccessDecisionManager</literal> is called by the
     <literal>AbstractSecurityInterceptor</literal> and is responsible for
@@ -100,9 +96,7 @@ public boolean supports(Class clazz);</programlisting></para>
 
     <para><mediaobject>
         <imageobject role="html">
-          <imagedata align="center"
-                     fileref="images/AccessDecisionVoting.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/AccessDecisionVoting.gif" format="GIF"/>
         </imageobject>
 
         <caption>
@@ -252,10 +246,10 @@ public boolean supports(Class clazz);</programlisting></para>
     <para>TODO: Remove references to the old ACL package when it's
     deprecated, and have all references to the replacement package limited
     to the chapter describing the new ACL implementation.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="after-invocation">
-    <title>After Invocation Handling</title>
+  <section xml:id="after-invocation"><info><title>After Invocation Handling</title></info>
+    
 
     <para>Whilst the <literal>AccessDecisionManager</literal> is called by
     the <literal>AbstractSecurityInterceptor</literal> before proceeding
@@ -272,8 +266,7 @@ public boolean supports(Class clazz);</programlisting></para>
 
     <para><mediaobject>
         <imageobject>
-          <imagedata align="center" fileref="images/AfterInvocation.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/AfterInvocation.gif" format="GIF"/>
         </imageobject>
 
         <caption>
@@ -314,8 +307,8 @@ public boolean supports(Class clazz);</programlisting></para>
     achieved through a <literal>ROLE_USER</literal> or
     <literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
 
-    <sect2 id="after-invocation-acl-aware">
-      <title>ACL-Aware AfterInvocationProviders</title>
+    <section xml:id="after-invocation-acl-aware"><info><title>ACL-Aware AfterInvocationProviders</title></info>
+      
 
       <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
       ACL module. The new ACL module is a significant rewrite of the
@@ -398,10 +391,10 @@ public boolean supports(Class clazz);</programlisting></para>
 
       <para>The Contacts sample application demonstrates these two
       <literal>AfterInvocationProvider</literal>s.</para>
-    </sect2>
+    </section>
 
-    <sect2 id="after-invocation-acl-aware-old">
-      <title>ACL-Aware AfterInvocationProviders (old ACL module)</title>
+    <section xml:id="after-invocation-acl-aware-old"><info><title>ACL-Aware AfterInvocationProviders (old ACL module)</title></info>
+      
 
       <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
       ACL module. The new ACL module is a significant rewrite of the
@@ -478,11 +471,11 @@ public boolean supports(Class clazz);</programlisting></para>
 
       <para>The Contacts sample application demonstrates these two
       <literal>AfterInvocationProvider</literal>s.</para>
-    </sect2>
-  </sect1>
+    </section>
+  </section>
 
-  <sect1 id="authorization-taglibs">
-    <title>Authorization Tag Libraries</title>
+  <section xml:id="authorization-taglibs"><info><title>Authorization Tag Libraries</title></info>
+    
 
     <para><literal>AuthorizeTag</literal> is used to include content if
     the current principal holds certain
@@ -569,5 +562,5 @@ public boolean supports(Class clazz);</programlisting></para>
     should be considered deprecated. For the sake of historical reference,
     works exactly the samae as
     <literal>AccessControlListTag</literal>.</para>
-  </sect1>
+  </section>
 </chapter>

src/docbkx/basic-authentication.xml

@@ -1,13 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-                         
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="basic"><info><title>BASIC Authentication Mechanism</title></info>
 
-<chapter id="basic">
-<title>BASIC Authentication Mechanism</title>
 
-<sect1 id="basic-overview">
-    <title>Overview</title>
+<section xml:id="basic-overview"><info><title>Overview</title></info>
+    
     
     <para>Spring Security provides a
         <literal>BasicProcessingFilter</literal> which is capable of
@@ -21,10 +16,10 @@
         is very widely deployed in user agents and implementation is extremely
         simple (it's just a Base64 encoding of the username:password,
         specified in an HTTP header).</para>
-</sect1>
+</section>
 
-<sect1 id="basic-config">
-    <title>Configuration</title>
+<section xml:id="basic-config"><info><title>Configuration</title></info>
+    
     
     <para>To implement HTTP Basic Authentication, it is necessary to
         define <literal>BasicProcessingFilter</literal> in the filter chain.
@@ -61,5 +56,5 @@
         only time the filter chain will be interrupted is if authentication
         fails and the <literal>AuthenticationEntryPoint</literal> is called,
         as discussed in the previous paragraph</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/cas-auth-provider.xml

@@ -1,12 +1,9 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="cas"><info><title>CAS Authentication</title></info>
+  
 
-<chapter id="cas">
-  <title>CAS Authentication</title>
-
-  <sect1 id="cas-overview">
-    <title>Overview</title>
+  <section xml:id="cas-overview">
+      <info><title>Overview</title></info>
+    
 
     <para>JA-SIG produces an enterprise-wide single sign on system known
     as CAS. Unlike other initiatives, JA-SIG's Central Authentication
@@ -24,10 +21,10 @@
     file, you will still need the CAS Java Server Pages and
     <literal>web.xml</literal> to customise and deploy your CAS
     server.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="cas-how-it-works">
-    <title>How CAS Works</title>
+  <section xml:id="cas-how-it-works"><info><title>How CAS Works</title></info>
+    
 
     <para>Whilst the CAS web site above contains two documents that detail
     the architecture of CAS, we present the general overview again here
@@ -106,7 +103,7 @@
     <para>The basic interaction between a web browser, CAS server and n
     Spring Security-secured service is as follows:</para>
 
-    <orderedlist>
+    <orderedlist inheritnum="ignore" continuation="restarts">
       <listitem>
         <para>The web user is browsing the service's public pages. CAS or
         Spring Security is not involved.</para>
@@ -301,18 +298,18 @@
     <para>It's good that you're still here! It might sound involved, but
     you can relax as Spring Security classes hide much of the complexity.
     Let's now look at how this is configured</para>
-  </sect1>
+  </section>
 
-  <sect1 id="cas-server">
-    <title>Optional CAS Server Setup</title>
+  <section xml:id="cas-server"><info><title>Optional CAS Server Setup</title></info>
+    
 
     <para>Spring Security can even act as the backend which a CAS version
     2.0 or 3.0 server utilises. The configuration approach is described
     below. Of course, if you have an existing CAS environment you might
     just like to use it instead.</para>
 
-    <sect2 id="cas-server-2">
-      <title>CAS Version 2.0</title>
+    <section xml:id="cas-server-2"><info><title>CAS Version 2.0</title></info>
+      
 
       <para>As mentioned above, Spring Security includes a
       <literal>PasswordHandler</literal> that bridges your existing
@@ -402,10 +399,10 @@
       web container's documentation on setting up HTTPS, if you need some
       additional help or a test certificate you might like to check the
       <literal>samples/contacts/etc/ssl</literal> directory</para>
-    </sect2>
+    </section>
 
-    <sect2 id="cas-server-3">
-      <title>CAS Version 3.0</title>
+    <section xml:id="cas-server-3"><info><title>CAS Version 3.0</title></info>
+      
 
       <para>As mentioned above, Spring Security includes an
       <literal>AuthenticationHandler</literal> that bridges your existing
@@ -493,11 +490,11 @@
       additional help or a test certificate you might like to check the
       CAS documentation on setting up SSL:
       <literal>http://www.ja-sig.org/products/cas/server/ssl/index.html</literal></para>
-    </sect2>
-  </sect1>
+    </section>
+  </section>
 
-  <sect1 id="cas-client">
-    <title>Configuration of CAS Client</title>
+  <section xml:id="cas-client"><info><title>Configuration of CAS Client</title></info>
+    
 
     <para>The web application side of CAS is made easy due to Spring
     Security. It is assumed you already know the basics of using Spring
@@ -508,11 +505,11 @@
     to your application context. This represents your service:</para>
 
     <para><programlisting>
-<![CDATA[ 
-<bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties">
-  <property name="service" value="https://localhost:8443/contacts-cas/j_spring_cas_security_check"/>
-  <property name="sendRenew"><value>false</value></property>
-</bean> ]]>
+ 
+&lt;bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties"&gt;
+  &lt;property name="service" value="https://localhost:8443/contacts-cas/j_spring_cas_security_check"/&gt;
+  &lt;property name="sendRenew"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt; 
     </programlisting></para>
 
     <para>The <literal>service</literal> must equal a URL that will be
@@ -526,38 +523,38 @@
     <para>The following beans should be configured to commence the CAS
     authentication process:</para>
 
-    <para><programlisting><![CDATA[ 
-<bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter">
-  <property name="authenticationManager" ref="authenticationManager"/>
-  <property name="authenticationFailureUrl" value="/casfailed.jsp"/>
-  <property name="defaultTargetUrl" value="/"/>
-  <property name="filterProcessesUrl" value="/j_spring_cas_security_check"/>
-</bean>
-
-<bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter">
-  <property name="authenticationEntryPoint" ref="casProcessingFilterEntryPoint"/>
-</bean>
-
-<bean id="casProcessingFilterEntryPoint"
-        class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint">
-  <property name="loginUrl" value="https://localhost:8443/cas/login"/>
-  <property name="serviceProperties" ref="serviceProperties"/>
-</bean>
- ]]>
+    <para><programlisting> 
+&lt;bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter"&gt;
+  &lt;property name="authenticationManager" ref="authenticationManager"/&gt;
+  &lt;property name="authenticationFailureUrl" value="/casfailed.jsp"/&gt;
+  &lt;property name="defaultTargetUrl" value="/"/&gt;
+  &lt;property name="filterProcessesUrl" value="/j_spring_cas_security_check"/&gt;
+&lt;/bean&gt;
+
+&lt;bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
+  &lt;property name="authenticationEntryPoint" ref="casProcessingFilterEntryPoint"/&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casProcessingFilterEntryPoint"
+        class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint"&gt;
+  &lt;property name="loginUrl" value="https://localhost:8443/cas/login"/&gt;
+  &lt;property name="serviceProperties" ref="serviceProperties"/&gt;
+&lt;/bean&gt;
+ 
     </programlisting></para>
 
     <para>You will also need to add the <literal>CasProcessingFilter</literal> to web.xml:</para>
 
-    <para><programlisting><![CDATA[ 
-<filter>
-    <filter-name>casProcessingFilter</filter-name>
-    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
-</filter>
+    <para><programlisting> 
+&lt;filter&gt;
+    &lt;filter-name&gt;casProcessingFilter&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
+&lt;/filter&gt;
 
-<filter-mapping>
-  <filter-name>casProcessingFilter</filter-name>
-  <url-pattern>/*</url-pattern>
-</filter-mapping> ]]>
+&lt;filter-mapping&gt;
+  &lt;filter-name&gt;casProcessingFilter&lt;/filter-name&gt;
+  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+&lt;/filter-mapping&gt; 
     </programlisting></para>
 
     <para>The <literal>CasProcessingFilter</literal> has very similar
@@ -671,10 +668,10 @@
     <para>There is also a <literal>contacts-cas.war</literal> file in the
     sample applications directory. This sample application uses the above
     settings and can be deployed to see CAS in operation</para>
-  </sect1>
+  </section>
 
-  <sect1 id="cas-advanced">
-    <title>Advanced Issues</title>
+  <section xml:id="cas-advanced"><info><title>Advanced Issues</title></info>
+    
 
     <para>The <literal>CasAuthenticationProvider</literal> distinguishes
     between stateful and stateless clients. A stateful client is
@@ -733,5 +730,5 @@
 
     <para>It is hoped you find CAS integration easy and useful with Spring
     Security classes. Welcome to enterprise-wide single sign on!</para>
-  </sect1>
-</chapter>
+  </section>
+</chapter>

src/docbkx/channel-security.xml

@@ -1,14 +1,10 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-                         
-                         
-<chapter id="channel-security">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="channel-security">
 
-<title>Channel Security</title>
+<info><title>Channel Security</title></info>
 
-<sect1 id="channel-security-overview">
-    <title>Overview</title>
+<section xml:id="channel-security-overview">
+    <info><title>Overview</title></info>
+    
     
     <para>In addition to coordinating the authentication and authorization
         requirements of your application, Spring Security is also able to
@@ -37,39 +33,39 @@
         <literal>&lt;welcome-file&gt;</literal> points to an HTTPS location,
         and the application never directs the user to an HTTP location. Spring
         Security provides a solution to assist with the latter.</para>
-</sect1>
+</section>
 
-<sect1 id="channel-security-config">
-    <title>Configuration</title>
+<section xml:id="channel-security-config"><info><title>Configuration</title></info>
+    
         
     <para>To use chanel security, you should define the following the filter in your application
         context:</para>
     
-    <para><programlisting><![CDATA[ 
-    <bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter">
-        <property name="channelDecisionManager" ref="channelDecisionManager"/>
-        <property name="filterInvocationDefinitionSource">
-            <security:filter-invocation-definition-source path-type="regex">
-                <security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
-                <security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/>
-                <security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
-                <security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/>
-            </security:filter-invocation-definition-source>                
-        </property>
-    </bean>
+    <para><programlisting> 
+    &lt;bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"&gt;
+        &lt;property name="channelDecisionManager" ref="channelDecisionManager"/&gt;
+        &lt;property name="filterInvocationDefinitionSource"&gt;
+            &lt;security:filter-invocation-definition-source path-type="regex"&gt;
+                &lt;security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
+                &lt;security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/&gt;
+                &lt;security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
+                &lt;security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/&gt;
+            &lt;/security:filter-invocation-definition-source&gt;                
+        &lt;/property&gt;
+    &lt;/bean&gt;
         
-    <bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl">
-        <property name="channelProcessors">
-            <list>
-            <ref bean="secureChannelProcessor"/>
-            <ref bean="insecureChannelProcessor"/>
-            </list>
-        </property>
-    </bean>
+    &lt;bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"&gt;
+        &lt;property name="channelProcessors"&gt;
+            &lt;list&gt;
+            &lt;ref bean="secureChannelProcessor"/&gt;
+            &lt;ref bean="insecureChannelProcessor"/&gt;
+            &lt;/list&gt;
+        &lt;/property&gt;
+    &lt;/bean&gt;
         
-    <bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/>
-    <bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/>
-     ]]>    
+    &lt;bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/&gt;
+    &lt;bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/&gt;
+         
     </programlisting></para>
     
     <para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
@@ -126,10 +122,10 @@
         <literal>REQUIRES_SECURE_CHANNEL</literal>, and that the
         <literal>AuthenticationProcessingFilterEntryPoint.forceHttps</literal>
         property is <literal>true</literal>.</para>
-</sect1>
+</section>
 
-<sect1 id="channel-security-conclusion">
-    <title>Conclusion</title>
+<section xml:id="channel-security-conclusion"><info><title>Conclusion</title></info>
+    
     
     <para>Once configured, using the channel security filter is very easy.
         Simply request pages without regard to the protocol (ie HTTP or HTTPS)
@@ -161,5 +157,5 @@
         <literal>AccessDecisionVoter</literal> will ultimately result in an
         <literal>AccessDeniedException</literal> (depending on the governing
         <literal>AccessDecisionManager</literal>).</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/common-auth-services.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="authentication-common-auth-services"><info><title>Common Authentication Services</title></info>
+  
 
-<chapter id="authentication-common-auth-services">
-  <title>Common Authentication Services</title>
-
-  <sect1 id="mechanisms-providers-entry-points">
-    <title>Mechanisms, Providers and Entry Points</title>
+  <section xml:id="mechanisms-providers-entry-points"><info><title>Mechanisms, Providers and Entry Points</title></info>
+    
 
     <para>If you're using Spring Security-provided authentication
     approaches, you'll usually need to configure a web filter, together
@@ -23,17 +19,17 @@
     this:</para>
 
     <para><programlisting>
-<![CDATA[ 
-    <filter>
-        <filter-name>filterChainProxy</filter-name>
-        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
-    </filter>
-
-    <filter-mapping>
-      <filter-name>filterChainProxy</filter-name>
-      <url-pattern>/*</url-pattern>
-    </filter-mapping>
-]]></programlisting></para>
+ 
+    &lt;filter&gt;
+        &lt;filter-name&gt;filterChainProxy&lt;/filter-name&gt;
+        &lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
+    &lt;/filter&gt;
+
+    &lt;filter-mapping&gt;
+      &lt;filter-name&gt;filterChainProxy&lt;/filter-name&gt;
+      &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+    &lt;/filter-mapping&gt;
+</programlisting></para>
 
     <para>The above declarations will cause every web request to be passed
         through to the bean called <literal>filterChainProxy</literal>
@@ -230,10 +226,10 @@
     point to use for each authentication approach is discussed in the
     authentication approach-specific chapters of this reference
     guide.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="userdetails-and-associated-types">
-    <title>UserDetails and Associated Types</title>
+  <section xml:id="userdetails-and-associated-types"><info><title>UserDetails and Associated Types</title></info>
+    
 
     <para>As mentioned in the first part of the reference guide, most
     authentication providers take advantage of the
@@ -277,8 +273,8 @@
     that, Spring Security does include a couple of useful base
     implementations, which we'll look at below.</para>
 
-    <sect2 id="in-memory-service">
-      <title>In-Memory Authentication</title>
+    <section xml:id="in-memory-service"><info><title>In-Memory Authentication</title></info>
+      
 
       <para>Whilst it is easy to use create a custom
       <literal>UserDetailsService</literal> implementation that extracts
@@ -329,10 +325,10 @@
       useful for simple applications that have a larger number of users,
       or deployment-time configuration changes, but do not wish to use a
       full database for handling authentication details.</para>
-    </sect2>
+    </section>
 
-    <sect2 id="jdbc-service">
-      <title>JDBC Authentication</title>
+    <section xml:id="jdbc-service"><info><title>JDBC Authentication</title></info>
+      
 
       <para>Spring Security also includes a
       <literal>UserDetailsService</literal> that can obtain authentication
@@ -376,11 +372,11 @@
       <literal>UserDetailsService</literal>. The base implementation
       provided with Spring Security is intended for typical situations,
       and does not offer infinite configuration flexibility.</para>
-    </sect2>
-  </sect1>
+    </section>
+  </section>
 
-  <sect1 id="concurrent-sessions">
-    <title>Concurrent Session Handling</title>
+  <section xml:id="concurrent-sessions"><info><title>Concurrent Session Handling</title></info>
+    
 
     <para>Spring Security is able to prevent a principal from concurrently
     authenticating to the same application more than a specified number of
@@ -433,10 +429,10 @@
 &lt;/bean&gt;
 
 &lt;bean id="sessionRegistry" class="org.springframework.security.concurrent.SessionRegistryImpl"/&gt;</programlisting></para>
-  </sect1>
+  </section>
 
-  <sect1 id="authentication-taglibs">
-    <title>Authentication Tag Libraries</title>
+  <section xml:id="authentication-taglibs"><info><title>Authentication Tag Libraries</title></info>
+    
 
     <para><literal>AuthenticationTag</literal> is used to simply output a
     property of the current principal's
@@ -453,5 +449,5 @@
     <literal>UserDetails</literal> object, which is generally the case
     when using the typical
     <literal>DaoAuthenticationProvider</literal>.</para>
-  </sect1>
-</chapter>
+  </section>
+</chapter>

src/docbkx/community.xml

@@ -1,12 +1,14 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 
+    xml:id="community"
+    xmlns:xlink="http://www.w3.org/1999/xlink" >
+    
+    
+    <info><title>Community Support</title></info>
 
-<chapter id="community">
-<title>Community Support</title>
 
-<sect1 id="jira">
-    <title>Use JIRA for Issue Tracking</title>
+<section xml:id="jira">
+    <info><title>Use JIRA for Issue Tracking</title></info>
+    
     
     <para>Spring Security uses JIRA to manage bug reports and enhancement
         requests. If you find a bug, please log a report using JIRA. Do not
@@ -21,12 +23,11 @@
         if you include corresponding unit tests. This is necessary to ensure
         project test coverage is adequately maintained.</para>
     
-    <para>You can access JIRA at <ulink
-        url="http://opensource.atlassian.com/projects/spring/secure/BrowseProject.jspa?id=10040"></ulink>.</para>
-</sect1>
+    <para>You can access JIRA at <link xlink:href="http://jira.springframework.org/browse/SEC">http://jira.springframework.org/browse/SEC</link>.</para>
+</section>
 
-<sect1 id="becoming-involved">
-    <title>Becoming Involved</title>
+<section xml:id="becoming-involved"><info><title>Becoming Involved</title></info>
+    
     
     <para>We welcome you to become involved in Spring Security project.
         There are many ways of contributing, including reading the mailing
@@ -38,21 +39,19 @@
         Spring Security home page. This explains the path to become a
         committer, and the administration approaches we use within the
         project.</para>
-</sect1>
+</section>
 
-<sect1 id="further-info">
-    <title>Further Information</title>
+<section xml:id="further-info"><info><title>Further Information</title></info>
+    
     
     <para>Questions and comments on Spring Security are welcome. Please
-        use the Spring Community Forum web site at <ulink
-            url="http://forum.springframework.org"></ulink> for all support
+        use the Spring Community Forum web site at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://forum.springframework.org">http://forum.springframework.org</uri> for all support
         issues. Remember to use JIRA for bug reports, as explained above.
         Everyone is also welcome to join the Acegisecurity-developer mailing
         list and participate in design discussions. It's also a good way of
         finding out what's happening with regard to release timing, and the
         traffic volume is quite light. Finally, our project home page (where
         you can obtain the latest release of the project and convenient links
-        to Subversion, JIRA, mailing lists, forums etc) is at <ulink
-            url="http://acegisecurity.org"></ulink>.</para>
-</sect1>
+        to Subversion, JIRA, mailing lists, forums etc) is at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://acegisecurity.org">http://acegisecurity.org</uri>.</para>
+</section>
 </chapter>

src/docbkx/container-adapters.xml

@@ -1,12 +1,9 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">  
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ca"><info><title>Container Adapter Authentication</title></info>
+  
 
-<chapter id="ca">
-  <title>Container Adapter Authentication</title>
-
-  <sect1 id="ca-overview">
-    <title>Overview</title>
+  <section xml:id="ca-overview">
+    <info><title>Overview</title></info>
+    
 
     <para>Very early versions of Spring Security exclusively used
     Container Adapters for interfacing authentication with end users.
@@ -45,10 +42,10 @@
     <para>Spring Security currently supports Jetty, Catalina (Tomcat),
     JBoss and Resin. Additional container adapters can easily be
     written</para>
-  </sect1>
+  </section>
 
-  <sect1 id="ca-adapter">
-    <title>Adapter Authentication Provider</title>
+  <section xml:id="ca-adapter"><info><title>Adapter Authentication Provider</title></info>
+    
 
     <para>As is always the case, the container adapter generated
     <literal>Authentication</literal> object still needs to be
@@ -103,10 +100,10 @@
     <literal>DaoAuthenticationProvider</literal>, ensure you set its
     <literal>forcePrincipalAsString</literal> property to
     <literal>true</literal>.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="ca-jetty">
-    <title>Jetty</title>
+  <section xml:id="ca-jetty"><info><title>Jetty</title></info>
+    
 
     <para>The following was tested with Jetty 4.2.18.</para>
 
@@ -172,10 +169,10 @@
     <literal>&lt;realm-name&gt;</literal> as your
     <literal>jetty.xml</literal> (in the example above, "Spring Powered
     Realm").</para>
-  </sect1>
+  </section>
 
-  <sect1 id="ca-jboss">
-    <title>JBoss</title>
+  <section xml:id="ca-jboss"><info><title>JBoss</title></info>
+    
 
     <para>The following was tested with JBoss 3.2.6.</para>
 
@@ -302,10 +299,10 @@
     <para>JBoss is a widely-used container adapter (mostly due to the need
     to support legacy EJBs), so please let us know if you have any
     difficulties.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="ca-resin">
-    <title>Resin</title>
+  <section xml:id="ca-resin"><info><title>Resin</title></info>
+    
 
     <para>The following was tested with Resin 3.0.6.</para>
 
@@ -377,10 +374,10 @@
     indicated in your <literal>web.xml</literal> does not matter with
     Resin, as the relevant authentication class is indicated by the
     <literal>&lt;authenticator&gt;</literal> setting</para>
-  </sect1>
+  </section>
 
-  <sect1 id="ca-tomcat">
-    <title>Tomcat</title>
+  <section xml:id="ca-tomcat"><info><title>Tomcat</title></info>
+    
 
     <para>The following was tested with Jakarta Tomcat 4.1.30 and
     5.0.19.</para>
@@ -449,5 +446,5 @@ cd /
 $CATALINA_HOME/bin/startup.sh</programlisting></para>
 
     <para>Finally, restart Tomcat.</para>
-  </sect1>
+  </section>
 </chapter>

src/docbkx/dao-auth-provider.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dao-provider"><info><title>DAO Authentication Provider</title></info>
 
-<chapter id="dao-provider">
-<title>DAO Authentication Provider</title>
 
-<sect1 id="dao-provider-overview">
-    <title>Overview</title>
+<section xml:id="dao-provider-overview"><info><title>Overview</title></info>
+    
     
     <para>Spring Security includes a production-quality
         <literal>AuthenticationProvider</literal> implementation called
@@ -22,10 +18,10 @@
         presented, and the provider will actually evaluate the validity or
         otherwise of the password presented in an authentication request
         object.</para>
-</sect1>
+</section>
 
-<sect1 id="dao-provider-config">
-    <title>Configuration</title>
+<section xml:id="dao-provider-config"><info><title>Configuration</title></info>
+    
     
     <para>Aside from adding DaoAuthenticationProvider to your
         ProviderManager list (as discussed at the start of this part of the
@@ -126,5 +122,5 @@
         prior to Spring Security 0.6), you should set the
         <literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
         property to <literal>true</literal> in your application context</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/digest-authentication.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
-
-<chapter id="digest">
-    <title>Digest Authentication</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="digest"><info><title>Digest Authentication</title></info>
     
-    <sect1 id="digest-overview">
-        <title>Overview</title>
+    
+    <section xml:id="digest-overview"><info><title>Overview</title></info>
+        
         
         <para>Spring Security provides a
             <literal>DigestProcessingFilter</literal> which is capable of
@@ -80,10 +76,10 @@
             "<literal>nonce</literal>" token instead. In our testing, Spring
             Security implementation works reliably with FireFox and Internet
             Explorer, correctly handling nonce timeouts etc.</para>
-    </sect1>
+    </section>
     
-    <sect1 id="digest-config">
-        <title>Configuration</title>
+    <section xml:id="digest-config"><info><title>Configuration</title></info>
+        
         
         <para>Now that we've reviewed the theory, let's see how to use it. To
             implement HTTP Digest Authentication, it is necessary to define
@@ -141,5 +137,5 @@
             if you wish to explore these features in more detail. As far as we are
             aware, Spring Security's implementation does comply with the minimum
             standards of this RFC.</para>
-    </sect1>
+    </section>
 </chapter>

src/docbkx/domain-acls-old.xml

@@ -1,12 +1,9 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="domain-acls-old">
+  <info><title>Domain Object Security (old ACL module)</title></info>
+  
 
-<chapter id="domain-acls-old">
-  <title>Domain Object Security (old ACL module)</title>
-
-  <section id="domain-acls-overview-old">
-    <title>Overview</title>
+  <section xml:id="domain-acls-overview-old"><info><title>Overview</title></info>
+    
 
     <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
     ACL module. The new ACL module is a significant rewrite of the
@@ -35,7 +32,7 @@
     more interesting, your customers can allow other users to see their
     customer records, such as their "puppy preschool "mentor or president
     of their local "Pony Club". Using Spring Security as the foundation,
-    you have several approaches that can be used:<orderedlist>
+    you have several approaches that can be used:<orderedlist inheritnum="ignore" continuation="restarts">
         <listitem>
           <para>Write your business methods to enforce the security. You
           could consult a collection within the
@@ -95,8 +92,8 @@
     about below.</para>
   </section>
 
-  <section id="domain-acls-basic-old">
-    <title>Basic ACL Package</title>
+  <section xml:id="domain-acls-basic-old"><info><title>Basic ACL Package</title></info>
+    
 
     <para>Please note that our Basic ACL services are currently being
     refactored. We expect release 1.1.0 will contain this new code.
@@ -112,8 +109,7 @@
 
     <para><mediaobject>
         <imageobject role="html">
-          <imagedata align="center" fileref="images/ACLSecurity.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/ACLSecurity.gif" format="GIF"/>
         </imageobject>
 
         <caption>
@@ -171,8 +167,7 @@ public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authen
 
     <para><mediaobject>
         <imageobject role="html">
-          <imagedata align="center" fileref="images/BasicAclProvider.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/BasicAclProvider.gif" format="GIF"/>
         </imageobject>
 
         <caption>
@@ -463,8 +458,7 @@ END;
 
     <mediaobject>
       <imageobject role="html">
-        <imagedata align="center" fileref="images/Permissions.gif"
-                   format="GIF" />
+        <imagedata align="center" fileref="images/Permissions.gif" format="GIF"/>
       </imageobject>
 
       <caption>

src/docbkx/domain-acls.xml

@@ -1,181 +1,179 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-
-<chapter id="domain-acls">
-
-<title>Domain Object Security</title>
-
-<section id="domain-acls-overview">
-    <title>Overview</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="domain-acls">
     
-    <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
-        ACL module. The new ACL module is a significant rewrite of the
-        existing ACL module. The new module can be found under the
-        <literal>org.springframework.security.acls</literal> package, with the
-        old ACL module under
-        <literal>org.springframework.security.acl</literal>. We encourage
-        users to consider testing with the new ACL module and build
-        applications with it. The old ACL module should be considered
-        deprecated and may be removed from a future release.</para>
+    <info><title>Domain Object Security</title></info>
     
-    <para>Complex applications often will find the need to define access
-        permissions not simply at a web request or method invocation level.
-        Instead, security decisions need to comprise both who
-        (<literal>Authentication</literal>), where
-        (<literal>MethodInvocation</literal>) and what
-        (<literal>SomeDomainObject</literal>). In other words, authorization
-        decisions also need to consider the actual domain object instance
-        subject of a method invocation.</para>
     
-    <para>Imagine you're designing an application for a pet clinic. There
-        will be two main groups of users of your Spring-based application:
-        staff of the pet clinic, as well as the pet clinic's customers. The
-        staff will have access to all of the data, whilst your customers will
-        only be able to see their own customer records. To make it a little
-        more interesting, your customers can allow other users to see their
-        customer records, such as their "puppy preschool "mentor or president
-        of their local "Pony Club". Using Spring Security as the foundation,
-        you have several approaches that can be used:<orderedlist>
+    
+    <section xml:id="domain-acls-overview"><info><title>Overview</title></info>
+        
+        
+        <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
+            ACL module. The new ACL module is a significant rewrite of the
+            existing ACL module. The new module can be found under the
+            <literal>org.springframework.security.acls</literal> package, with the
+            old ACL module under
+            <literal>org.springframework.security.acl</literal>. We encourage
+            users to consider testing with the new ACL module and build
+            applications with it. The old ACL module should be considered
+            deprecated and may be removed from a future release.</para>
+        
+        <para>Complex applications often will find the need to define access
+            permissions not simply at a web request or method invocation level.
+            Instead, security decisions need to comprise both who
+            (<literal>Authentication</literal>), where
+            (<literal>MethodInvocation</literal>) and what
+            (<literal>SomeDomainObject</literal>). In other words, authorization
+            decisions also need to consider the actual domain object instance
+            subject of a method invocation.</para>
+        
+        <para>Imagine you're designing an application for a pet clinic. There
+            will be two main groups of users of your Spring-based application:
+            staff of the pet clinic, as well as the pet clinic's customers. The
+            staff will have access to all of the data, whilst your customers will
+            only be able to see their own customer records. To make it a little
+            more interesting, your customers can allow other users to see their
+            customer records, such as their "puppy preschool "mentor or president
+            of their local "Pony Club". Using Spring Security as the foundation,
+            you have several approaches that can be used:<orderedlist inheritnum="ignore" continuation="restarts">
+                <listitem>
+                    <para>Write your business methods to enforce the security. You
+                        could consult a collection within the
+                        <literal>Customer</literal> domain object instance to determine
+                        which users have access. By using the
+                        <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
+                        you'll be able to access the <literal>Authentication</literal>
+                        object.</para>
+                </listitem>
+                
+                <listitem>
+                    <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+                        the security from the <literal>GrantedAuthority[]</literal>s
+                        stored in the <literal>Authentication</literal> object. This
+                        would mean your <literal>AuthenticationManager</literal> would
+                        need to populate the <literal>Authentication</literal> with
+                        custom <literal>GrantedAuthority</literal>[]s representing each
+                        of the <literal>Customer</literal> domain object instances the
+                        principal has access to.</para>
+                </listitem>
+                
+                <listitem>
+                    <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+                        the security and open the target <literal>Customer</literal>
+                        domain object directly. This would mean your voter needs access
+                        to a DAO that allows it to retrieve the
+                        <literal>Customer</literal> object. It would then access the
+                        <literal>Customer</literal> object's collection of approved
+                        users and make the appropriate decision.</para>
+                </listitem>
+            </orderedlist></para>
+        
+        <para>Each one of these approaches is perfectly legitimate. However,
+            the first couples your authorization checking to your business code.
+            The main problems with this include the enhanced difficulty of unit
+            testing and the fact it would be more difficult to reuse the
+            <literal>Customer</literal> authorization logic elsewhere. Obtaining
+            the <literal>GrantedAuthority[]</literal>s from the
+            <literal>Authentication</literal> object is also fine, but will not
+            scale to large numbers of <literal>Customer</literal>s. If a user
+            might be able to access 5,000 <literal>Customer</literal>s (unlikely
+            in this case, but imagine if it were a popular vet for a large Pony
+            Club!) the amount of memory consumed and time required to construct
+            the <literal>Authentication</literal> object would be undesirable. The
+            final method, opening the <literal>Customer</literal> directly from
+            external code, is probably the best of the three. It achieves
+            separation of concerns, and doesn't misuse memory or CPU cycles, but
+            it is still inefficient in that both the
+            <literal>AccessDecisionVoter</literal> and the eventual business
+            method itself will perform a call to the DAO responsible for
+            retrieving the <literal>Customer</literal> object. Two accesses per
+            method invocation is clearly undesirable. In addition, with every
+            approach listed you'll need to write your own access control list
+            (ACL) persistence and business logic from scratch.</para>
+        
+        <para>Fortunately, there is another alternative, which we'll talk
+            about below.</para>
+    </section>
+    
+    <section xml:id="domain-acls-key-concepts"><info><title>Key Concepts</title></info>
+        
+        
+        <para>The org.springframework.security.acls package should be
+            consulted for its major interfaces. The key interfaces are:</para>
+        
+        <itemizedlist spacing="compact">
             <listitem>
-                <para>Write your business methods to enforce the security. You
-                    could consult a collection within the
-                    <literal>Customer</literal> domain object instance to determine
-                    which users have access. By using the
-                    <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
-                    you'll be able to access the <literal>Authentication</literal>
-                    object.</para>
+                <para><literal>Acl</literal>: Every domain object has one and only
+                    one <literal>Acl</literal> object, which internally holds the
+                    <literal>AccessControlEntry</literal>s as well as knows the owner
+                    of the <literal>Acl</literal>. An Acl does not refer directly to
+                    the domain object, but instead to an
+                    <literal>ObjectIdentity</literal>.</para>
             </listitem>
             
             <listitem>
-                <para>Write an <literal>AccessDecisionVoter</literal> to enforce
-                    the security from the <literal>GrantedAuthority[]</literal>s
-                    stored in the <literal>Authentication</literal> object. This
-                    would mean your <literal>AuthenticationManager</literal> would
-                    need to populate the <literal>Authentication</literal> with
-                    custom <literal>GrantedAuthority</literal>[]s representing each
-                    of the <literal>Customer</literal> domain object instances the
-                    principal has access to.</para>
+                <para><literal>AccessControlEntry</literal>: An
+                    Acl holds multiple <literal>AccessControlEntry</literal>s, which
+                    are often abbreviated as ACEs in the framework. Each ACE refers to
+                    a specific tuple of <literal>Permission</literal>,
+                    <literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
+                    be granting or non-granting and contain audit settings.</para>
             </listitem>
             
             <listitem>
-                <para>Write an <literal>AccessDecisionVoter</literal> to enforce
-                    the security and open the target <literal>Customer</literal>
-                    domain object directly. This would mean your voter needs access
-                    to a DAO that allows it to retrieve the
-                    <literal>Customer</literal> object. It would then access the
-                    <literal>Customer</literal> object's collection of approved
-                    users and make the appropriate decision.</para>
+                <para><literal>Permission</literal>: A permission represents an
+                    immutable particular bit mask, and offers convenience functions
+                    for bit masking and outputting information.</para>
             </listitem>
-        </orderedlist></para>
-    
-    <para>Each one of these approaches is perfectly legitimate. However,
-        the first couples your authorization checking to your business code.
-        The main problems with this include the enhanced difficulty of unit
-        testing and the fact it would be more difficult to reuse the
-        <literal>Customer</literal> authorization logic elsewhere. Obtaining
-        the <literal>GrantedAuthority[]</literal>s from the
-        <literal>Authentication</literal> object is also fine, but will not
-        scale to large numbers of <literal>Customer</literal>s. If a user
-        might be able to access 5,000 <literal>Customer</literal>s (unlikely
-        in this case, but imagine if it were a popular vet for a large Pony
-        Club!) the amount of memory consumed and time required to construct
-        the <literal>Authentication</literal> object would be undesirable. The
-        final method, opening the <literal>Customer</literal> directly from
-        external code, is probably the best of the three. It achieves
-        separation of concerns, and doesn't misuse memory or CPU cycles, but
-        it is still inefficient in that both the
-        <literal>AccessDecisionVoter</literal> and the eventual business
-        method itself will perform a call to the DAO responsible for
-        retrieving the <literal>Customer</literal> object. Two accesses per
-        method invocation is clearly undesirable. In addition, with every
-        approach listed you'll need to write your own access control list
-        (ACL) persistence and business logic from scratch.</para>
-    
-    <para>Fortunately, there is another alternative, which we'll talk
-        about below.</para>
-</section>
-
-<section id="domain-acls-key-concepts">
-    <title>Key Concepts</title>
-    
-    <para>The org.springframework.security.acls package should be
-        consulted for its major interfaces. The key interfaces are:</para>
-    
-    <itemizedlist spacing="compact">
-        <listitem>
-            <para><literal>Acl</literal>: Every domain object has one and only
-                one <literal>Acl</literal> object, which internally holds the
-                <literal>AccessControlEntry</literal>s as well as knows the owner
-                of the <literal>Acl</literal>. An Acl does not refer directly to
-                the domain object, but instead to an
-                <literal>ObjectIdentity</literal>.</para>
-        </listitem>
-        
-        <listitem>
-            <para><literal><literal>AccessControlEntry</literal></literal>: An
-                Acl holds multiple <literal>AccessControlEntry</literal>s, which
-                are often abbreviated as ACEs in the framework. Each ACE refers to
-                a specific tuple of <literal>Permission</literal>,
-                <literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
-                be granting or non-granting and contain audit settings.</para>
-        </listitem>
-        
-        <listitem>
-            <para><literal>Permission</literal>: A permission represents an
-                immutable particular bit mask, and offers convenience functions
-                for bit masking and outputting information.</para>
-        </listitem>
-        
-        <listitem>
-            <para><literal>Sid</literal>: The ACL module needs to refer to
-                principals and <literal>GrantedAuthority[]</literal>s. A level of
-                indirection is provided by the <literal>Sid</literal> interface.
-                Common classes include <literal>PrincipalSid</literal> (to
-                represent the principal inside an
-                <literal>Authentication</literal> object) and
-                <literal>GrantedAuthoritySid</literal>.</para>
-        </listitem>
+            
+            <listitem>
+                <para><literal>Sid</literal>: The ACL module needs to refer to
+                    principals and <literal>GrantedAuthority[]</literal>s. A level of
+                    indirection is provided by the <literal>Sid</literal> interface.
+                    Common classes include <literal>PrincipalSid</literal> (to
+                    represent the principal inside an
+                    <literal>Authentication</literal> object) and
+                    <literal>GrantedAuthoritySid</literal>.</para>
+            </listitem>
+            
+            <listitem>
+                <para><literal>ObjectIdentity</literal>: Each domain object is
+                    represented internally within the ACL module by an
+                    <literal>ObjectIdentity</literal>.</para>
+            </listitem>
+            
+            <listitem>
+                <para><literal>AclService</literal>: Retrieves the
+                    <literal>Acl</literal> applicable for a given
+                    <literal>ObjectIdentity</literal>.</para>
+            </listitem>
+            
+            <listitem>
+                <para><literal>MutableAclService</literal>: Allows a modified
+                    <literal>Acl</literal> to be presented for persistence. It is not
+                    essential to use this interface if you do not wish.</para>
+            </listitem>
+        </itemizedlist>
         
-        <listitem>
-            <para><literal>ObjectIdentity</literal>: Each domain object is
-                represented internally within the ACL module by an
-                <literal>ObjectIdentity</literal>.</para>
-        </listitem>
+        <para>The ACL module was based on extensive feedback from the user
+            community following real-world use of the original ACL module. This
+            feedback resulted in a rearchitecture of the ACL module to offer
+            significantly enhanced performance (particularly in the area of
+            database retrieval), significantly better encapsulation, higher
+            cohesion, and enhanced customisation points.</para>
         
-        <listitem>
-            <para><literal>AclService</literal>: Retrieves the
-                <literal>Acl</literal> applicable for a given
-                <literal>ObjectIdentity</literal>.</para>
-        </listitem>
+        <para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
+            a demonstration of the new ACL module. Converting Contacts from using
+            the old module to the new module was relatively simple, and users of
+            the old ACL module will likely find their applications can be modified
+            with relatively little work.</para>
         
-        <listitem>
-            <para><literal>MutableAclService</literal>: Allows a modified
-                <literal>Acl</literal> to be presented for persistence. It is not
-                essential to use this interface if you do not wish.</para>
-        </listitem>
-    </itemizedlist>
-    
-    <para>The ACL module was based on extensive feedback from the user
-        community following real-world use of the original ACL module. This
-        feedback resulted in a rearchitecture of the ACL module to offer
-        significantly enhanced performance (particularly in the area of
-        database retrieval), significantly better encapsulation, higher
-        cohesion, and enhanced customisation points.</para>
-    
-    <para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
-        a demonstration of the new ACL module. Converting Contacts from using
-        the old module to the new module was relatively simple, and users of
-        the old ACL module will likely find their applications can be modified
-        with relatively little work.</para>
-    
-    <para>We will document the new ACL module more fully with a subsequent
-        release. Please note that the new ACL module should be considered a
-        preview only (ie do not use in production without proper prior
-        testing), and there is a small chance there may be changes between
-        1.0.3 and 1.1.0 when it will become final. Nevertheless,
-        compatibility-affecting changes are considered quite unlikely,
-        especially given the module is already based on several years of
-        feedback from users of the original ACL module.</para>
-</section>
+        <para>We will document the new ACL module more fully with a subsequent
+            release. Please note that the new ACL module should be considered a
+            preview only (ie do not use in production without proper prior
+            testing), and there is a small chance there may be changes between
+            1.0.3 and 1.1.0 when it will become final. Nevertheless,
+            compatibility-affecting changes are considered quite unlikely,
+            especially given the module is already based on several years of
+            feedback from users of the original ACL module.</para>
+    </section>
 </chapter>

src/docbkx/form-authentication.xml

@@ -1,36 +1,33 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-
-<chapter id="form">
-    <title>Form Authentication Mechanism</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="form"><info><title>Form Authentication Mechanism</title></info>
     
-    <sect1 id="form-overview">
-        <title>Overview</title>
+    
+    <section xml:id="form-overview">
+        <info><title>Overview</title></info>
+        
         
         <para>HTTP Form Authentication involves using the
             <literal>AuthenticationProcessingFilter</literal> to process a login
             form. This is the most common way that application authenticate end
             users. Form-based authentication is entirely compatible with the DAO
             and JAAS authentication providers.</para>
-    </sect1>
+    </section>
     
-    <sect1 id="form-config">
-        <title>Configuration</title>
+    <section xml:id="form-config"><info><title>Configuration</title></info>
+        
         
         <para>The login form simply contains <literal>j_username</literal> and
             <literal>j_password</literal> input fields, and posts to a URL that is
             monitored by the filter (by default
             <literal>j_spring_security_check</literal>). You should add an 
             <literal>AuthenticationProcessingFilter</literal> to you application context:
-            <programlisting><![CDATA[             
-    <bean id="authenticationProcessingFilter"
-            class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter">
-        <property name="authenticationManager" ref="authenticationManager"/>
-        <property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/>
-        <property name="defaultTargetUrl" value="/"/>
-        <property name="filterProcessesUrl" value="/j_spring_security_check"/>
-    </bean> ]]>        
+            <programlisting>             
+    &lt;bean id="authenticationProcessingFilter"
+            class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter"&gt;
+        &lt;property name="authenticationManager" ref="authenticationManager"/&gt;
+        &lt;property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/&gt;
+        &lt;property name="defaultTargetUrl" value="/"/&gt;
+        &lt;property name="filterProcessesUrl" value="/j_spring_security_check"/&gt;
+    &lt;/bean&gt;         
             </programlisting></para>
         
         <para>The configured <literal>AuthenticationManager</literal>
@@ -58,5 +55,5 @@
             If for some reason the <literal>HttpSession</literal> does not
             indicate the target URL, the browser will be redirected to the
             <literal>defaultTargetUrl</literal> property.</para>
-    </sect1>
+    </section>
 </chapter>

src/docbkx/introduction.xml

@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
 
-<chapter id="introduction">
+<chapter version="5.0" xml:id="introduction"
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
     
 <title>Introduction</title>
 
-<sect1 id="what-is-acegi-security">
+<sect1 xml:id="what-is-acegi-security">
     <title>What is Spring Security?</title>
     
     <para>Spring Security provides comprehensive security services for
@@ -173,8 +173,8 @@
         </listitem>
     </itemizedlist>
     
-    <para>(* Denotes provided by a third party; check our <ulink
-        url="http://acegisecurity.org/powering.html">integration page</ulink>
+    <para>(* Denotes provided by a third party; check our <link
+        xlink:href="http://acegisecurity.org/powering.html">integration page</link>
         for links to the latest details)</para>
     
     <para>Many independent software vendors (ISVs) adopt Spring Security
@@ -214,7 +214,7 @@
         which we'll explore later in this reference guide.</para>
 </sect1>
 
-<sect1 id="history">
+<sect1 xml:id="history">
     <title>History</title>
     
     <para>Spring Security began in late 2003 as "The Acegi Security System
@@ -261,7 +261,7 @@
         peers.</para>
 </sect1>
 
-<sect1 id="release-numbering">
+<sect1 xml:id="release-numbering">
     <title>Release Numbering</title>
     
     <para>It is useful to understand how Spring Security release numbers

src/docbkx/jaas-auth-provider.xml

@@ -1,12 +1,9 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-<chapter id="jaas">
-    <title>Java Authentication and Authorization Service (JAAS)
-        Provider</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="jaas"><info><title>Java Authentication and Authorization Service (JAAS)
+        Provider</title></info>
     
-    <sect1 id="jaas-overview">
-        <title>Overview</title>
+    
+    <section xml:id="jaas-overview"><info><title>Overview</title></info>
+        
         
         <para>Spring Security provides a package able to delegate
             authentication requests to the Java Authentication and Authorization
@@ -17,10 +14,10 @@
             reference documentation available from Sun Microsystems. We expect you
             to have a basic understanding of JAAS and its login configuration file
             syntax in order to understand this section.</para>
-    </sect1>
+    </section>
     
-    <sect1 id="jaas-config">
-        <title>Configuration</title>
+    <section xml:id="jaas-config"><info><title>Configuration</title></info>
+        
         
         <para>The <literal>JaasAuthenticationProvider</literal> attempts to
             authenticate a user’s principal and credentials through JAAS.</para>
@@ -39,34 +36,34 @@
             above JAAS login configuration file:</para>
         
         <para><programlisting>
-            <![CDATA[ &lt;bean id="jaasAuthenticationProvider"
-            class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&gt;
-  &lt;property name="loginConfig"&gt;
-    &lt;value&gt;/WEB-INF/login.conf&lt;/value&gt;
-  &lt;/property&gt;
-  &lt;property name="loginContextName"&gt;
-    &lt;value&gt;JAASTest&lt;/value&gt;
-  &lt;/property&gt;
-  &lt;property name="callbackHandlers"&gt;
-    &lt;list&gt;
-      &lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&gt;
-      &lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-  &lt;property name="authorityGranters"&gt;
-    &lt;list&gt;
-      &lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&gt;
-    &lt;/list&gt;
-  &lt;/property&gt;
-&lt;/bean&gt; ]]>
+             &amp;lt;bean id="jaasAuthenticationProvider"
+            class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&amp;gt;
+  &amp;lt;property name="loginConfig"&amp;gt;
+    &amp;lt;value&amp;gt;/WEB-INF/login.conf&amp;lt;/value&amp;gt;
+  &amp;lt;/property&amp;gt;
+  &amp;lt;property name="loginContextName"&amp;gt;
+    &amp;lt;value&amp;gt;JAASTest&amp;lt;/value&amp;gt;
+  &amp;lt;/property&amp;gt;
+  &amp;lt;property name="callbackHandlers"&amp;gt;
+    &amp;lt;list&amp;gt;
+      &amp;lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&amp;gt;
+      &amp;lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&amp;gt;
+    &amp;lt;/list&amp;gt;
+  &amp;lt;/property&amp;gt;
+  &amp;lt;property name="authorityGranters"&amp;gt;
+    &amp;lt;list&amp;gt;
+      &amp;lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&amp;gt;
+    &amp;lt;/list&amp;gt;
+  &amp;lt;/property&amp;gt;
+&amp;lt;/bean&amp;gt; 
 
         </programlisting></para>
         
         <para>The <literal>CallbackHandler</literal>s and
             <literal>AuthorityGranter</literal>s are discussed below.</para>
         
-        <sect2 id="jaas-callbackhandler">
-            <title id="jaas-callback-handler">JAAS CallbackHandler</title>
+        <section xml:id="jaas-callbackhandler"><info><title xml:id="jaas-callback-handler">JAAS CallbackHandler</title></info>
+            
             
             <para>Most JAAS <literal>LoginModule</literal>s require a callback
                 of some sort. These callbacks are usually used to obtain the
@@ -103,10 +100,10 @@
                 <literal>InternalCallbackHandler</literal>s, the callback is in-turn
                 passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
                 being wrapped.</para>
-        </sect2>
+        </section>
         
-        <sect2 id="jaas-authoritygranter">
-            <title id="jaas-authority-granter">JAAS AuthorityGranter</title>
+        <section xml:id="jaas-authoritygranter"><info><title xml:id="jaas-authority-granter">JAAS AuthorityGranter</title></info>
+            
             
             <para>JAAS works with principals. Even "roles" are represented as
                 principals in JAAS. Spring Security, on the other hand, works with
@@ -142,6 +139,6 @@
                 <literal>TestAuthorityGranter</literal> in the unit tests that
                 demonstrates a simple <literal>AuthorityGranter</literal>
                 implementation.</para>
-        </sect2>
-    </sect1>
+        </section>
+    </section>
 </chapter>

src/docbkx/ldap-auth-provider.xml

@@ -1,10 +1,7 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-<chapter id="ldap">
-    <title>LDAP Authentication</title>
-    <sect1 id="ldap-overview">
-        <title>Overview</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ldap"><info><title>LDAP Authentication</title></info>
+    
+    <section xml:id="ldap-overview"><info><title>Overview</title></info>
+        
         <para>LDAP is often used by organizations as a central repository for user information and
             as an authentication service. It can also be used to store the role information for
             application users.</para>
@@ -14,17 +11,16 @@
             configured to handle a wide range of situations.</para>
         <para>You should be familiar with LDAP before trying to use it with Spring Security. The
             following link provides a good introduction to the concepts involved and a guide to
-            setting up a directory using the free LDAP server OpenLDAP: <ulink
-                url="http://www.zytrax.com/books/ldap/"/>. Some familiarity with the JNDI APIs used
+            setting up a directory using the free LDAP server OpenLDAP: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.zytrax.com/books/ldap/">http://www.zytrax.com/books/ldap/</uri>. Some familiarity with the JNDI APIs used
             to access LDAP from Java may also be useful. We don't use any third-party LDAP libraries
             (Mozilla, JLDAP etc.) in the LDAP provider, but extensive use is made of Spring LDAP, so
             some familiarity with that project may be useful if you plan on adding your own
             customizations.</para>
-    </sect1>
-    <sect1>
-        <title>Using LDAP with Spring Security</title>
+    </section>
+    <section><info><title>Using LDAP with Spring Security</title></info>
+        
         <para> LDAP authentication in Spring Security can be roughly divided into the following
-            stages. <orderedlist>
+            stages. <orderedlist inheritnum="ignore" continuation="restarts">
                 <listitem>
                     <para>Obtaining the unique LDAP <quote>Distinguished Name</quote>, or DN, from
                         the login name. This will often mean performing a search in the directory,
@@ -45,57 +41,56 @@
         <para> We will look at some configuration scenarios below. For full information on available
             configuration options, please consult the security namespace schema (information from
             which should be available in your XML editor). </para>
-    </sect1>
-    <sect1>
-        <title>Configuring an LDAP Server</title>
+    </section>
+    <section><info><title>Configuring an LDAP Server</title></info>
+        
         <para> The first thing you need to do is configure the server against which authentication
             should take place. This is done using the <literal>&lt;ldap-server&gt;</literal> element
             from the security namespace. This can be configured to point at an external LDAP server,
-            using the <literal>url</literal> attribute: <programlisting><![CDATA[ 
-    <ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" /> 
-            ]]></programlisting></para>
-        <sect2>
-            <title>Using an Embedded Test Server</title>
+            using the <literal>url</literal> attribute: <programlisting> 
+    &lt;ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" /&gt; 
+            </programlisting></para>
+        <section><info><title>Using an Embedded Test Server</title></info>
+            
             <para> The <literal>&lt;ldap-server&gt;</literal> element can also be used to create an
                 embedded server, which can be very useful for testing and demonstrations. In this
-                case you use it without the <literal>url</literal> attribute: <programlisting><![CDATA[ 
-    <ldap-server root="dc=springframework,dc=org"/> 
-    ]]></programlisting> Here we've specified that the root DIT of the directory should be
+                case you use it without the <literal>url</literal> attribute: <programlisting> 
+    &lt;ldap-server root="dc=springframework,dc=org"/&gt; 
+    </programlisting> Here we've specified that the root DIT of the directory should be
                     <quote>dc=springframework,dc=org</quote>, which is the default. Used this way,
                 the namespace parser will create an embedded Apache Directory server and scan the
                 classpath for any LDIF files, which it will attempt to load into the server. You can
                 customize this behaviour using the <literal>ldif</literal> attribute, which defines
-                an LDIF resource to be loaded: <programlisting><![CDATA[ 
-    <ldap-server ldif="classpath:users.ldif" /> 
-    ]]></programlisting> This makes it a lot easier to get up and running with LDAP, since it can be
+                an LDIF resource to be loaded: <programlisting> 
+    &lt;ldap-server ldif="classpath:users.ldif" /&gt; 
+    </programlisting> This makes it a lot easier to get up and running with LDAP, since it can be
                 inconvenient to work all the time with an external server. It also insulates the
                 user from the complex bean configuration needed to wire up an Apache Directory
                 server. Using plain Spring Beans the configuration would be much more cluttered. You
                 must have the necessary Apache Directory dependency jars available for your
-                application to use. These can be obtained from the <olink targetdoc="sample-apps"
-                    targetptr="ldap">LDAP sample application</olink>. </para>
-        </sect2>
-        <sect2>
-            <title>Using Bind Authentication</title>
+                application to use. These can be obtained from the LDAP sample application. </para>
+        </section>
+        <section><info><title>Using Bind Authentication</title></info>
+            
             <para> This is the most common LDAP authentication scenario. <programlisting>
-                    <![CDATA[ 
-    <ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/> 
-                    ]]></programlisting> This simple example would obtain the DN for the user by
+                     
+    &lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/&gt; 
+                    </programlisting> This simple example would obtain the DN for the user by
                 substituting the user login name in the supplied pattern and attempting to bind as
                 that user with the login password. This is OK if all your users are stored under a
                 single node in the directory. If instead you wished to configure an LDAP search
                 filter to locate the user, you could use the following: <programlisting>
-                    <![CDATA[ 
-    <ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/>
-                    ]]></programlisting> If used with the server definition above, this would
+                     
+    &lt;ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/&gt;
+                    </programlisting> If used with the server definition above, this would
                 perform a search under the DN <literal>ou=people,dc=springframework,dc=org</literal>
                 using the value of the <literal>user-search-filter</literal> attribute as a filter.
                 Again the user login name is substituted for the parameter in the filter name. If
                     <literal>user-search-base</literal> isn't supplied, the search will be performed
                 from the root. </para>
-        </sect2>
-        <sect2>
-            <title>Loading Authorities</title>
+        </section>
+        <section><info><title>Loading Authorities</title></info>
+            
             <para> How authorities are loaded from groups in the LDAP directory is controlled by the
                 following attributes. <itemizedlist>
                     <listitem>
@@ -109,27 +104,24 @@
                     </listitem>
                     <listitem>
                         <para><literal>group-search-filter</literal>. The filter which is used to
-                            search for group membership. The default is <literal
-                            >uniqueMember={0}</literal>, corresponding to the <literal
-                                >groupOfUniqueMembers</literal> LDAP class. In this case, the
+                            search for group membership. The default is <literal>uniqueMember={0}</literal>, corresponding to the <literal>groupOfUniqueMembers</literal> LDAP class. In this case, the
                             substituted parameter is the full distinguished name of the user. The
                             parameter <literal>{1}</literal> can be used if you want to filter on
                             the login name.</para>
                     </listitem>
                 </itemizedlist> So if we used the following configuration <programlisting>
-            <![CDATA[ 
-    <ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" />
-                    ]]></programlisting> and authenticated successfully as user <quote>ben</quote>,
+             
+    &lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" /&gt;
+                    </programlisting> and authenticated successfully as user <quote>ben</quote>,
                 the subsequent loading of authorities would perform a search under the directory
                 entry <literal>ou=groups,dc=springframework,dc=org</literal>, looking for entries
-                which contain the attribute <literal>uniqueMember</literal> with value <literal
-                    >uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information on
+                which contain the attribute <literal>uniqueMember</literal> with value <literal>uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information on
                 loading authorities, see the Javadoc for the
                     <classname>DefaultLdapAuthoritiesPopulator</classname> class. </para>
-        </sect2>
-    </sect1>
-    <sect1>
-        <title>Implementation Classes</title>
+        </section>
+    </section>
+    <section><info><title>Implementation Classes</title></info>
+        
         <para>The namespace configuration options we've used above are simple to use and much more
             concise than using Spring beans explicitly. There are situations when you may need to
             know how to configure Spring Security LDAP directly in your application context. You may
@@ -146,8 +138,8 @@
                 <interfacename>LdapAuthoritiesPopulator</interfacename> which are responsible for
             authenticating the user and retrieving the user's set of
             <interfacename>GrantedAuthority</interfacename>s respectively.</para>
-        <sect2 id="ldap-ldap-authenticators">
-            <title>LdapAuthenticator Implementations</title>
+        <section xml:id="ldap-ldap-authenticators"><info><title>LdapAuthenticator Implementations</title></info>
+            
             <para>The authenticator is also responsible for retrieving any required user attributes.
                 This is because the permissions on the attributes may depend on the type of
                 authentication being used. For example, if binding as the user, it may be necessary
@@ -166,8 +158,8 @@
                             value is never retrieved.</para>
                     </listitem>
                 </itemizedlist></para>
-            <sect3 id="ldap-ldap-authenticators-common">
-                <title>Common Functionality</title>
+            <section xml:id="ldap-ldap-authenticators-common"><info><title>Common Functionality</title></info>
+                
                 <para>Before it is possible to authenticate a user (by either strategy), the
                     distinguished name (DN) has to be obtained from the login name supplied to the
                     application. This can be done either by simple pattern-matching (by setting the
@@ -181,35 +173,34 @@
                     server</link> for more information on this). For example, if you are using an
                     LDAP server with the URL <literal>ldap://monkeymachine.co.uk/dc=springframework,dc=org</literal>, and have a
                     pattern <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla"
-                    will map to a DN <literal
-                    >uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured
+                    will map to a DN <literal>uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured
                     DN pattern will be tried in turn until a match is found. For information on
                     using a search, see the section on <link linkend="ldap-searchobjects">search
                         objects</link> below. A combination of the two approaches can also be used -
                     the patterns will be checked first and if no matching DN is found, the search
                     will be used.</para>
-            </sect3>
-            <sect3 id="ldap-ldap-authenticators-bind">
-                <title>BindAuthenticator</title>
+            </section>
+            <section xml:id="ldap-ldap-authenticators-bind"><info><title>BindAuthenticator</title></info>
+                
                 <para>The class
                         <classname>org.springframework.security.providers.ldap.authenticator.BindAuthenticator</classname>
                     implements the bind authentication strategy. It simply attempts to bind as the
                     user.</para>
-            </sect3>
-            <sect3 id="ldap-ldap-authenticators-password">
-                <title>PasswordComparisonAuthenticator</title>
+            </section>
+            <section xml:id="ldap-ldap-authenticators-password"><info><title>PasswordComparisonAuthenticator</title></info>
+                
                 <para>The class
                         <classname>org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
                     implements the password comparison authentication strategy.</para>
-            </sect3>
-            <sect3 id="ldap-ldap-authenticators-active-directory">
-                <title>Active Directory Authentication</title>
+            </section>
+            <section xml:id="ldap-ldap-authenticators-active-directory"><info><title>Active Directory Authentication</title></info>
+                
                 <para>In addition to standard LDAP authentication (binding with a DN), Active
                     Directory has its own non-standard syntax for user authentication.</para>
-            </sect3>
-        </sect2>
-        <sect2 id="ldap-context-source">
-            <title>Connecting to the LDAP Server</title>
+            </section>
+        </section>
+        <section xml:id="ldap-context-source"><info><title>Connecting to the LDAP Server</title></info>
+            
             <para>The beans discussed above have to be able to connect to the server. They both have
                 to be supplied with a <interfacename>SpringSecurityContextSource</interfacename>
                 which is an extension of Spring LDAP's <interfacename>ContextSource</interfacename>. 
@@ -220,59 +211,54 @@
                 server (instead of binding anonymously). For more information read the Javadoc for 
                 this class and for Spring LDAP's <classname>AbstractContextSource</classname>.
             </para>
-        </sect2>
-        <sect2 id="ldap-searchobjects">
-            <title>LDAP Search Objects</title>
+        </section>
+        <section xml:id="ldap-searchobjects"><info><title>LDAP Search Objects</title></info>
+            
             <para>Often more a more complicated strategy than simple DN-matching is required to
                 locate a user entry in the directory. This can be encapsulated in an
                     <interfacename>LdapUserSearch</interfacename> instance which can be supplied to
                 the authenticator implementations, for example, to allow them to locate a user. The
                 supplied implementation is <classname>FilterBasedLdapUserSearch</classname>.</para>
-            <sect3 id="ldap-searchobjects-filter">
-                <title id="ldap-searchobjects-filter-based"
-                    ><classname>FilterBasedLdapUserSearch</classname></title>
+            <section xml:id="ldap-searchobjects-filter"><info><title xml:id="ldap-searchobjects-filter-based"><classname>FilterBasedLdapUserSearch</classname></title></info>
+                
                 <para>This bean uses an LDAP filter to match the user object in the directory. The
                     process is explained in the Javadoc for the corresponding search method on the
-                        <ulink
-                        url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)"
-                        >JDK DirContext class</ulink>. As explained there, the search filter can be
-                    supplied with parameters. For this class, the only valid parameter is <parameter
-                        >{0}</parameter> which will be replaced with the user's login name.</para>
-            </sect3>
-        </sect2>
-        <sect2 id="ldap-bean-config">
-            <title>Spring Bean Configuration</title>
+                        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)">JDK DirContext class</link>. As explained there, the search filter can be
+                    supplied with parameters. For this class, the only valid parameter is <parameter>{0}</parameter> which will be replaced with the user's login name.</para>
+            </section>
+        </section>
+        <section xml:id="ldap-bean-config"><info><title>Spring Bean Configuration</title></info>
+            
             <para>A typical configuration, using some of the beans we've discussed here, might look
                 like this: <programlisting>            
-                    <![CDATA[                 
-<bean id="contextSource"
-        class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
-    <constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/>
-    <property name="userDn" value="cn=manager,dc=springframework,dc=org"/>
-    <property name="password" value="password"/>
-</bean>
+                                     
+&lt;bean id="contextSource"
+        class="org.springframework.security.ldap.DefaultSpringSecurityContextSource"&gt;
+    &lt;constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/&gt;
+    &lt;property name="userDn" value="cn=manager,dc=springframework,dc=org"/&gt;
+    &lt;property name="password" value="password"/&gt;
+&lt;/bean&gt;
 
-<bean id="ldapAuthProvider"
-        class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">
-    <constructor-arg>
-        <bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">
-            <constructor-arg ref="contextSource"/>
-            <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property>
-        </bean>
-    </constructor-arg>
-    <constructor-arg>
-        <bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator">
-            <constructor-arg ref="contextSource"/>
-            <constructor-arg value="ou=groups"/>
-            <property name="groupRoleAttribute" value="ou"/>
-        </bean>
-    </constructor-arg>
-</bean>
-]]>              
+&lt;bean id="ldapAuthProvider"
+        class="org.springframework.security.providers.ldap.LdapAuthenticationProvider"&gt;
+    &lt;constructor-arg&gt;
+        &lt;bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator"&gt;
+            &lt;constructor-arg ref="contextSource"/&gt;
+            &lt;property name="userDnPatterns"&gt;&lt;list&gt;&lt;value&gt;uid={0},ou=people&lt;/value&gt;&lt;/list&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+    &lt;/constructor-arg&gt;
+    &lt;constructor-arg&gt;
+        &lt;bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator"&gt;
+            &lt;constructor-arg ref="contextSource"/&gt;
+            &lt;constructor-arg value="ou=groups"/&gt;
+            &lt;property name="groupRoleAttribute" value="ou"/&gt;
+        &lt;/bean&gt;
+    &lt;/constructor-arg&gt;
+&lt;/bean&gt;
+              
                 </programlisting> This would set up the provider to access an LDAP server with URL
                 <literal>ldap://monkeymachine:389/dc=springframework,dc=org</literal>.
-                Authentication will be performed by attempting to bind with the DN <literal
-                    >uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After
+                Authentication will be performed by attempting to bind with the DN <literal>uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After
                 successful authentication, roles will be assigned to the user by searching under the DN
                 <literal>ou=groups,dc=springframework,dc=org</literal> with the default filter
                 <literal>(member=&lt;user's-DN&gt;)</literal>. The role name will be taken from the
@@ -280,18 +266,18 @@
             <para>To configurae a user search object, which uses the filter
                 <literal>(uid=&lt;user-login-name&gt;)</literal> for use instead of the
                 DN-pattern (or in addition to it), you would configure the following bean
-                <programlisting><![CDATA[
-<bean id="userSearch"
-    class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
-    <constructor-arg index="0" value=""/>
-    <constructor-arg index="1" value="(uid={0})"/>
-    <constructor-arg index="2" ref="contextSource" />
-    <property name="searchSubtree" value="true"/>
-</bean> ]]>                    
+                <programlisting>
+&lt;bean id="userSearch"
+    class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"&gt;
+    &lt;constructor-arg index="0" value=""/&gt;
+    &lt;constructor-arg index="1" value="(uid={0})"/&gt;
+    &lt;constructor-arg index="2" ref="contextSource" /&gt;
+    &lt;property name="searchSubtree" value="true"/&gt;
+&lt;/bean&gt;                     
                 </programlisting>                
                and use it by setting the authenticator's <property>userSearch</property> property. The authenticator 
                 would then call the search object to obtain the correct user's DN before attempting to bind as this user.</para>
-        </sect2>
-    </sect1>
+        </section>
+    </section>
 
-</chapter>
+</chapter>

src/docbkx/remember-me-authentication.xml

@@ -1,12 +1,9 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">  
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="remember-me"><info><title>Remember-Me Authentication</title></info>
 
-<chapter id="remember-me">
-<title>Remember-Me Authentication</title>
 
-<sect1 id="remember-me-overview">
-    <title>Overview</title>
+<section xml:id="remember-me-overview">
+    <info><title>Overview</title></info>
+    
     
     <para>Remember-me authentication refers to web sites being able to
         remember the identity of a principal between sessions. This is
@@ -16,10 +13,10 @@
         that such operations can take place, along with providing a concrete
         implementation that uses hashing to preserve the security of
         cookie-based tokens.</para>
-</sect1>
+</section>
 
-<sect1 id="remember-me-config">
-    <title>Configuration</title>
+<section xml:id="remember-me-config"><info><title>Configuration</title></info>
+    
     
     <para>Remember-me authentication is not used with basic
         authentication, given it is often not used with
@@ -117,5 +114,5 @@
         a call to <literal>RememberMeProcessingFilter</literal> into your
         <literal>FilterChainProxy</literal> (typically immediately after your
         <literal>AuthenticationProcessingFilter</literal>)</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/runas-auth-provider.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
-
-<chapter id="runas">
-    <title>Run-As Authentication Replacement</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="runas"><info><title>Run-As Authentication Replacement</title></info>
     
-    <sect1 id="runas-overview">
-        <title>Overview</title>
+    
+    <section xml:id="runas-overview"><info><title>Overview</title></info>
+        
         
         <para>The <literal>AbstractSecurityInterceptor</literal> is able to
             temporarily replace the <literal>Authentication</literal> object in
@@ -30,10 +26,10 @@
             remoting protocols based on the contents of the
             <literal>SecurityContextHolder</literal>, these run-as replacements
             are particularly useful when calling remote web services</para>
-    </sect1>
+    </section>
     
-    <sect1 id="runas-config">
-        <title>Configuration</title>
+    <section xml:id="runas-config"><info><title>Configuration</title></info>
+        
         
         <para>A <literal>RunAsManager</literal> interface is provided by Acegi
             Security:</para>
@@ -107,5 +103,5 @@
             <literal>RunAsManagerImpl</literal>. The
             <literal>RunAsUserToken</literal> is immutable after creation for
             security reasons</para>
-    </sect1>
+    </section>
 </chapter>

src/docbkx/samples.xml

@@ -1,12 +1,11 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sample-apps">
+    
+<info><title xml:id="samples">Sample Applications</title></info>
 
-<chapter id="sample-apps">
-<title id="samples">Sample Applications</title>
 
-<sect1 id="contacts-sample">
-    <title id="contacts">Contacts</title>
+<section xml:id="contacts-sample">
+    <info><title xml:id="contacts">Contacts</title></info>
+    
     
     <para>Included with Spring Security is a very simple application that
         can demonstrate the basic security facilities provided by the system
@@ -22,7 +21,7 @@
         <literal>spring-security-sample-contacts-cas.war</literal> is designed
         to work with a JA-SIG CAS server. If you're just wanting to see how
         the sample application works, please use
-        <literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
+        <literal>spring-security-sample-contacts-filter.war</literal>
         as it does not require special configuration of your container. This
         is also the artifact included in official release ZIPs.</para>
     
@@ -82,7 +81,7 @@
         <literal>MethodSecurityInterceptor</literal> is securing the business
         objects. If you're using or
         <literal>spring-security-sample-contacts-cas.war</literal>, the
-        <literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
+        <literal>spring-security-sample-contacts-filter.war</literal>
         <literal>FilterSecurityInterceptor</literal> is also securing the HTTP
         requests. If using either of these WARs, be sure to try visiting
         <literal>http://localhost:8080/contacts/secure/super</literal>, which
@@ -104,10 +103,10 @@
         and the password to use. Note that you may need to edit
         <literal>client.properties</literal> to use a different target
         URL.</para>
-</sect1>
+</section>
 
-<sect1 id="tutorial-sample">
-    <title>Tutorial Sample</title>
+<section xml:id="tutorial-sample"><info><title>Tutorial Sample</title></info>
+    
     
     <para>Whilst the <link linkend="contacts-sample">Contacts
         Sample</link> is quite advanced in that it illustrates the more
@@ -117,36 +116,33 @@
     
     <para>The compiled tutorial is included in the distribution ZIP file,
         ready to be deployed into your web container. Authentication is
-        handled by the <link linkend="dao-provider">DaoAuthenticationProvider</link>, using the
-        <link linkend="in-memory-service">in-memory</link>
+        handled by the <link xlink:href="dao-auth-provider.xml">DaoAuthenticationProvider</link>, using the
+        <link xlink:href="in-memory-service">in-memory</link>
         <literal>UserDetailsService</literal> that sources information from
         the <literal>users.properties</literal> file located in the WAR's
-        <literal>/WEB-INF</literal> directory. The <link linkend="form">form-based</link> 
+        <literal>/WEB-INF</literal> directory. The <link xlink:href="form-authentication.xml">form-based</link> 
         authentication mechanism is used, with the commonly-used 
-        <link linkend="remember-me">remember-me</link>
+        <link xlink:href="#remember-me">remember-me</link>
         authentication provider used to automatically remember the login using
         cookies.</para>
     
     <para>In terms of authorization, to keep things simple we've
-        configured the tutorial to only perform some basic <link
-            linkend="filter-invocation-authorization">web filter
-            authorization</link>. We've wired two common <link
-                linkend="pre-invocation">pre-invocation access decision voters</link>,
+        configured the tutorial to only perform some basic <link xlink:href="#filter-invocation-authorization">web filter
+            authorization</link>. We've wired two common <link xlink:href="#pre-invocation">pre-invocation access decision voters</link>,
         being the <literal>RoleVoter</literal> and
         <literal>AuthenticatedVoter</literal>, such that
         <literal>ROLE_*</literal> configuration attributes and
         <literal>IS_AUTHENTICATED_*</literal> configuration attributes may be
         used. Of course, it's extremely easy to add in other providers, with
         most users probably starting with some services-layer security using
-        <link linkend="aop-alliance">MethodSecurityInterceptor</link>.</para>
+        <link xlink:href="#aop-alliance">MethodSecurityInterceptor</link>.</para>
     
     <para>We recommend you start with the tutorial sample, as the XML is
-        minimal and easy to follow. All of the needed <link
-            linkend="filters">filters</link> are configured properly, and using
+        minimal and easy to follow. All of the needed <link xlink:href="#supporting-infrastructure">filters</link> are configured properly, and using
         best practise. Most importantly, you can easily this one XML file (and
         its corresponding <literal>web.xml</literal> entries) to your existing
         application. Only when this basic integration is achieved do we
         suggest you attempt adding in method authorization or domain object
         security.</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/secured-objects.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="secure-object-impls"><info><title>Secure Object Implementations</title></info>
+  
 
-<chapter id="secure-object-impls">
-  <title>Secure Object Implementations</title>
-
-  <sect1 id="aop-alliance">
-    <title>AOP Alliance (MethodInvocation) Security Interceptor</title>
+  <section xml:id="aop-alliance"><info><title>AOP Alliance (MethodInvocation) Security Interceptor</title></info>
+    
 
     <para>To secure <literal>MethodInvocation</literal>s, developers
     simply add a properly configured
@@ -215,10 +211,10 @@ public float getBalance(int id);
 &lt;/property&gt;
 &lt;property name="proxyTargetClass" value="true"/&gt;
 &lt;/bean&gt;        </programlisting>
-  </sect1>
+  </section>
 
-  <sect1 id="aspectj">
-    <title>AspectJ (JoinPoint) Security Interceptor</title>
+  <section xml:id="aspectj"><info><title>AspectJ (JoinPoint) Security Interceptor</title></info>
+    
 
     <para>The AspectJ security interceptor is very similar to the AOP
     Alliance security interceptor discussed in the previous section.
@@ -338,10 +334,10 @@ if (this.securityInterceptor == null)
     your application, using whatever means you think fit (eg <literal>new
     Person();</literal>) and they will have the security interceptor
     applied.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="filter-invocation-authorization">
-    <title>FilterInvocation Security Interceptor</title>
+  <section xml:id="filter-invocation-authorization"><info><title>FilterInvocation Security Interceptor</title></info>
+    
 
       <para>To secure <classname>FilterInvocation</classname>s, developers need
     to add a <literal>FilterSecurityInterceptor</literal> to their filter chain. 
@@ -350,30 +346,30 @@ if (this.securityInterceptor == null)
     <para>In the application context you will need to configure three
     beans:</para>
 
-    <programlisting><![CDATA[ 
-<bean id="exceptionTranslationFilter"
-        class="org.springframework.security.ui.ExceptionTranslationFilter">
-    <property name="authenticationEntryPoint"><ref local="authenticationEntryPoint"/></property>
-</bean>
-
-<bean id="authenticationEntryPoint"
-        class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint">
-    <property name="loginFormUrl"><value>/acegilogin.jsp</value></property>
-    <property name="forceHttps"><value>false</value></property>
-</bean>
-
-<bean id="filterSecurityInterceptor"
-        class="org.springframework.security.intercept.web.FilterSecurityInterceptor">
-    <property name="authenticationManager"><ref bean="authenticationManager"/></property>
-    <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
-    <property name="objectDefinitionSource">
-    <property name="filterInvocationDefinitionSource">
-        <security:filter-invocation-definition-source path-type="regex">
-            <security:intercept-url pattern="\A/secure/super/.*\Z" access="ROLE_WE_DONT_HAVE"/>
-            <security:intercept-url pattern="\A/secure/.*\" access="ROLE_SUPERVISOR,ROLE_TELLER"/>
-        </security:filter-invocation-definition-source>                
-    </property>
-</bean> ]]>        </programlisting>
+    <programlisting> 
+&lt;bean id="exceptionTranslationFilter"
+        class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
+    &lt;property name="authenticationEntryPoint"&gt;&lt;ref local="authenticationEntryPoint"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="authenticationEntryPoint"
+        class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
+    &lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="filterSecurityInterceptor"
+        class="org.springframework.security.intercept.web.FilterSecurityInterceptor"&gt;
+    &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+    &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+    &lt;property name="objectDefinitionSource"&gt;
+    &lt;property name="filterInvocationDefinitionSource"&gt;
+        &lt;security:filter-invocation-definition-source path-type="regex"&gt;
+            &lt;security:intercept-url pattern="\A/secure/super/.*\Z" access="ROLE_WE_DONT_HAVE"/&gt;
+            &lt;security:intercept-url pattern="\A/secure/.*\" access="ROLE_SUPERVISOR,ROLE_TELLER"/&gt;
+        &lt;/security:filter-invocation-definition-source&gt;                
+    &lt;/property&gt;
+&lt;/bean&gt;         </programlisting>
 
     <para>The <classname>ExceptionTranslationFilter</classname> provides
     the bridge between Java exceptions and HTTP responses. It is solely
@@ -496,5 +492,5 @@ if (this.securityInterceptor == null)
     <literal>AccessDecisionManager</literal> or the
     <literal>RunAsManager</literal>. If neither of these can process a
     given configuration attribute, an exception is thrown.</para>
-  </sect1>
+  </section>
 </chapter>

src/docbkx/siteminder-auth-provider.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="siteminder"><info><title>Siteminder Authentication Mechanism</title></info>
 
-<chapter id="siteminder">
-<title>Siteminder Authentication Mechanism</title>
 
-<sect1 id="siteminder-overview">
-    <title>Overview</title>
+<section xml:id="siteminder-overview"><info><title>Overview</title></info>
+    
     
     <para>Siteminder is a commercial single sign on solution by Computer
         Associates.</para>
@@ -29,10 +25,10 @@
         identifies the authenticated principal (please refer to your
         organization's "single sign-on" group for header details in your
         particular configuration).</para>
-</sect1>
+</section>
 
-<sect1 id="siteminder-config">
-    <title>Configuration</title>
+<section xml:id="siteminder-config"><info><title>Configuration</title></info>
+    
     
     <para>The first step in setting up Spring Security's Siteminder
         support is to define the authentication mechanism that will inspect
@@ -80,5 +76,5 @@
         support form-based authentication in your development environment
         (where Siteminder is typically not installed), specify the form's
         username parameter as well. Just don't do this in production!</para>
-</sect1>
+</section>
 </chapter>

src/docbkx/springsecurity.xml

@@ -1,25 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-        "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<book xmlns:xi="http://www.w3.org/2001/XInclude">
-  <bookinfo>
-    <title>Spring Security</title>
-
-    <subtitle>Reference Documentation</subtitle>
-
-    <releaseinfo>2.0-SNAPSHOT</releaseinfo>
-
-    <authorgroup>
-      <author>
-        <firstname>Ben</firstname>
-        <surname>Alex</surname>
-      </author>
-    </authorgroup>
-  </bookinfo>
-
-  <toc></toc>
+<book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" 
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+    
+    <info>
+        <title>Spring Security</title>
+        
+        <subtitle>Reference Documentation</subtitle>
+        
+        <author>
+            <personname>Ben Alex</personname>
+        </author>
+                
+        <releaseinfo>2.0-SNAPSHOT</releaseinfo>
+        
+    </info>
+    
+  <toc/>
 
-  <preface id="preface">
+  <preface xml:id="preface">
     <title>Preface</title>
 
     <para>Spring Security provides a comprehensive security solution for
@@ -76,13 +75,13 @@
     basis.</para>
 
     <para>We hope that you find this reference guide useful, and we welcome
-    your feedback and <link linkend="jira">suggestions</link>.</para>
+      your feedback and <link xlink:href="#jira">suggestions</link>.</para>
 
-    <para>Finally, welcome to the Spring Security <link linkend="community" >community</link>.
+    <para>Finally, welcome to the Spring Security <link xlink:href="#community" >community</link>.
     </para>
   </preface>
 
-  <part id="overall-architecture">
+  <part xml:id="overall-architecture">
     <title>Overall Architecture</title>
 
     <partintro>
@@ -103,10 +102,9 @@
     <xi:include href="channel-security.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     
     <xi:include href="taglibs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- 
   </part>
 
-  <part id="authentication">
+  <part xml:id="authentication">
     <title>Authentication</title>
 
     <partintro>
@@ -122,8 +120,6 @@
     <xi:include href="dao-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>    
 
     <xi:include href="jaas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
-    
-    <xi:include href="siteminder-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
     <xi:include href="runas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     
@@ -147,7 +143,7 @@
 
   </part>
 
-  <part id="authorization">
+  <part xml:id="authorization">
     <title>Authorization</title>
 
     <partintro>
@@ -175,7 +171,7 @@
     
   </part>
 
-  <part id="resources">
+  <part xml:id="resources">
     <title>Other Resources</title>
 
     <partintro>

src/docbkx/supporting-infrastructure.xml

@@ -1,17 +1,13 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-
-<chapter id="supporting-infrastructure">
-  <title>Supporting Infrastructure</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="supporting-infrastructure"><info><title>Supporting Infrastructure</title></info>
+  
 
   <para>This chapter introduces some of the supplementary and supporting
   infrastructure used by Spring Security. If a capability is not directly
   related to security, yet included in the Spring Security project, we
   will discuss it in this chapter.</para>
 
-  <sect1 id="localization">
-    <title>Localization</title>
+  <section xml:id="localization"><info><title>Localization</title></info>
+    
 
     <para>Spring Security supports localization of exception messages that
     end users are likely to see. If your application is designed for
@@ -75,10 +71,10 @@
     <literal>CookieLocaleResolver</literal>,
     <literal>FixedLocaleResolver</literal>,
     <literal>SessionLocaleResolver</literal> etc)</para>
-  </sect1>
+  </section>
 
-  <sect1 id="filters">
-    <title>Filters</title>
+  <section xml:id="filters"><info><title>Filters</title></info>
+    
 
     <para>Spring Security uses many filters, as referred to throughout the
     remainder of this reference guide. You have a choice in how these
@@ -90,17 +86,17 @@
       something like this in the web.xml file:
       
         <programlisting>
-            <![CDATA[
-    <filter>
-        <filter-name>myFilter</filter-name>
-        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
-    </filter>
-
-    <filter-mapping>
-      <filter-name>myFilter</filter-name>
-      <url-pattern>/*</url-pattern>
-    </filter-mapping>
-             ]]>
+            
+    &lt;filter&gt;
+        &lt;filter-name&gt;myFilter&lt;/filter-name&gt;
+        &lt;filter-class&gt;org.springframework.web.filter.DelegatingFilterProxy&lt;/filter-class&gt;
+    &lt;/filter&gt;
+
+    &lt;filter-mapping&gt;
+      &lt;filter-name&gt;myFilter&lt;/filter-name&gt;
+      &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+    &lt;/filter-mapping&gt;
+             
         </programlisting>     
        
         Notice that the filter  is actually a <literal>DelegatingFilterProxy</literal>, 
@@ -149,13 +145,13 @@
     The filter chain is then declared in the application context, using
     code such as this:</para>
 
-    <para><programlisting><![CDATA[ 
-<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy">
-    <sec:filter-chain-map path-type="ant">
-        <sec:filter-chain pattern="/webServices/**" filters="httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/>
-        <sec:filter-chain pattern="/**" filters="httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/>
-    </sec:filter-chain-map>
-</bean> ]]>        </programlisting></para>
+    <para><programlisting> 
+&lt;bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy"&gt;
+    &lt;sec:filter-chain-map path-type="ant"&gt;
+        &lt;sec:filter-chain pattern="/webServices/**" filters="httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/&gt;
+        &lt;sec:filter-chain pattern="/**" filters="httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/&gt;
+    &lt;/sec:filter-chain-map&gt;
+&lt;/bean&gt;         </programlisting></para>
 
     <para>You may notice similarities with the way
     <literal>FilterSecurityInterceptor</literal> is declared. Both regular
@@ -228,7 +224,7 @@
     using, the order of the <literal>&lt;filter-mapping&gt;</literal>s
     should be as follows:</para>
 
-    <orderedlist>
+    <orderedlist inheritnum="ignore" continuation="restarts">
       <listitem>
         <para><literal>ChannelProcessingFilter</literal>, because it might
         need to redirect to a different protocol</para>
@@ -276,7 +272,7 @@
         <literal>SecurityContextHolder</literal>, and the request presents
         a cookie that enables remember-me services to take place, a
         suitable remembered
-        <literal><literal>Authentication</literal></literal> object will
+        <literal>Authentication</literal> object will
         be put there</para>
       </listitem>
 
@@ -312,5 +308,5 @@
     before the SiteMesh filters are called. This enables the
     <literal>SecurityContextHolder</literal> to be populated in time for
     use by SiteMesh decorators</para>
-  </sect1>
+  </section>
 </chapter>

src/docbkx/taglibs.xml

@@ -1,16 +1,17 @@
-<chapter id="taglib">    
-    <title>Tag Libraries</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="taglib">
+    <info><title>Tag Libraries</title></info>    
     
-    <sect1 id="taglib-overview">
-        <title>Overview</title>
+    
+    <section xml:id="taglib-overview"><info><title>Overview</title></info>
+        
         
         <para>Spring Security comes bundled with several JSP tag libraries
             that eases JSP writing. The tag libraries provide a range of different
             services.</para>
-    </sect1>
+    </section>
     
-    <sect1 id="taglib-config">
-        <title>Configuration</title>
+    <section xml:id="taglib-config"><info><title>Configuration</title></info>
+        
         
         <para>All taglib classes are included in the core
             <literal>spring-security-xx.jar</literal> file, with the
@@ -28,10 +29,10 @@
             &lt;taglib-uri&gt;http://www.springframework.org/security/tags&lt;/taglib-uri&gt;
             &lt;taglib-location&gt;/WEB-INF/security.tld&lt;/taglib-location&gt;
             &lt;/taglib&gt;       </programlisting></para>
-    </sect1>
+    </section>
     
-    <sect1 id="taglib-usage">
-        <title>Usage</title>
+    <section xml:id="taglib-usage"><info><title>Usage</title></info>
+        
         
         <para>Now that you've configured the tag libraries, refer to the
             individual reference guide sections for details on how to use them.
@@ -40,5 +41,5 @@
                 &lt;%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %&gt;
                 
             </programlisting></para>
-    </sect1>
+    </section>
 </chapter>

src/docbkx/technical-overview.xml

@@ -1,12 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">    
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="technical-overview"><info><title>Technical Overview</title></info>
+  
 
-<chapter id="technical-overview">
-  <title>Technical Overview</title>
-
-  <sect1 id="runtime-environment">
-    <title>Runtime Environment</title>
+  <section xml:id="runtime-environment"><info><title>Runtime Environment</title></info>
+    
 
     <para>Spring Security is written to execute within a standard Java 1.4
     Runtime Environment. It also supports Java 5.0, although the Java
@@ -25,10 +21,10 @@
     <para>This above design offers maximum deployment time flexibility, as
     you can simply copy your target artifact (be it a JAR, WAR or EAR)
     from one system to another and it will immediately work.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="shared-components">
-    <title>Shared Components</title>
+  <section xml:id="shared-components"><info><title>Shared Components</title></info>
+    
 
     <para>Let's explore some of the most important shared components in
     Spring Security. Components are considered "shared" if they are
@@ -223,10 +219,10 @@ String username = obj.toString();
     <para>Now that you've gained an understanding of these repeatedly-used
     components, let's take a closer look at the process of
     authentication.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="common-authentication">
-    <title>Authentication</title>
+  <section xml:id="common-authentication"><info><title>Authentication</title></info>
+    
 
     <para>As mentioned in the beginning of this reference guide, Spring
     Security can participate in many different authentication
@@ -241,7 +237,7 @@ String username = obj.toString();
     <para>Consider a typical web application's authentication
     process:</para>
 
-    <orderedlist>
+    <orderedlist inheritnum="ignore" continuation="restarts">
       <listitem>
         <para>You visit the home page, and click on a link.</para>
       </listitem>
@@ -385,10 +381,10 @@ String username = obj.toString();
     from a location, build a Spring Security-specific Authentication
     object, and put it onto the SecurityContextHolder. It's quite easy to
     do this, and it is a fully-supported integration approach.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="secure-objects">
-    <title>Secure Objects</title>
+  <section xml:id="secure-objects"><info><title>Secure Objects</title></info>
+    
 
     <para>If you're familiar with AOP, you'd be aware there are different
     types of advice available: before, after, throws and around. An around
@@ -479,15 +475,11 @@ String username = obj.toString();
 
     <para><mediaobject>
         <imageobject role="html">
-          <imagedata align="center"
-                     fileref="images/SecurityInterception.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/SecurityInterception.gif" format="GIF"/>
         </imageobject>
 
         <imageobject role="fo">
-          <imagedata align="center"
-                     fileref="images/SecurityInterception.gif"
-                     format="GIF" />
+          <imagedata align="center" fileref="images/SecurityInterception.gif" format="GIF"/>
         </imageobject>
 
         <caption>
@@ -507,10 +499,10 @@ String username = obj.toString();
     <literal>JoinPoint</literal> and web request
     <literal>FilterInterceptor</literal>) with complete
     transparency.</para>
-  </sect1>
+  </section>
 
-  <sect1 id="common-conclusion">
-    <title>Conclusion</title>
+  <section xml:id="common-conclusion"><info><title>Conclusion</title></info>
+    
 
     <para>Congratulations! You have enough of a high-level picture of
     Spring Security to embark on your project. We've explored the shared
@@ -518,5 +510,5 @@ String username = obj.toString();
     authorization concept of a "secure object". Everything that follows in
     this reference guide may or may not apply to your particular needs,
     and can be read in any order.</para>
-  </sect1>
+  </section>
 </chapter>

src/docbkx/x509-auth-provider.xml

@@ -1,10 +1,7 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-<chapter id="x509">
-    <title>X.509 Authentication</title>
-    <sect1 id="x509-overview">
-        <title>Overview</title>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="x509"><info><title>X.509 Authentication</title></info>
+    
+    <section xml:id="x509-overview"><info><title>Overview</title></info>
+        
         <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 (ie
@@ -22,25 +19,22 @@
         <para>You should be familiar with using certificates and setting up client authentication
             for your servlet container before attempting to use it with Spring 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://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html"/>. It's important that
+            you're using Tomcat then read the instructions here <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html</uri>. It's important that
             you get this working before trying it out with Spring Security</para>
-    </sect1>
-    <sect1>
-        <title>Adding X.509 Authentication to Your Web Application</title>
-        <para> Enabling X.509 client authentication is very straightforward. Just add the <literal
-                >&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting><![CDATA[
-    <http>
+    </section>
+    <section><info><title>Adding X.509 Authentication to Your Web Application</title></info>
+        
+        <para> Enabling X.509 client authentication is very straightforward. Just add the <literal>&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting>
+    &lt;http&gt;
      ...
-        <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>
+        &lt;x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/&gt;
      ...
-    </http>]]>
+    &lt;/http&gt;
             </programlisting> The element has two optional attributes: <itemizedlist>
                 <listitem>
                     <para><literal>subject-principal-regex</literal>. The regular expression used to
                         extract a username from the certificate's subject name. The default value is
-                        shown above. This is the username which will be passed to the <literal
-                            >UserDetailsService</literal> to load the authorities for the
+                        shown above. This is the username which will be passed to the <literal>UserDetailsService</literal> to load the authorities for the
                     user.</para>
                 </listitem>
                 <listitem>
@@ -59,9 +53,9 @@
             security context. If no certificate is found, or no corresponding user could be found
             then the security context will remain empty. This means that you can easily use X.509
             authentication with other options such as a form-based login. </para>
-    </sect1>
-    <sect1 id="x509-ssl-config">
-        <title>Setting up SSL in Tomcat</title>
+    </section>
+    <section xml:id="x509-ssl-config"><info><title>Setting up SSL in Tomcat</title></info>
+        
         <para>There are some pre-generated certificates in the  
             <filename>samples/certificate</filename> directory in the Spring Security project.  
             You can use these to enable SSL for testing if you don't want to generate your own. The file
@@ -74,19 +68,19 @@
             To run tomcat with SSL support, drop the <filename>server.jks</filename> file into the 
             tomcat <filename>conf</filename> directory and add the following connector to the
             <filename>server.xml</filename> file 
-                <programlisting><![CDATA[ 
-    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
+                <programlisting> 
+    &lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
                 clientAuth="true" sslProtocol="TLS" 
                 keystoreFile="${catalina.home}/conf/server.jks"
                 keystoreType="JKS" keystorePass="password"
                 truststoreFile="${catalina.home}/conf/server.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.
             Clients which don't present a certificate won't be able to access any objects secured by 
             Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication.
         </para>
-    </sect1>
-</chapter>
+    </section>
+</chapter>

src/docbkx/xml-auth-provider.xml

@@ -1,148 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
-
-<chapter id="x509">
-<title>X509 Authentication</title>
-
-<sect1 id="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. Spring 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 Spring 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 Spring 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
-        Spring Security</para>
-</sect1>
-
-<sect1 id="x509-with-acegi">
-    <title>Using X509 with Spring 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. A UserDetailsService 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>ExceptionTranslationFilter</classname> will invoke
-                    the <classname>X509ProcessingFilterEntryPoint</classname> which
-                    returns a 403 error (forbidden) to the user.</para>
-            </listitem>
-        </orderedlist></para>
-</sect1>
-
-<sect1 id="x509-config">
-    <title>Configuration</title>
-    
-    <para>There is a version of the <link
-        linkend="contacts-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>user.p12</filename>: A PKCS12 format file
-                    containing the client key and certificate. These should be
-                    installed in your browser. It maps to a use 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 the user'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 Spring
-        Security (unless you use a non-X509 authentication mechanism, such as
-        BASIC authentication, to authenticate the user)</para>
-</sect1>
-</chapter>