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