xmlgraphics-batik-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From vha...@apache.org
Subject cvs commit: xml-batik/xdocs security.xml site-book.xml
Date Mon, 17 Jun 2002 11:43:37 GMT
vhardy      2002/06/17 04:43:37

  Modified:    xdocs    site-book.xml
  Added:       xdocs    security.xml
  Log:
  Added documentation on the 1.5 security features
  
  Revision  Changes    Path
  1.28      +2 -1      xml-batik/xdocs/site-book.xml
  
  Index: site-book.xml
  ===================================================================
  RCS file: /home/cvs/xml-batik/xdocs/site-book.xml,v
  retrieving revision 1.27
  retrieving revision 1.28
  diff -u -r1.27 -r1.28
  --- site-book.xml	8 Mar 2002 08:45:28 -0000	1.27
  +++ site-book.xml	17 Jun 2002 11:43:37 -0000	1.28
  @@ -64,6 +64,7 @@
       <page id="scripting"          label="Scripting Intro"          source="scriptIntro.xml"
/>
       <page id="scriptfeatures"     label="Scripting Features"       source="scriptFeatures.xml"
/>
       <page id="javaScripting"      label="Java Scripting"           source="javaScripting.xml"
/>
  +    <page id="security"           label="Security"                 source="security.xml"
/>
       <separator />
       <page id="extendingBatik"     label="Extensions"               source="extendingBatik.xml"
/>
       <separator/>
  
  
  
  1.1                  xml-batik/xdocs/security.xml
  
  Index: security.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <!-- ========================================================================= -->
  <!-- Copyright (C) The Apache Software Foundation. All rights reserved.        -->
  <!--                                                                           -->
  <!-- This software is published under the terms of the Apache Software License -->
  <!-- version 1.1, a copy of which has been included with this distribution in  -->
  <!-- the LICENSE file.                                                         -->
  <!-- ========================================================================= -->
  
  <!-- ========================================================================= -->
  <!-- author vincent.hardy@sun.com                                              -->
  <!-- version $Id: security.xml,v 1.1 2002/06/17 11:43:37 vhardy Exp $ -->      
  <!-- ========================================================================= -->
  <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. There are two major 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-svgbrowser.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 
                  Crimson parser and give appropriate permissions to its 
                  <code>lib/crimson-parser.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 
                  Crimson. You will have to replace:
                  </p>
  <source>
  grant codeBase "${app.dev.base}/lib/crimson-parser.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>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: batik-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: batik-dev-help@xml.apache.org


Mime
View raw message