avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject cvs commit: avalon/merlin/platform/xdocs/starting/advanced security.xml index.xml
Date Mon, 19 Jan 2004 21:43:01 GMT
niclas      2004/01/19 13:43:01

  Modified:    merlin/platform/xdocs/meta/block/classloader index.xml
                        navigation.xml
               merlin/platform/xdocs/meta/kernel/parameters index.xml
               merlin/platform/xdocs/starting/advanced index.xml
  Added:       merlin/platform/xdocs/meta/block/classloader/grant index.xml
                        navigation.xml permission.xml
               merlin/platform/xdocs/starting/advanced security.xml
  Log:
  Documentation for the new security system. Needs plenty of touch up.
  
  Revision  Changes    Path
  1.2       +16 -0     avalon/merlin/platform/xdocs/meta/block/classloader/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/meta/block/classloader/index.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- index.xml	24 Sep 2003 09:34:46 -0000	1.1
  +++ index.xml	19 Jan 2004 21:43:00 -0000	1.2
  @@ -76,6 +76,12 @@
                Jar file option extensions repository.
               </td>
             </tr>
  +          <tr>
  +            <td><a href="grant/index.html">grant</a></td><td>0..1</td>
  +            <td>
  +             Granting permissions to code level security.
  +            </td>
  +          </tr>
           </table>
         </subsection>
   
  @@ -95,6 +101,16 @@
         <resource id="tutorial:composition-api" version="1.0"/>
       </repository>
     </classpath>
  +  <grant>
  +    <permission class="java.lang.RuntimePermission" name="getClassLoader" />
  +    <permission class="java.util.PropertyPermission" name="java.*" >
  +      <action>read</action>
  +    </permission>
  +    <permission class="java.util.PropertyPermission" name="com.mycompany.*" >
  +      <action>read</action>
  +      <action>write</action>
  +    </permission>
  +  </grant>
   </classloader>
   ]]></source>
         </subsection>
  
  
  
  1.6       +1 -0      avalon/merlin/platform/xdocs/meta/block/classloader/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/meta/block/classloader/navigation.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- navigation.xml	23 Dec 2003 17:30:30 -0000	1.5
  +++ navigation.xml	19 Jan 2004 21:43:00 -0000	1.6
  @@ -73,6 +73,7 @@
             <item name="classloader" href="/meta/block/classloader/index.html">
               <item name="classpath" href="/meta/block/classloader/classpath/index.html"/>
               <item name="library" href="/meta/block/classloader/extensions.html"/>
  +            <item name="grant" href="/meta/block/classloader/grant/index.html"/>
             </item>
             <item name="component" href="/meta/block/components/index.html"/>
             <item name="container" href="/meta/block/index.html"/>
  
  
  
  1.1                  avalon/merlin/platform/xdocs/meta/block/classloader/grant/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!--
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without modifica-
   tion, are permitted provided that the following conditions are met:
  
   1. Redistributions of  source code must  retain the above copyright  notice,
      this list of conditions and the following disclaimer.
  
   2. Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
  
   3. The end-user documentation included with the redistribution, if any, must
      include  the following  acknowledgment:  "This product includes  software
      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
      Alternately, this  acknowledgment may  appear in the software itself,  if
      and wherever such third-party acknowledgments normally appear.
  
   4. The names "Jakarta", "Apache Avalon", "Avalon Framework" and
      "Apache Software Foundation"  must not be used to endorse or promote
      products derived  from this  software without  prior written
      permission. For written permission, please contact apache@apache.org.
  
   5. Products  derived from this software may not  be called "Apache", nor may
      "Apache" appear  in their name,  without prior written permission  of the
      Apache Software Foundation.
  
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
   This software  consists of voluntary contributions made  by many individuals
   on  behalf of the Apache Software  Foundation. For more  information on the
   Apache Software Foundation, please see http://www.apache.org/.
  -->
  
  <document>
  
    <header>
      <title>Classloader</title>
      <authors>
        <person name="Stephen McConnell" email="mcconnell@apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <section name="Grant Directive">
  
        <subsection name="Nested Elements">
          <table>
            <tr><th>Element</th><th>Occurance</th><th>Description</th></tr>
            <tr>
              <td><a href="permission.html">permission</a></td><td>0..n</td>
              <td>
               The permission descriptor.
              </td>
            </tr>
          </table>
        </subsection>
  
        <subsection name="Description">
        <p>
          The Grant is somewhat similar to the standard Java Security policy
          files, except that it is assigned per container instead of for the
          code loading location. This allow for sharing central repositories
          of code, without necessary giving all the same level of security
          within a system.
        </p>
        </subsection>
  
        <subsection name="Example XML">
  <source><![CDATA[
  <classloader>
    <classpath>
      <repository>
        <resource id="tutorial:composition-api" version="1.0"/>
      </repository>
    </classpath>
    <grant>
      <permission class="java.lang.RuntimePermission" name="getClassLoader" />
      <permission class="java.util.PropertyPermission" name="java.*" >
        <action>read</action>
      </permission>
      <permission class="java.util.PropertyPermission" name="com.mycompany.*" >
        <action>read</action>
        <action>write</action>
      </permission>
    </grant>
  </classloader>
  ]]></source>
        </subsection>
  
      </section>
  
    </body>
  
  </document>
  
  
  
  
  
  1.1                  avalon/merlin/platform/xdocs/meta/block/classloader/grant/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  
  <!--
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without modifica-
   tion, are permitted provided that the following conditions are met:
  
   1. Redistributions of  source code must  retain the above copyright  notice,
      this list of conditions and the following disclaimer.
  
   2. Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
  
   3. The end-user documentation included with the redistribution, if any, must
      include  the following  acknowledgment:  "This product includes  software
      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
      Alternately, this  acknowledgment may  appear in the software itself,  if
      and wherever such third-party acknowledgments normally appear.
  
   4. The names "Jakarta", "Apache Avalon", "Avalon Framework" and
      "Apache Software Foundation"  must not be used to endorse or promote
      products derived  from this  software without  prior written
      permission. For written permission, please contact apache@apache.org.
  
   5. Products  derived from this software may not  be called "Apache", nor may
      "Apache" appear  in their name,  without prior written permission  of the
      Apache Software Foundation.
  
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
   This software  consists of voluntary contributions made  by many individuals
   on  behalf of the Apache Software  Foundation. For more  information on the
   Apache Software Foundation, please see http://www.apache.org/.
  -->
  
  <project>
  
   <title>Merlin</title>
  
   <body>
  
      <links>
        <item name="Apache" href="http://apache.org/"/>
        <item name="Avalon" href="http://avalon.apache.org/"/>
        <item name="Framework" href="http://avalon.apache.org/product/framework/"/>
        <item name="Containers" href="http://avalon.apache.org/product/containers/"/>
        <item name="Components" href="http://avalon.apache.org/product/components/"/>
      </links>
  
      <menu name="About Merlin">
        <item name="Overview" href="/about/index.html"/>
        <item name="Getting Started" href="/starting/index.html"/>
        <item name="Merlin System" href="/merlin/index.html"/>
        <item name="Meta Model" href="/meta/index.html">
          <item name="kernel.xml" href="/meta/kernel/index.html"/>
          <item name="block.xml" href="/meta/block/index.html">
            <item name="services" href="/meta/block/services/index.html"/>
            <item name="classloader" href="/meta/block/classloader/index.html">
              <item name="classpath" href="/meta/block/classloader/classpath/index.html"/>
              <item name="library" href="/meta/block/classloader/extensions.html"/>
              <item name="grant" href="/meta/block/classloader/grant/index.html"/>
            </item>
            <item name="component" href="/meta/block/components/index.html"/>
            <item name="container" href="/meta/block/index.html"/>
            <item name="include" href="/meta/block/include/index.html"/>
          </item>
          <item name="config.xml" href="/meta/config/index.html"/>
        </item>
        <item name="Tools" href="/tools/index.html"/>
      </menu>
  
      <menu name="Resources">
        <item name="Javadoc" href="/api/index.html"/>
        <item name="Download" href="/resources/download.html"/>
        <item name="Roadmap" href="/resources/roadmap/index.html"/>
        <item name="DPML" href="/dpml/index.html"/>
      </menu>
  
      <menu name="Related Projects">
        <item name="Meta" href="http://avalon.apache.org/meta"/>
        <item name="Utilities" href="http://avalon.apache.org/util"/>
        <item name="Repository" href="http://avalon.apache.org/repository"/>
      </menu>
  
   </body>
  
  </project>
  
  
  
  1.1                  avalon/merlin/platform/xdocs/meta/block/classloader/grant/permission.xml
  
  Index: permission.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!--
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without modifica-
   tion, are permitted provided that the following conditions are met:
  
   1. Redistributions of  source code must  retain the above copyright  notice,
      this list of conditions and the following disclaimer.
  
   2. Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
  
   3. The end-user documentation included with the redistribution, if any, must
      include  the following  acknowledgment:  "This product includes  software
      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
      Alternately, this  acknowledgment may  appear in the software itself,  if
      and wherever such third-party acknowledgments normally appear.
  
   4. The names "Jakarta", "Apache Avalon", "Avalon Framework" and
      "Apache Software Foundation"  must not be used to endorse or promote
      products derived  from this  software without  prior written
      permission. For written permission, please contact apache@apache.org.
  
   5. Products  derived from this software may not  be called "Apache", nor may
      "Apache" appear  in their name,  without prior written permission  of the
      Apache Software Foundation.
  
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
   This software  consists of voluntary contributions made  by many individuals
   on  behalf of the Apache Software  Foundation. For more  information on the
   Apache Software Foundation, please see http://www.apache.org/.
  -->
  
  <document>
  
    <header>
      <title>Include Directive</title>
      <authors>
        <person name="Stephen McConnell" email="mcconnell@apache.org"/>
      </authors>
    </header>
  
    <body>
      <section name="Permission Directive">
  
        <subsection name="Nested Elements">
          <table>
            <tr><th>Element</th><th>Occurance</th><th>Description</th></tr>
            <tr>
              <td><a href="action.html">action</a></td><td>0..n</td>
              <td>
               The action descriptor.
              </td>
            </tr>
          </table>
        </subsection>
  
        <subsection name="Attributes">
  
          <table>
            <tr><th>Attribute</th><th>Required</th><th>Description</th></tr>
            <tr>
              <td>class</td><td>yes</td>
              <td>
                The name of the Permission class. This classname must be a subclass of
                the java.security.Permission class.
              </td>
            </tr>
            <tr>
              <td>name</td><td>no</td>
              <td>
                This is the first argument passed into the constructor. Most Permission
                classes calls this the "name" argument, but the has other names
                for certain permission classes, e.g. FilePermission calls it "path".
              </td>
            </tr>
          </table>
        </subsection>
  
        <subsection name="Description">
  <p>
  A resource directive is a logical reference to a jar file within the enclosing repository.
 A repository implementation is responsible for the mapping of logical directives to physical
jar URL.
  </p>
        </subsection>
  
        <subsection name="Example XML">
  <p>
  The following example block.xml demonstrates the inclusion of three blocks within another
enclosing block.  In this example, the common shared API (containing service interfaces classes
is declared in the containing block classloader).
  </p>
  
  <source><![CDATA[
  <classloader>
    <classpath>
      <repository>
        <resource id="james:mail" version="1.3"/>
        <resource id="james:activation" version="1.0"/>
        <resource id="james:mailet-api" version="1.0"/>
      </repository>
    </classpath>
    <grant>
      <permission class="java.lang.RuntimePermission" name="getClassLoader" />
      <permission class="java.util.PropertyPermission" name="java.*" >
        <action>read</action>
      </permission>
      <permission class="java.util.PropertyPermission" name="org.apache.*" >
        <action>read</action>
        <action>write</action>
      </permission>
    </grant>
      
    <!-- include blocks here -->
  
    <include name="james" id="james:block" type="xml"/>
  </classloader>
  ]]></source>
  
       </subsection>
      </section>
    </body>
  
  </document>
  
  
  
  
  
  
  1.7       +19 -1     avalon/merlin/platform/xdocs/meta/kernel/parameters/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/meta/kernel/parameters/index.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- index.xml	15 Jan 2004 13:32:51 -0000	1.6
  +++ index.xml	19 Jan 2004 21:43:00 -0000	1.7
  @@ -86,7 +86,7 @@
             Parameters that are currently available is;
           </p>
           <table>
  -          <tr><th>Name</th><th>Default</th><th>Description</th></tr>
  +          <tr><th>Name</th><th>Default</th><th>Description</th><th>Since</th></tr>
             <tr>
               <td>urn:composition:deployment.timeout</td>
               <td>5000</td>
  @@ -99,6 +99,23 @@
                 deployed. If the interrupt() fails, the whole JVM must be
                 considered unstable, and should terminate.
               </td>
  +            <td>
  +              3.2.5
  +            </td>
  +          </tr>
  +          <tr>
  +            <td>urn:composition:security.enabled</td>
  +            <td>false</td>
  +            <td>
  +              This is a global switch for turning the code level security
  +              on or off. For compatibility reasons, the default is false, 
  +              but any production system should have this true. In the
  +              kernel.xml it is set to true, and for the debug.xml it is
  +              set to false.
  +            </td>
  +            <td>
  +              3.3
  +            </td>
             </tr>
           </table>
         </subsection>
  @@ -113,6 +130,7 @@
             any component or container to start-up, before interrupting
             or failing.  -->
        <parameter name="urn:composition:deployment.timeout" value="2500" />
  +     <parameter name="urn:composition:security.enabled" value="true" />
      </parameters>
     </kernel>
   ]]></source>
  
  
  
  1.8       +8 -0      avalon/merlin/platform/xdocs/starting/advanced/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/starting/advanced/index.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- index.xml	25 Oct 2003 15:27:07 -0000	1.7
  +++ index.xml	19 Jan 2004 21:43:00 -0000	1.8
  @@ -83,6 +83,14 @@
                   it provides.</td>
             </tr>
             <tr>
  +            <td><a href="security.html">Container Security</a></td>
  +            <td>
  +              Starting from Merlin 3.3, it is possible to grant permission per
  +              container, similarily to the standard Java feature of granting
  +              permissions to the code based on where it was loaded from.
  +            </td>
  +          </tr>
  +          <tr>
               <td><a href="unit/index.html">Unit Tests</a></td>
               <td>Setting up unit tests that leverage merlin as the component factory.</td>
             </tr>
  
  
  
  1.1                  avalon/merlin/platform/xdocs/starting/advanced/security.xml
  
  Index: security.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!--
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without modifica-
   tion, are permitted provided that the following conditions are met:
  
   1. Redistributions of  source code must  retain the above copyright  notice,
      this list of conditions and the following disclaimer.
  
   2. Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
  
   3. The end-user documentation included with the redistribution, if any, must
      include  the following  acknowledgment:  "This product includes  software
      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
      Alternately, this  acknowledgment may  appear in the software itself,  if
      and wherever such third-party acknowledgments normally appear.
  
   4. The names "Jakarta", "Apache Avalon", "Avalon Framework" and
      "Apache Software Foundation"  must not be used to endorse or promote
      products derived  from this  software without  prior written
      permission. For written permission, please contact apache@apache.org.
  
   5. Products  derived from this software may not  be called "Apache", nor may
      "Apache" appear  in their name,  without prior written permission  of the
      Apache Software Foundation.
  
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
   This software  consists of voluntary contributions made  by many individuals
   on  behalf of the Apache Software  Foundation. For more  information on the
   Apache Software Foundation, please see http://www.apache.org/.
  -->
  
  <document>
  
    <header>
      <title>Using Merlin</title>
      <authors>
        <person name="Niclas Hedhman" email="niclas@apache.org"/>
      </authors>
    </header>
  
    <body>
      <section name="Advanced Features">
        <subsection name="Granting Permissions to classes in container">
          <p>
           Starting from Merlin 3.3, it is possible to grant permissions to
           classes within a container. This is done by the declaration of a 
           &lt;grant&gt; element in the classloader definition section in
           the block descriptor (e.g. block.xml).
          </p>
          <p>
            In the example below you should be able to see the mechanism. The
            multiple &lt;action&gt; elements, instead of a single String value
            as is more common, was chosen for easier tool support while still
            allowing you to place multiple comma separated actions into a 
            single &lt;action&gt; element, passed to the Permission constructor
            as-is.
          </p>
          <source><![CDATA[
      <container>
        <classloader>
          <classpath>
            <repository>
              <resource id="avalon-framework:avalon-framework-impl" version="4.1.5"/>
              <resource id="mystuff:myfilestorage"/>
            </repository>
          </classpath>
          <grant>
            <permission class="java.io.FilePermission" name="/mystore" >
              <action>read</action>
              <action>write</action>
            </permission>
            <permission class="java.util.PropertyPermission" name="*" >
              <action>read</action>
            </permission>
            <permission class="java.util.PropertyPermission" name="com.mycompany.*" >
              <action>read</action>
              <action>write</action>
            </permission>
          </grant> 
        </classloader>
      </container>
  ]]></source>
          <p>
           There can only be a single &lt;grant&gt; for each &lt;classloader&gt;
           and any number of &lt;permission&gt; elements within. 
          </p>
        </subsection>
  
        <subsection name="Implementing Security in Components.">
          <p>
            If you are only looking for basic security, similar to any typical
            stand-alone application, that would depend on a Java Security Policy
            file, you don't need to do anything special. All classes in Java
            will perform the security checks behind the scenes, protecting
            files, network connection and many other system resources. Please
            refer to your Java Security documentation for full details.
          </p>
          <p>
            If you want to guard some resource or a section of code, you will
            need to;
          </p>
          <ul>
            <li>
              Create a subclass of java.security.Permission, or one of its
              subclasses such as java.lang.BasicPermission, and override
              the implies(), equals() and hashCode() methods.
            </li>
            <li>
              Insert a AccessController.checkPermission() at the relevant
              points in your code. (See examples below.)
            </li>
          </ul>
        </subsection>
        <subsection name="Examples of Security" >
          <subsection name="Using an existing Permission class">
            <p>
              This first example uses a simple named RuntimePermission.
            </p>
            <source><![CDATA[
      public SuperGlue getSuperGlue()
      {
          Permission p = new RuntimePermission( "useSuperGlue" );
          AccessController.checkPermission( p );
          return m_SuperGlue;
      }
  ]]></source>
            <p>
              In this example, we utilizes the existing 
              java.lang.RuntimePermission to do a very simple check, i.e is the
              current protection domain allowed to use the SuperGlue. 
            </p>
            <p>
              And to make this work in your Merlin application, you would need to
              insert the appropriate permission in the &lt;grant&gt; element.
            </p>
            <source><![CDATA[
      <container>
        <classloader>
          <!-- other stuff -->
          <grant>
            <permission class="java.lang.RuntimePermission" name="useSuperGlue" />
          </grant>
        </classloader>
      </container>
  ]]></source>
          </subsection>
          <subsection name="Creating a new Permission class">
            <p>
              If you need something more complicated that can not be fulfilled
              with the existing Permission classes, you will need to create your
              own. This can be rather tricky, depending on what you are actually
              trying to do.
            </p>
            <p>
              In the example below, we have a Permission class that ensures that 
              an amount is within its boundaries, for instance for a banking application.
              The semantics are;
            </p>
            <ul>
              <li>
                The name argument for a granted permission (declared) contains a 
                minimum value, followed by a dash and then followed by a maximum 
                value.
              </li>
              <li>
                The name argument for a required permission (programmatically)
                only contains a single value, which is the requested amount.
                The amount is expressed in cent, and no fractional numbers needed.
              </li>
              <li>
                If any of the two values are missing, the default is used. The
                default is 1000000 for each.
              </li>
              <li>
                The action argument contains either "deposit" or "withdrawal".
              </li>
              <li>
                The granted permission must contain the action of the required
                permission, and the required permission's amount must be within
                the limits of the granted permission.
              </li>
            </ul>
            <p>
              As we can see it is a fairly straight forward algorithm, but a bit
              hard to put in words, and I hope I haven't missed something. To do
              this with Java Security permissions is fairly easy.
            </p>
            <source><![CDATA[
  public class AccountPermission extends Permission
  {
      private long m_Minimum;
      private long m_Maximum;
      private int  m_Actions;
      
      public AccountPermission( String amount, String actions )
      {
          super( amount );
          parseAmount( amount );
          parseActions( actions );
      }
      
      public int hashCode()
      {
          return (int) m_Actions * 876238684 + m_Minimum * 23457241393 + m_Maximum;
      }
      
      public boolean equals( Object obj )
      {
          if( ! ( obj.getClass().equals( AccountPermission.class ) ) )
              return false;
          AmountPermission other = (AmountPermission) obj;
          return m_Actions == other.m_Actions  &&
                 m_Minimum == other.m_Minimum &&
                 m_Maximum == other.m_Maximum;
      }
      
      public boolean implies( Permission permission )
      {
          if( ! (permission.getClass().equals( AmountPermission.class ) ) )
              return false;
          AmountPermission requesting = (AmountPermission) permission;
          if( ( m_Actions & requesting.m_Actions ) > 0 )
              return false;
          if( requesting.m_Minimum < m_Minimum )
              return false;
          if( requesting.m_Minimum > m_Maximum )
              return false;
          return true;
      }
      
      private void parseAmount( String amount )
      {
          m_Minimum = 1000000;
          m_Maximum = 1000000;
          if( amount == null || "".equals( amount ) )
              return;
              
          int dash = amount.indexOf( '-' );
          if( dash < 0 )
          {
              try
              {
                  m_Minimum = Long.parseLong( amount );
              } catch( NumberFormatException e )
              {} // ignore, use default
          }
          else
          {
              String am1 = amount.substring( 0, dash );
              String am2 = amount.substring( dash + 1 );
              try
              {
                  m_Minimum = Long.parseLong( am1 );
              } catch( NumberFormatException e )
              {} // ignore, use default
              try
              {
                  m_Maximum = Long.parseLong( am2 );
              } catch( NumberFormatException e )
              {} // ignore, use default
          }
      }
      
      private void parseActions( String actions )
      {
          // This should probably be done differently.
          m_Actions = 0;
          if( actions.indexOf( "withdrawal" ) )
              m_Actions = 1;
          if( actions.indexOf( "deposit" ) )
              m_Actions += 2;
      }
  }
      
  ]]></source>
          <p>
            Please note that the code has not yet been tested. If you do
            please post any mistake to dev@avalon.apache.org. Thank you.
          </p>
          <p>
            Then in the actual code, we would do something like this;
          </p>
            <source><![CDATA[
      public void deposit( long amount )
      {
          AmountPermission p = new AmountPermission( (String) amount, "deposit" );
          AccessController.checkPermission( p );
      }
      
      public void withdraw( long amount )
      {
          AmountPermission p = new AmountPermission( (String) amount, "withdrawal" );
          AccessController.checkPermission( p );
      }
  ]]></source>
          <p>
            Wasn't that easy? Well, it would have been if we could tie the principal
            customer/client/user to the protection domain that is checked. This is
            currently on the drawing board for Avalon Merlin, and will probably 
            not be ready until version 4.0, somewhere mid or late 2004.
            While awaiting this Subject-based, generic, pluggable security system,
            you can hack the above example a little bit, for some basic subject
            driven security. 
          </p>
          <p>
            In the implies() method, you reach out and detect who is executing
            the current thread, for instance through a ThreadLocal variable,
            ask some authoritive object instance for the amounts allowed and 
            perform the check. This is NOT the recommended method for larger and
            more complex system (such as banks), but can work as a temporary 
            solution for the time being.
          </p>
          </subsection>
        </subsection>
      </section>
    </body>
  
  </document>
  
  
  
  
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message