source: nutchez-0.1/tomcat/webapps/docs/funcspecs/fs-memory-realm.html @ 253

Last change on this file since 253 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 12.7 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - MemoryRealm</title><meta value="Craig McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      Catalina Functional Specifications
3    " align="right" src="../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default.html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Catalina Functional Specifications</h1><h2>MemoryRealm</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/fs-memory-realm.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
5
6
7  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
8
9    <p>The purpose of the <strong>MemoryRealm</strong> implementation is to
10    provide a mechanism by which Tomcat 6 can acquire information needed
11    to authenticate web application users, and define their security roles,
12    from a simple text-based configuration file in XML format.  This is
13    intended to simplify the initial installation and operation of Tomcat 6,
14    without the complexity of configuring a database or directory server
15    based Realm.  It is not intended for production use.</p>
16
17    <p>This specification reflects a combination of functionality that is
18    already present in the <code>org.apache.catalina.realm.MemoryRealm</code>
19    class, as well as requirements for enhancements that have been
20    discussed.  Where appropriate, requirements statements are marked
21    <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
22
23    <p>The current status of this functional specification is
24    <strong>PROPOSED</strong>.  It has not yet been discussed and
25    agreed to on the TOMCAT-DEV mailing list.</p>
26
27  </blockquote></td></tr></table>
28
29
30  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
31
32    <p>The implementation of this functionality depends on the following
33    external specifications:</p>
34    <ul>
35    <li>None</li>
36    </ul>
37
38  </blockquote></td></tr></table>
39
40
41  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
42
43    <p>The implementation of this functionality shall conform to the
44    following requirements:</p>
45    <ul>
46    <li>Be realized in one or more implementation classes.</li>
47    <li>Implement the <code>org.apache.catalina.Realm</code> interface.
48        [Current]</li>
49    <li>Implement the <code>org.apache.catalina.Lifecycle</code>
50        interface.  [Current]</li>
51    <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
52        base class.</li>
53    <li>Live in the <code>org.apache.catalina.realm</code> package.
54        [Current]</li>
55    <li>Support a configurable debugging detail level. [Current]</li>
56    <li>Log debugging and operational messages (suitably internationalized)
57        via the <code>getContainer().log()</code> method. [Current]</li>
58    </ul>
59
60  </blockquote></td></tr></table>
61
62
63</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
64
65
66  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
67
68    <p>The following environmental dependencies must be met in order for
69    MemoryRealm to operate correctly:</p>
70    <ul>
71    <li>The desire to utilize MemoryRealm must be registered in
72        <code>$CATALINA_BASE/conf/server.xml</code>, in a
73        <code>&lt;Realm&gt;</code> element that is nested inside a
74        corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
75        or <code>&lt;Context&gt;</code> element.  (This is already
76        included in the default <code>server.xml</code> file.)</li>
77    </ul>
78
79  </blockquote></td></tr></table>
80
81
82  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
83
84    <p>Correct operation of MemoryRealm depends on the following
85    specific features of the surrounding container:</p>
86    <ul>
87    <li>Interactions with <code>MemoryRealm</code> will be initiated by
88        the appropriate <code>Authenticator</code> implementation, based
89        on the login method that is selected.</li>
90    <li><code>MemoryRealm</code> must have an XML parser compatible with
91        the JAXP/1.1 APIs available to it.  This is normally accomplished
92        by placing the corresponding JAR files in directory
93        <code>$CATALINA_HOME/lib</code>.</li>
94    </ul>
95
96  </blockquote></td></tr></table>
97
98
99</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
100
101
102  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview of Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote>
103
104    <p>The main purpose of <code>MemoryRealm</code> is to allow Catalina to
105    authenticate users, and look up the corresponding security roles, from
106    the information found in an XML-format configuration file.  The format
107    of this file is described below.  When a <code>MemoryRealm</code>
108    instance is started, it will read the contents of this XML file and create
109    an "in memory database" of all the valid users and their associated
110    security roles.</p>
111
112    <p>Each time that Catalina needs to authenticate a user, it will call
113    the <code>authenticate()</code> method of this Realm implementation,
114    passing the username and password that were specified by the user.  If
115    we find the user in the database (and match on the password), we accumulate
116    all of the security roles that are defined for this user, and create a
117    new <code>GenericPrincipal</code> object to be returned.  If the user
118    is not authenticated, we return <code>null</code> instead.  The
119    <code>GenericUser</code> object caches the set of security roles that
120    were owned by this user at the time of authentication, so that calls to
121    <code>isUserInRole()</code> can be answered without going back to the
122    database every time.</p>
123
124  </blockquote></td></tr></table>
125
126
127  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Detailed Functional Requirements"><strong>Detailed Functional Requirements</strong></a></font></td></tr><tr><td><blockquote>
128
129
130    <h3>Configurable Properties</h3>
131
132    <p>The implementation shall support the following properties
133    that can be configured with JavaBeans property setters:</p>
134    <ul>
135    <li>Configurable debugging detail level.</li>
136    <li>Configurable file pathname (absolute or relative to
137        <code>$CATALINA_BASE</code> of the XML file containing our
138        defined users.  [<code>conf/tomcat-users.xml</code>].</li>
139    </ul>
140
141    <h3>Lifecycle Functionality</h3>
142
143    <p>The following processing must be performed when the <code>start()</code>
144    method is called:</p>
145    <ul>
146    <li>Open and parse the specified XML file.</li>
147    <li>Create an in-memory database representation of the XML file
148        contents.</li>
149    <li><strong>NOTE</strong> - There is no requirement to recognize
150        subsequent changes to the contents of the XML file.</li>
151    </ul>
152
153    <p>The following processing must be performed when the <code>stop()</code>
154    method is called:</p>
155    <ul>
156    <li>Release object references to the in-memory database representation.</li>
157    </ul>
158
159
160    <h3>Method authenticate() Functionality</h3>
161
162    <p>When <code>authenticate()</code> is called, the following processing
163    is required:</p>
164    <ul>
165    <li>Select the one and only "user" instance from the in-memory database,
166        based on matching the specified username.  If there is no such
167        instance, return <code>null</code>.</li>
168    <li>Authenticate the user by comparing the (possibly encrypted) password
169        value that was received against the password presented by the user.
170        If there is no match, return <code>null</code>.</li>
171    <li>Construct a new instance of class
172        <code>org.apache.catalina.realm.GenericPrincipal</code> (if not
173        already using this as the internal database representation) that
174        contains the authenticated username and a <code>List</code> of the
175        security roles associated with this user.</li>
176    <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
177    </ul>
178
179
180    <h3>Method hasRole() Functionality</h3>
181
182    <p>When <code>hasRole()</code> is called, the following processing
183    is required:</p>
184    <ul>
185    <li>The <code>principal</code> that is passed as an argument SHOULD
186        be one that we returned (instanceof class
187        <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
188        <code>realm</code> property that is equal to our instance.</li>
189    <li>If the passed <code>principal</code> meets these criteria, check
190        the specified role against the list returned by
191        <code>getRoles()</code>, and return <code>true</code> if the
192        specified role is included; otherwise, return <code>false</code>.</li>
193    <li>If the passed <code>principal</code> does not meet these criteria,
194        return <code>false</code>.</li>
195    </ul>
196
197  </blockquote></td></tr></table>
198
199</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
200
201  <p>In addition the the assertions implied by the functionality requirements
202  listed above, the following additional assertions shall be tested to
203  validate the behavior of <code>MemoryRealm</code>:</p>
204  <ul>
205  </ul>
206
207</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
208        Copyright &copy; 1999-2008, Apache Software Foundation
209        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.