xdocs/security.xml - xmlgraphics-batik - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">

 <!--

    Copyright 2002,2004  The Apache Software Foundation

    Licensed 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.

 -->
 <!-- ========================================================================= -->
 <!-- author vincent.hardy@sun.com                                              -->
 <!-- version $Id$ -->
 <!-- ========================================================================= -->
 <document>
   <header>
     <title>Batik Security Features</title>
     <authors>
       <person name="Vincent Hardy" email="vincent.hardy@sun.com"/>
     </authors>
   </header>

   <body>
     <s1 title="Introduction">
         <p>
         With the addition of scripting support in Batik 1.5, security features
         have also been added to enable users of the Batik toolkit to run
         scripts in a secure manner.</p>
         <p>
         If you are using scripts, please make sure you have reviewed the
         <link href="index.html#SecurityWarning">Script Security
         Warning</link> with regards to the Batik 1.5 release.
         </p>
         <p>
        There are two major script security features in Batik:
         </p>
         <ul>
             <li><link href="#sandBox">Script execution</link></li>
             <li><link href="#externalResources">Access to linked resources</link></li>
         </ul>
     </s1>

     <anchor id="sandBox" />
     <s1 title="Running scripts securely">

         <p>The Java platform offers a lot of options for running applications securely.
         Running an application securely requires that it runs in a so-called
         security sand-box which controls all the access the application makes to
         restricted resources (such as the file system).
         </p>

         <p>The concept of Java security is an application-wide concept. As such, it
         has to be applied at the application level (and not at the framework level).
         In the Batik distribution, the sample applications (such as the
         <link href="svgviewer.html">Squiggle Browser</link> or the <link href="svgrasterizer.html">SVG
         rasterizer</link>) apply security (or disable it) but the framework does not
         apply it: it is security-aware (meaning that it is able to handle security
         exceptions).</p>

         <s2 title="Enforcing security in a Batik application">

             <p>
             Enforcing security in a Batik application is done by setting a
             <code>java.lang.SecurityManager</code>. This security manager
             will apply the security settings of the Java platform (as defined
             by the <code>[jre-dir]/lib/security/java.policy</code> and, optionally,
             by the policy file whose url is defined in the <code>java.security.policy</code>
             system property).
             </p>

             <p>
             The <code>org.apache.batik.util.ApplicationSecurityEnforcer</code>
             helper class makes it easier for Batik application
             developers to add security support in their applications. That
             helper class is used by the sample Batik applications.
             </p>
         </s2>

         <s2 title="Squiggle security">

             <p>
             The Squiggle browser lets the user decide whether or not scripts
             should be run securely (see the "Browser Options" in the
             preference dialog box). When scripts are run securely, Squiggle
             will enforce the security settings as follows:
             </p>
             <ul>
                 <li>The default policy is defined by the policy file found
                 in the distribution: <code>org/apache/batik/apps/svgbrowser/svgbrowser.policy</code>.
                 In the binary distribution, that file would be in the
                 <code>batik-squiggle.jar</code> file. In the source
                 distribution, that file would be in the
                 <code>resources</code> directory.  The default policy
                 file gives appropriate permissions to the Batik code,
                 the XML parser and the Rhino scripting engine and very
                 limited permissions to scripts. </li> <li>At startup
                 time, and whenever the preference settings are
                 modified, Squiggle makes a copy of the default policy
                 and appends any additional permissions granted to
                 scripts by the user through the preference
                 settings. This policy file can be found in the
                 <code>[user.home]/.batik</code> directory. It is
                 called <code>__svgbrowser.policy</code>.  Note that
                 this file is automatically generated and should not be
                 modified manually (as any edits would be lost).</li>
                 <li>The policy defined as described above is enforced
                 unless the <code>java.security.policy</code> system
                 property is defined. In that case, the policy defined
                 by the system property takes precedence and the policy
                 file generated from the Squiggle preferences is
                 ignored.</li>
             </ul>

             <p><strong>Important Note</strong></p>
                 <p>
                 The default policy files assume that the applications use the
                 Xerces parser and give appropriate permissions to its
                 <code>lib/xerces-2_5_0.jar</code> JAR file. If you are using
                 a different XML parser, you need to modify the policy files to
                 grant the propser permissions to your XML parser instead of
                 Xerces. You will have to replace:
                 </p>
 <source>
 grant codeBase "${app.dev.base}/lib/xerces_2_5_0.jar" {
   permission java.security.AllPermission;
 };
 </source>
                 <p>with:</p>
 <source>
 grant codeBase "${app.dev.base}/lib/myXMLParser.jar" {
   permission java.security.AllPermission;
 };
 </source>
                 <p>
                 in the <code>resources/org/apache/batik/apps/svgbrowser/resources/svgbrowser.policy</code>
                 file (for the source distribution) and do the same in
                 <code>resources/org/apache/batik/apps/svgbrowser/resources/svgbrowser.bin.policy</code> (for
                 the binary distribution which will then need to be rebuilt with the <code>build dist-zip</code>
                 command.
                 </p>

                 <p>
                 Alternatively, you can write your own policy file and specify its
                 url through the <code>java.security.policy</code> system property (which you can
                 specify through the <code>-Djava.security.policy=&lt;url&gt;</code> command line
                 option).
                 </p>

         </s2>
     </s1>

     <anchor id="externalResources" />
     <s1 title="Controlling access to external resources">

         <p>
         SVG makes a very powerful use of external resources in many elements
         such as <code>&lt;image&gt;, &lt;use&gt;, &lt;font&gt;, &lt;script&gt;</code> or
         <code>&lt;radialGradients&gt;</code>. There are over fifteen SVG elements which
         may reference external resources that way.
         </p>

         <p>
         In some environments, and typically for security reasons, it is
         important to control the resources referenced by an SVG document
         and be able to accept or reject these resources.
         </p>

         <p>
         In the Batik toolkit, this flexibility is provided by the
         <code>org.apache.batik.bridge.UserAgent</code> interface which
         can define various strategies with regards to external resources.
         By providing a new implementation of the <code>UserAgent</code>
         interface, it is possible to apply the desired security strategy
         for scripts and external resources.</p>

         <p>
         The following <code>UserAgent</code> methods a provided for
         that purpose:
         </p>
         <ul>
             <li><code>getScriptSecurity(scriptType, scriptURL, docURL)</code>
                 should return the <code>ScriptSecurity</code> strategy for
                 a script of type <code>scriptType</code> (e.g., <code>text/ecmascript</code>)
                 coming from <code>scriptURL</code>.
                 when referenced from the document whose url is <code>docURL</code>.</li>
             <li><code>getExternalResourceSecurity(resourceURL, docURL)</code>
                 should return the <code>ExternalResourceSecurity</code> for
                 a resource coming from <code>resourceURL</code> referenced
                 from the document at url <code>docURL</code></li>
         </ul>

         <p>
         The <code>ScriptSecurity</code> and <code>ExternalResourceSecurity</code>
         interfaces have methods (<code>checkLoadScript</code> and
         <code>checkLoadExternalResource</code> respectively) which should
         throw a <code>SecurityException</code> if the script or resource
         is considered a security threat.
         </p>
         <note>the <code>UserAgent</code> interface has two additional methods
         (<code>checkLoadScript</code> and <code>checkLoadExternalResource</code>
         which are meant to provide a short hand for getting a security strategy
         object and calling the <code>checkLoadXXX</code> method on that object.
         This is how the <code>org.apache.batik.bridge.UserAgentAdapter</code>
         implements this method.
         </note>

         <p>
         Batik provides the following set of <code>ScriptSecurity</code> implementations:
         </p>

         <ul>
             <li><code>NoLoadScriptSecurity</code>. The scrip resource should not be
             loaded </li>
             <li><code>EmbededScriptSecurity</code>. The script resource will only
             be loaded if it is embeded in the SVG document referencing it. This means
             that script attributes (such as <code>onclick</code> on a <code>&lt;rect&gt;</code>
             element is allowed), inline <code>&lt;script&gt;</code> elements and
             <code>&lt;script&gt;</code> elements using a <code>data:</code> url
             (i.e., the script content is Base 64 encoded into the <code>script</code>'s
             <code>xlink:href</code>'s value) will be allowed. All other script
             resources should not be loaded.</li>
             <li><code>DefaultScriptSecurity</code>. The script resource will only
             be loaded if it is embeded in the SVG document (see the description
             of <code>EmbededScriptSecurity</code>) or if it is coming from the same
             location as the document referencing the script. If the document comes
             from a network server, then any script coming from that server will
             be allowed. If the document comes from the file system, then only
             scripts under the same directory root as the SVG document will be allowed.</li>
             <li><code>RelaxedScriptSecurity</code>. Scripts from any location can
             be loaded.</li>
         </ul>

         <p>
         In addition, Batik provides the following set of <code>ExternalResourceSecurity</code>
         implementations:
         </p>

         <ul>
             <li><code>NoLoadExternalResourceSecurity</code>. No external references are allowed</li>
             <li><code>EmbededExternalResourceSecurity</code>. Only resources embeded into the
             file are allowed (i.e., references through the <code>data:</code> protocol</li>
             <li><code>DefaultExternalResourceSecurity</code>. Embeded external resources (see above)
             and resources coming from the same location as the document referencing them
             are allowed.</li>
             <li><code>RelaxedExternalResourceSecurity</code>. Resources from any location
             can be loaded.</li>
         </ul>

     </s1>


   </body>
 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">

	<!--

	Copyright 2002,2004 The Apache Software Foundation

	Licensed 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.

	-->
	<!-- ========================================================================= -->
	<!-- author vincent.hardy@sun.com -->
	<!-- version $Id$ -->
	<!-- ========================================================================= -->
	<document>
	<header>
	<title>Batik Security Features</title>
	<authors>
	<person name="Vincent Hardy" email="vincent.hardy@sun.com"/>
	</authors>
	</header>

	<body>
	<s1 title="Introduction">
	<p>
	With the addition of scripting support in Batik 1.5, security features
	have also been added to enable users of the Batik toolkit to run
	scripts in a secure manner.</p>
	<p>
	If you are using scripts, please make sure you have reviewed the
	<link href="index.html#SecurityWarning">Script Security
	Warning</link> with regards to the Batik 1.5 release.
	</p>
	<p>
	There are two major script security features in Batik:
	</p>
	<ul>
	<li><link href="#sandBox">Script execution</link></li>
	<li><link href="#externalResources">Access to linked resources</link></li>
	</ul>
	</s1>

	<anchor id="sandBox" />
	<s1 title="Running scripts securely">

	<p>The Java platform offers a lot of options for running applications securely.
	Running an application securely requires that it runs in a so-called
	security sand-box which controls all the access the application makes to
	restricted resources (such as the file system).
	</p>

	<p>The concept of Java security is an application-wide concept. As such, it
	has to be applied at the application level (and not at the framework level).
	In the Batik distribution, the sample applications (such as the
	<link href="svgviewer.html">Squiggle Browser</link> or the <link href="svgrasterizer.html">SVG
	rasterizer</link>) apply security (or disable it) but the framework does not
	apply it: it is security-aware (meaning that it is able to handle security
	exceptions).</p>

	<s2 title="Enforcing security in a Batik application">

	<p>
	Enforcing security in a Batik application is done by setting a
	<code>java.lang.SecurityManager</code>. This security manager
	will apply the security settings of the Java platform (as defined
	by the <code>[jre-dir]/lib/security/java.policy</code> and, optionally,
	by the policy file whose url is defined in the <code>java.security.policy</code>
	system property).
	</p>

	<p>
	The <code>org.apache.batik.util.ApplicationSecurityEnforcer</code>
	helper class makes it easier for Batik application
	developers to add security support in their applications. That
	helper class is used by the sample Batik applications.
	</p>
	</s2>

	<s2 title="Squiggle security">

	<p>
	The Squiggle browser lets the user decide whether or not scripts
	should be run securely (see the "Browser Options" in the
	preference dialog box). When scripts are run securely, Squiggle
	will enforce the security settings as follows:
	</p>
	<ul>
	<li>The default policy is defined by the policy file found
	in the distribution: <code>org/apache/batik/apps/svgbrowser/svgbrowser.policy</code>.
	In the binary distribution, that file would be in the
	<code>batik-squiggle.jar</code> file. In the source
	distribution, that file would be in the
	<code>resources</code> directory. The default policy
	file gives appropriate permissions to the Batik code,
	the XML parser and the Rhino scripting engine and very
	limited permissions to scripts. </li> <li>At startup
	time, and whenever the preference settings are
	modified, Squiggle makes a copy of the default policy
	and appends any additional permissions granted to
	scripts by the user through the preference
	settings. This policy file can be found in the
	<code>[user.home]/.batik</code> directory. It is
	called <code>__svgbrowser.policy</code>. Note that
	this file is automatically generated and should not be
	modified manually (as any edits would be lost).</li>
	<li>The policy defined as described above is enforced
	unless the <code>java.security.policy</code> system
	property is defined. In that case, the policy defined
	by the system property takes precedence and the policy
	file generated from the Squiggle preferences is
	ignored.</li>
	</ul>

	<p><strong>Important Note</strong></p>
	<p>
	The default policy files assume that the applications use the
	Xerces parser and give appropriate permissions to its
	<code>lib/xerces-2_5_0.jar</code> JAR file. If you are using
	a different XML parser, you need to modify the policy files to
	grant the propser permissions to your XML parser instead of
	Xerces. You will have to replace:
	</p>
	<source>
	grant codeBase "${app.dev.base}/lib/xerces_2_5_0.jar" {
	permission java.security.AllPermission;
	};
	</source>
	<p>with:</p>
	<source>
	grant codeBase "${app.dev.base}/lib/myXMLParser.jar" {
	permission java.security.AllPermission;
	};
	</source>
	<p>
	in the <code>resources/org/apache/batik/apps/svgbrowser/resources/svgbrowser.policy</code>
	file (for the source distribution) and do the same in
	<code>resources/org/apache/batik/apps/svgbrowser/resources/svgbrowser.bin.policy</code> (for
	the binary distribution which will then need to be rebuilt with the <code>build dist-zip</code>
	command.
	</p>

	<p>
	Alternatively, you can write your own policy file and specify its
	url through the <code>java.security.policy</code> system property (which you can
	specify through the <code>-Djava.security.policy=<url></code> command line
	option).
	</p>

	</s2>
	</s1>

	<anchor id="externalResources" />
	<s1 title="Controlling access to external resources">

	<p>
	SVG makes a very powerful use of external resources in many elements
	such as <code><image>, <use>, <font>, <script></code> or
	<code><radialGradients></code>. There are over fifteen SVG elements which
	may reference external resources that way.
	</p>

	<p>
	In some environments, and typically for security reasons, it is
	important to control the resources referenced by an SVG document
	and be able to accept or reject these resources.
	</p>

	<p>
	In the Batik toolkit, this flexibility is provided by the
	<code>org.apache.batik.bridge.UserAgent</code> interface which
	can define various strategies with regards to external resources.
	By providing a new implementation of the <code>UserAgent</code>
	interface, it is possible to apply the desired security strategy
	for scripts and external resources.</p>

	<p>
	The following <code>UserAgent</code> methods a provided for
	that purpose:
	</p>
	<ul>
	<li><code>getScriptSecurity(scriptType, scriptURL, docURL)</code>
	should return the <code>ScriptSecurity</code> strategy for
	a script of type <code>scriptType</code> (e.g., <code>text/ecmascript</code>)
	coming from <code>scriptURL</code>.
	when referenced from the document whose url is <code>docURL</code>.</li>
	<li><code>getExternalResourceSecurity(resourceURL, docURL)</code>
	should return the <code>ExternalResourceSecurity</code> for
	a resource coming from <code>resourceURL</code> referenced
	from the document at url <code>docURL</code></li>
	</ul>

	<p>
	The <code>ScriptSecurity</code> and <code>ExternalResourceSecurity</code>
	interfaces have methods (<code>checkLoadScript</code> and
	<code>checkLoadExternalResource</code> respectively) which should
	throw a <code>SecurityException</code> if the script or resource
	is considered a security threat.
	</p>
	<note>the <code>UserAgent</code> interface has two additional methods
	(<code>checkLoadScript</code> and <code>checkLoadExternalResource</code>
	which are meant to provide a short hand for getting a security strategy
	object and calling the <code>checkLoadXXX</code> method on that object.
	This is how the <code>org.apache.batik.bridge.UserAgentAdapter</code>
	implements this method.
	</note>

	<p>
	Batik provides the following set of <code>ScriptSecurity</code> implementations:
	</p>

	<ul>
	<li><code>NoLoadScriptSecurity</code>. The scrip resource should not be
	loaded </li>
	<li><code>EmbededScriptSecurity</code>. The script resource will only
	be loaded if it is embeded in the SVG document referencing it. This means
	that script attributes (such as <code>onclick</code> on a <code><rect></code>
	element is allowed), inline <code><script></code> elements and
	<code><script></code> elements using a <code>data:</code> url
	(i.e., the script content is Base 64 encoded into the <code>script</code>'s
	<code>xlink:href</code>'s value) will be allowed. All other script
	resources should not be loaded.</li>
	<li><code>DefaultScriptSecurity</code>. The script resource will only
	be loaded if it is embeded in the SVG document (see the description
	of <code>EmbededScriptSecurity</code>) or if it is coming from the same
	location as the document referencing the script. If the document comes
	from a network server, then any script coming from that server will
	be allowed. If the document comes from the file system, then only
	scripts under the same directory root as the SVG document will be allowed.</li>
	<li><code>RelaxedScriptSecurity</code>. Scripts from any location can
	be loaded.</li>
	</ul>

	<p>
	In addition, Batik provides the following set of <code>ExternalResourceSecurity</code>
	implementations:
	</p>

	<ul>
	<li><code>NoLoadExternalResourceSecurity</code>. No external references are allowed</li>
	<li><code>EmbededExternalResourceSecurity</code>. Only resources embeded into the
	file are allowed (i.e., references through the <code>data:</code> protocol</li>
	<li><code>DefaultExternalResourceSecurity</code>. Embeded external resources (see above)
	and resources coming from the same location as the document referencing them
	are allowed.</li>
	<li><code>RelaxedExternalResourceSecurity</code>. Resources from any location
	can be loaded.</li>
	</ul>

	</s1>


	</body>
	</document>