src/org/mozilla/javascript/SecuritySupport.java

   1 /* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-\r
   2  *\r
   3  * The contents of this file are subject to the Netscape Public\r
   4  * License Version 1.1 (the "License"); you may not use this file\r
   5  * except in compliance with the License. You may obtain a copy of\r
   6  * the License at http://www.mozilla.org/NPL/\r
   7  *\r
   8  * Software distributed under the License is distributed on an "AS\r
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express oqr\r
  10  * implied. See the License for the specific language governing\r
  11  * rights and limitations under the License.\r
  12  *\r
  13  * The Original Code is Rhino code, released\r
  14  * May 6, 1999.\r
  15  *\r
  16  * The Initial Developer of the Original Code is Netscape\r
  17  * Communications Corporation.  Portions created by Netscape are\r
  18  * Copyright (C) 1997-1999 Netscape Communications Corporation. All\r
  19  * Rights Reserved.\r
  20  *\r
  21  * Contributor(s): \r
  22  * Norris Boyd\r
  23  *\r
  24  * Alternatively, the contents of this file may be used under the\r
  25  * terms of the GNU Public License (the "GPL"), in which case the\r
  26  * provisions of the GPL are applicable instead of those above.\r
  27  * If you wish to allow use of your version of this file only\r
  28  * under the terms of the GPL and not to allow others to use your\r
  29  * version of this file under the NPL, indicate your decision by\r
  30  * deleting the provisions above and replace them with the notice\r
  31  * and other provisions required by the GPL.  If you do not delete\r
  32  * the provisions above, a recipient may use your version of this\r
  33  * file under either the NPL or the GPL.\r
  34  */\r
  35 \r
  36 // API class\r
  37 \r
  38 package org.mozilla.javascript;\r
  39 \r
  40 /**\r
  41  * This class describes the support needed to implement security.\r
  42  * <p>\r
  43  * Three main pieces of functionality are required to implement\r
  44  * security for JavaScript. First, it must be possible to define\r
  45  * classes with an associated security context. (This security \r
  46  * context may be any object that has meaning to an embedding;\r
  47  * for a client-side JavaScript embedding this would typically\r
  48  * be an origin URL and/or a digital certificate.) Next it \r
  49  * must be possible to get the current class context so that\r
  50  * the implementation can determine securely which class is\r
  51  * requesting a privileged action. And finally, it must be \r
  52  * possible to map a class back into a security context so that\r
  53  * additional classes may be defined with that security context.\r
  54  * <p>\r
  55  * These three pieces of functionality are encapsulated in the\r
  56  * SecuritySupport class.\r
  57  * <p>\r
  58  * Additionally, an embedding may provide filtering on the \r
  59  * Java classes that are visible to scripts through the \r
  60  * <code>visibleToScripts</code> method.\r
  61  *\r
  62  * @see org.mozilla.javascript.Context\r
  63  * @see java.lang.ClassLoader\r
  64  * @since 1.4 Release 2\r
  65  * @author Norris Boyd\r
  66  */\r
  67 public interface SecuritySupport {\r
  68 \r
  69     /**\r
  70      * Define and load a Java class.\r
  71      * <p>\r
  72      * In embeddings that care about security, the securityDomain \r
  73      * must be associated with the defined class such that a call to\r
  74      * <code>getSecurityDomain</code> with that class will return this security\r
  75      * context.\r
  76      * <p>\r
  77      * @param name the name of the class\r
  78      * @param data the bytecode of the class\r
  79      * @param securityDomain some object specifying the security\r
  80      *        context of the code that is defining this class.\r
  81      *        Embeddings that don't care about security may allow\r
  82      *        null here. This value propagated from the values passed\r
  83      *        into methods of Context that evaluate scripts.\r
  84      */\r
  85     public Class defineClass(String name, byte[] data, \r
  86                              Object securityDomain);\r
  87         \r
  88     /**\r
  89      * Get the current class Context.\r
  90      * <p> \r
  91      * This functionality is supplied by SecurityManager.getClassContext,\r
  92      * but only one SecurityManager may be instantiated in a single JVM\r
  93      * at any one time. So implementations that care about security must\r
  94      * provide access to this functionality through this interface.\r
  95      * <p>\r
  96      * Note that the 0th entry of the returned array should be the class\r
  97      * of the caller of this method. So if this method is implemented by\r
  98      * calling SecurityManager.getClassContext, this method must allocate\r
  99      * a new, shorter array to return.\r
 100      */\r
 101     public Class[] getClassContext();\r
 102     \r
 103     /**\r
 104      * Return the security context associated with the given class. \r
 105      * <p>\r
 106      * If <code>cl</code> is a class defined through a call to \r
 107      * SecuritySupport.defineClass, then return the security \r
 108      * context from that call. Otherwise return null.\r
 109      * @param cl a class potentially defined by defineClass\r
 110      * @return a security context object previously passed to defineClass\r
 111      */\r
 112     public Object getSecurityDomain(Class cl);\r
 113     \r
 114     /**\r
 115      * Return true iff the Java class with the given name should be exposed\r
 116      * to scripts.\r
 117      * <p>\r
 118      * An embedding may filter which Java classes are exposed through \r
 119      * LiveConnect to JavaScript scripts.\r
 120      * <p>\r
 121      * Due to the fact that there is no package reflection in Java,\r
 122      * this method will also be called with package names. There\r
 123      * is no way for Rhino to tell if "Packages.a.b" is a package name \r
 124      * or a class that doesn't exist. What Rhino does is attempt\r
 125      * to load each segment of "Packages.a.b.c": It first attempts to \r
 126      * load class "a", then attempts to load class "a.b", then\r
 127      * finally attempts to load class "a.b.c". On a Rhino installation \r
 128      * without any SecuritySupport set, and without any of the\r
 129      * above classes, the expression "Packages.a.b.c" will result in \r
 130      * a [JavaPackage a.b.c] and not an error.\r
 131      * <p>\r
 132      * With SecuritySupport supplied, Rhino will first call \r
 133      * visibleToScripts before attempting to look up the class name. If\r
 134      * visibleToScripts returns false, the class name lookup is not \r
 135      * performed and subsequent Rhino execution assumes the class is\r
 136      * not present. So for "java.lang.System.out.println" the lookup \r
 137      * of "java.lang.System" is skipped and thus Rhino assumes that\r
 138      * "java.lang.System" doesn't exist. So then for "java.lang.System.out",\r
 139      * Rhino attempts to load the class "java.lang.System.out" because \r
 140      * it assumes that "java.lang.System" is a package name.\r
 141      * <p>\r
 142      * @param fullClassName the full name of the class (including the package\r
 143      *                      name, with '.' as a delimiter). For example the \r
 144      *                      standard string class is "java.lang.String"\r
 145      * @return whether or not to reveal this class to scripts\r
 146      */\r
 147     public boolean visibleToScripts(String fullClassName);\r
 148 }\r