1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
|
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="security-manager-howto.html">
&project;
<properties>
<author email="glenn@voyager.apg.more.net">Glenn Nielsen</author>
<author email="jeanfrancois.arcand@sun.com">Jean-Francois Arcand</author>
<title>Security Manager HOW-TO</title>
</properties>
<body>
<section name="Background">
<p>The Java <strong>SecurityManager</strong> is what allows a web browser
to run an applet in its own sandbox to prevent untrusted code from
accessing files on the local file system, connecting to a host other
than the one the applet was loaded from, and so on. In the same way
the SecurityManager protects you from an untrusted applet running in
your browser, use of a SecurityManager while running Tomcat can protect
your server from trojan servlets, JSPs, JSP beans, and tag libraries.
Or even inadvertent mistakes.</p>
<p>Imagine if someone who is authorized to publish JSPs on your site
inadvertently included the following in their JSP:</p>
<source>
<% System.exit(1); %>
</source>
<p>Every time this JSP was executed by Tomcat, Tomcat would exit.
Using the Java SecurityManager is just one more line of defense a
system administrator can use to keep the server secure and reliable.</p>
<p><strong>WARNING</strong> - A security audit
have been conducted using the Tomcat 5 codebase. Most of the critical
package have been protected and a new security package protection mechanism
has been implemented. Still, make sure that you are satisfied with your SecurityManager
configuration before allowing untrusted users to publish web applications,
JSPs, servlets, beans, or tag libraries. <strong>However, running with a
SecurityManager is definitely better than running without one.</strong></p>
</section>
<section name="Permissions">
<p>Permission classes are used to define what Permissions a class loaded
by Tomcat will have. There are a number of Permission classes that are
a standard part of the JDK, and you can create your own Permission class
for use in your own web applications. Both techniques are used in
Tomcat 6.</p>
<subsection name="Standard Permissions">
<p>This is just a short summary of the standard system SecurityManager
Permission classes applicable to Tomcat. See
<a href="http://java.sun.com/security/">http://java.sun.com/security/</a>
for more information.</p>
<ul>
<li><strong>java.util.PropertyPermission</strong> - Controls read/write
access to JVM properties such as <code>java.home</code>.</li>
<li><strong>java.lang.RuntimePermission</strong> - Controls use of
some System/Runtime functions like <code>exit()</code> and
<code>exec()</code>. Also control the package access/definition.</li>
<li><strong>java.io.FilePermission</strong> - Controls read/write/execute
access to files and directories.</li>
<li><strong>java.net.SocketPermission</strong> - Controls use of
network sockets.</li>
<li><strong>java.net.NetPermission</strong> - Controls use of
multicast network connections.</li>
<li><strong>java.lang.reflect.ReflectPermission</strong> - Controls
use of reflection to do class introspection.</li>
<li><strong>java.security.SecurityPermission</strong> - Controls access
to Security methods.</li>
<li><strong>java.security.AllPermission</strong> - Allows access to all
permissions, just as if you were running Tomcat without a
SecurityManager.</li>
</ul>
</subsection>
<subsection name="Tomcat Custom Permissions">
<p>Tomcat utilizes a custom permission class called
<strong>org.apache.naming.JndiPermission</strong>. This permission
controls read access to JNDI named file based resources. The permission
name is the JNDI name and there are no actions. A trailing "*" can be
used to do wild card matching for a JNDI named file resource when
granting permission. For example, you might include the following
in your policy file:</p>
<source>
permission org.apache.naming.JndiPermission "jndi://localhost/examples/*";
</source>
<p>A Permission entry like this is generated dynamically for each web
application that is deployed, to allow it to read its own static resources
but disallow it from using file access to read any other files (unless
permissions for those files are explicitly granted).</p>
<p>Also, Tomcat always dynamically creates the following file permission:</p>
<source>
permission java.io.FilePermission "** your application context**", "read";
</source>
<p>Where **your application context** equals the folder(or WAR file) under which
your application has been deployed. </p>
</subsection>
</section>
<section name="Configuring Tomcat With A SecurityManager">
<h3>Policy File Format</h3>
<p>The security policies implemented by the Java SecurityManager are
configured in the <code>$CATALINA_HOME/conf/catalina.policy</code> file.
This file completely replaces the <code>java.policy</code> file present
in your JDK system directories. The <code>catalina.policy</code> file
can be edited by hand, or you can use the
<a href="http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/policytool.html">policytool</a>
application that comes with Java 1.2 or later.</p>
<p>Entries in the <code>catalina.policy</code> file use the standard
<code>java.policy</code> file format, as follows:</p>
<source>
// Example policy file entry
grant [signedBy <signer>,] [codeBase <code source>] {
permission <class> [<name> [, <action list>]];
};
</source>
<p>The <strong>signedBy</strong> and <strong>codeBase</strong> entries are
optional when granting permissions. Comment lines begin with "//" and
end at the end of the current line. The <code>codeBase</code> is in the
form of a URL, and for a file URL can use the <code>${java.home}</code>
and <code>${catalina.home}</code> properties (which are expanded out to
the directory paths defined for them by the <code>JAVA_HOME</code> and
<code>CATALINA_HOME</code> environment variables).</p>
<h3>The Default Policy File</h3>
<p>The default <code>$CATALINA_HOME/conf/catalina.policy</code> file
looks like this:</p>
<source>
// ============================================================================
// catalina.corepolicy - Security Policy Permissions for Tomcat 6
//
// This file contains a default set of security policies to be enforced (by the
// JVM) when Catalina is executed with the "-security" option. In addition
// to the permissions granted here, the following additional permissions are
// granted to the codebase specific to each web application:
//
// * Read access to the document root directory
//
// $Id: security-manager-howto.xml 562814 2007-08-05 03:52:04Z markt $
// ============================================================================
// ========== SYSTEM CODE PERMISSIONS =========================================
// These permissions apply to javac
grant codeBase "file:${java.home}/lib/-" {
permission java.security.AllPermission;
};
// These permissions apply to all shared system extensions
grant codeBase "file:${java.home}/jre/lib/ext/-" {
permission java.security.AllPermission;
};
// These permissions apply to javac when ${java.home] points at $JAVA_HOME/jre
grant codeBase "file:${java.home}/../lib/-" {
permission java.security.AllPermission;
};
// These permissions apply to all shared system extensions when
// ${java.home} points at $JAVA_HOME/jre
grant codeBase "file:${java.home}/lib/ext/-" {
permission java.security.AllPermission;
};
// ========== CATALINA CODE PERMISSIONS =======================================
// These permissions apply to the daemon code
grant codeBase "file:${catalina.home}/bin/commons-daemon.jar" {
permission java.security.AllPermission;
};
// These permissions apply to the logging API
grant codeBase "file:${catalina.home}/bin/tomcat-juli.jar" {
permission java.security.AllPermission;
};
// These permissions apply to the server startup code
grant codeBase "file:${catalina.home}/bin/bootstrap.jar" {
permission java.security.AllPermission;
};
// These permissions apply to the servlet API classes
// and those that are shared across all class loaders
// located in the "lib" directory
grant codeBase "file:${catalina.home}/lib/-" {
permission java.security.AllPermission;
};
// ========== WEB APPLICATION PERMISSIONS =====================================
// These permissions are granted by default to all web applications
// In addition, a web application will be given a read FilePermission
// and JndiPermission for all files and directories in its document root.
grant {
// Required for JNDI lookup of named JDBC DataSource's and
// javamail named MimePart DataSource used to send mail
permission java.util.PropertyPermission "java.home", "read";
permission java.util.PropertyPermission "java.naming.*", "read";
permission java.util.PropertyPermission "javax.sql.*", "read";
// OS Specific properties to allow read access
permission java.util.PropertyPermission "os.name", "read";
permission java.util.PropertyPermission "os.version", "read";
permission java.util.PropertyPermission "os.arch", "read";
permission java.util.PropertyPermission "file.separator", "read";
permission java.util.PropertyPermission "path.separator", "read";
permission java.util.PropertyPermission "line.separator", "read";
// JVM properties to allow read access
permission java.util.PropertyPermission "java.version", "read";
permission java.util.PropertyPermission "java.vendor", "read";
permission java.util.PropertyPermission "java.vendor.url", "read";
permission java.util.PropertyPermission "java.class.version", "read";
permission java.util.PropertyPermission "java.specification.version", "read";
permission java.util.PropertyPermission "java.specification.vendor", "read";
permission java.util.PropertyPermission "java.specification.name", "read";
permission java.util.PropertyPermission "java.vm.specification.version", "read";
permission java.util.PropertyPermission "java.vm.specification.vendor", "read";
permission java.util.PropertyPermission "java.vm.specification.name", "read";
permission java.util.PropertyPermission "java.vm.version", "read";
permission java.util.PropertyPermission "java.vm.vendor", "read";
permission java.util.PropertyPermission "java.vm.name", "read";
// Required for OpenJMX
permission java.lang.RuntimePermission "getAttribute";
// Allow read of JAXP compliant XML parser debug
permission java.util.PropertyPermission "jaxp.debug", "read";
// Precompiled JSPs need access to this package.
permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.runtime";
permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.runtime.*";
};
// You can assign additional permissions to particular web applications by
// adding additional "grant" entries here, based on the code base for that
// application, /WEB-INF/classes/, or /WEB-INF/lib/ jar files.
//
// Different permissions can be granted to JSP pages, classes loaded from
// the /WEB-INF/classes/ directory, all jar files in the /WEB-INF/lib/
// directory, or even to individual jar files in the /WEB-INF/lib/ directory.
//
// For instance, assume that the standard "examples" application
// included a JDBC driver that needed to establish a network connection to the
// corresponding database and used the scrape taglib to get the weather from
// the NOAA web server. You might create a "grant" entries like this:
//
// The permissions granted to the context root directory apply to JSP pages.
// grant codeBase "file:${catalina.home}/webapps/examples/-" {
// permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect";
// permission java.net.SocketPermission "*.noaa.gov:80", "connect";
// };
//
// The permissions granted to the context WEB-INF/classes directory
// grant codeBase "file:${catalina.home}/webapps/examples/WEB-INF/classes/-" {
// };
//
// The permission granted to your JDBC driver
// grant codeBase "jar:file:${catalina.home}/webapps/examples/WEB-INF/lib/driver.jar!/-" {
// permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect";
// };
// The permission granted to the scrape taglib
// grant codeBase "jar:file:${catalina.home}/webapps/examples/WEB-INF/lib/scrape.jar!/-" {
// permission java.net.SocketPermission "*.noaa.gov:80", "connect";
// };
</source>
<h3>Starting Tomcat With A SecurityManager</h3>
<p>Once you have configured the <code>catalina.policy</code> file for use
with a SecurityManager, Tomcat can be started with a SecurityManager in
place by using the "-security" option:</p>
<source>
$CATALINA_HOME/bin/catalina.sh start -security (Unix)
%CATALINA_HOME%\bin\catalina start -security (Windows)
</source>
</section>
<section name="Configuring Package Protection in Tomcat">
<p>Starting with Tomcat 5, it is now possible to configure which Tomcat
internal package are protected againts package definition and access. See
<a href="http://java.sun.com/security/seccodeguide.html">
http://java.sun.com/security/seccodeguide.html</a>
for more information.</p>
<p><strong>WARNING</strong>: Be aware that removing the default package protection
could possibly open a security hole</p>
<h3>The Default Properties File</h3>
<p>The default <code>$CATALINA_HOME/conf/catalina.properties</code> file
looks like this:</p>
<source>
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.,org.apache.catalina.,org.apache.coyote.,org.apache.tomcat.,
org.apache.jasper.
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
package.definition=sun.,java.,org.apache.catalina.,org.apache.coyote.,
org.apache.tomcat.,org.apache.jasper.
</source>
<p>Once you have configured the <code>catalina.properties</code> file for use
with a SecurityManager, remember to re-start Tomcat.</p>
</section>
<section name="Troubleshooting">
<p>If your web application attempts to execute an operation that is
prohibited by lack of a required Permission, it will throw an
<code>AccessControLException</code> or a <code>SecurityException</code>
when the SecurityManager detects the violation. Debugging the permission
that is missing can be challenging, and one option is to turn on debug
output of all security decisions that are made during execution. This
is done by setting a system property before starting Tomcat. The easiest
way to do this is via the <code>CATALINA_OPTS</code> environment variable.
Execute this command:</p>
<source>
export CATALINA_OPTS=-Djava.security.debug=all (Unix)
set CATALINA_OPTS=-Djava.security.debug=all (Windows)
</source>
<p>before starting Tomcat.</p>
<p><strong>WARNING</strong> - This will generate <em>many megabytes</em>
of output! However, it can help you track down problems by searching
for the word "FAILED" and determining which permission was being checked
for. See the Java security documentation for more options that you can
specify here as well.</p>
</section>
</body>
</document>
|
