documentation-sources/content/xdocs/using/scripting/security.xml - xmlgraphics-batik - Git at Google

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

 -->

 <!-- ========================================================================= -->
 <!-- author vincent.hardy@sun.com                                              -->
 <!-- version $Id: security.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
 <!-- ========================================================================= -->

 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
   <header>
     <title>Script security</title>
   </header>

   <body>
     <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 script, please make sure you have reviewed the
       <a href="../../index.html#SecurityWarning">Script Security
         Warning</a> with regards to the Batik 1.5 release.
     </p>

     <section id="sandbox">
       <title>Running scripts securely</title>

       <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 <a href="site:browser">Squiggle Browser</a> and the
         <a href="site:rasterizer">SVG rasterizer</a>) 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>

       <section id="enforcing">
         <title>Enforcing security in a Batik application</title>

         <p>
           Enforcing security in a Batik application is done by setting a
           <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/SecurityManager.html">java.lang.SecurityManager</a>.
           This security manager will apply the security settings of the Java
           platform (as defined by the
           <em>jre-dir</em><code>/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
           <a class="class" href="../../javadoc/org/apache/batik/util/ApplicationSecurityEnforcer.html">org.apache.batik.util.ApplicationSecurityEnforcer</a>
           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>
       </section>

       <section id="squiggle">
         <title>Squiggle security</title>

         <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, and 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>
           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=</code><em>url</em> command line
           option).
         </p>
       </section>
     </section>

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

       <p>
         SVG makes a very powerful use of external resources in many elements
         such as <code>image</code>, <code>use</code>, <code>font</code>,
         <code>script</code> and <code>radialGradient</code>. There are over
         fifteen SVG elements that 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
         <a class="class" href="../../javadoc/org/apache/batik/bridge/UserAgent.html">org.apache.batik.bridge.UserAgent</a>
         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 are provided for
         that purpose:
       </p>
       <ul>
         <li>
           <code>getScriptSecurity(scriptType, scriptURL, docURL)</code>
           should return the
           <a class="class" href="../../javadoc/org/apache/batik/bridge/ScriptSecurity.html">ScriptSecurity</a>
           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
           <a class="class" href="../../javadoc/org/apache/batik/bridge/ExternalResourceSecurity.html">ExternalResourceSecurity</a>
           strategry 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
         <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/SecurityException.html">SecurityException</a>
         if accessing the script or resource is considered a security violation.
       </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>checkLoad</code>* method on that object.
         This is how the
         <a class="class" href="../../javadoc/org/apache/batik/bridge/UserAgentAdapter.html">org.apache.batik.bridge.UserAgentAdapter</a>
         class implements this method.
       </note>
       <p>
         Batik provides the following set of <code>ScriptSecurity</code>
         implementations:
       </p>

       <dl>
         <dt>NoLoadScriptSecurity</dt>
         <dd>
           <p>The script resource should not be loaded.</p>
         </dd>
         <dt>EmbededScriptSecurity</dt>
         <dd>
           <p>
             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),
             inline <code>script</code> elements and <code>script</code> elements
             using a <code>data:</code> URL as its <code>xlink:href</code> attribute
             value will be allowed. All other script resources should not be
             loaded.
           </p>
         </dd>
         <dt>DefaultScriptSecurity</dt>
         <dd>
           <p>
             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.
           </p>
         </dd>
         <dt>RelaxedScriptSecurity</dt>
         <dd>
           <p>
             Scripts from any location can be loaded.
           </p>
         </dd>
       </dl>

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

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

     </section>

   </body>
 </document>
	<?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.

	-->

	<!-- ========================================================================= -->
	<!-- author vincent.hardy@sun.com -->
	<!-- version $Id: security.xml 201374 2004-08-18 07:17:26Z vhardy $ -->
	<!-- ========================================================================= -->

	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
	<document>
	<header>
	<title>Script security</title>
	</header>

	<body>
	<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 script, please make sure you have reviewed the
	<a href="../../index.html#SecurityWarning">Script Security
	Warning</a> with regards to the Batik 1.5 release.
	</p>

	<section id="sandbox">
	<title>Running scripts securely</title>

	<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 <a href="site:browser">Squiggle Browser</a> and the
	<a href="site:rasterizer">SVG rasterizer</a>) 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>

	<section id="enforcing">
	<title>Enforcing security in a Batik application</title>

	<p>
	Enforcing security in a Batik application is done by setting a
	<a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/SecurityManager.html">java.lang.SecurityManager</a>.
	This security manager will apply the security settings of the Java
	platform (as defined by the
	<em>jre-dir</em><code>/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
	<a class="class" href="../../javadoc/org/apache/batik/util/ApplicationSecurityEnforcer.html">org.apache.batik.util.ApplicationSecurityEnforcer</a>
	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>
	</section>

	<section id="squiggle">
	<title>Squiggle security</title>

	<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, and 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>
	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=</code><em>url</em> command line
	option).
	</p>
	</section>
	</section>

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

	<p>
	SVG makes a very powerful use of external resources in many elements
	such as <code>image</code>, <code>use</code>, <code>font</code>,
	<code>script</code> and <code>radialGradient</code>. There are over
	fifteen SVG elements that 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
	<a class="class" href="../../javadoc/org/apache/batik/bridge/UserAgent.html">org.apache.batik.bridge.UserAgent</a>
	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 are provided for
	that purpose:
	</p>
	<ul>
	<li>
	<code>getScriptSecurity(scriptType, scriptURL, docURL)</code>
	should return the
	<a class="class" href="../../javadoc/org/apache/batik/bridge/ScriptSecurity.html">ScriptSecurity</a>
	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
	<a class="class" href="../../javadoc/org/apache/batik/bridge/ExternalResourceSecurity.html">ExternalResourceSecurity</a>
	strategry 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
	<a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/SecurityException.html">SecurityException</a>
	if accessing the script or resource is considered a security violation.
	</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>checkLoad</code>* method on that object.
	This is how the
	<a class="class" href="../../javadoc/org/apache/batik/bridge/UserAgentAdapter.html">org.apache.batik.bridge.UserAgentAdapter</a>
	class implements this method.
	</note>
	<p>
	Batik provides the following set of <code>ScriptSecurity</code>
	implementations:
	</p>

	<dl>
	<dt>NoLoadScriptSecurity</dt>
	<dd>
	<p>The script resource should not be loaded.</p>
	</dd>
	<dt>EmbededScriptSecurity</dt>
	<dd>
	<p>
	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),
	inline <code>script</code> elements and <code>script</code> elements
	using a <code>data:</code> URL as its <code>xlink:href</code> attribute
	value will be allowed. All other script resources should not be
	loaded.
	</p>
	</dd>
	<dt>DefaultScriptSecurity</dt>
	<dd>
	<p>
	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.
	</p>
	</dd>
	<dt>RelaxedScriptSecurity</dt>
	<dd>
	<p>
	Scripts from any location can be loaded.
	</p>
	</dd>
	</dl>

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

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

	</section>

	</body>
	</document>