1 /* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
\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
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
13 * The Original Code is Rhino code, released
\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
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
38 package org.mozilla.javascript;
\r
41 * This class describes the support needed to implement security.
\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
55 * These three pieces of functionality are encapsulated in the
\r
56 * SecuritySupport class.
\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
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
67 public interface SecuritySupport {
\r
70 * Define and load a Java class.
\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
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
85 public Class defineClass(String name, byte[] data,
\r
86 Object securityDomain);
\r
89 * Get the current class Context.
\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
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
101 public Class[] getClassContext();
\r
104 * Return the security context associated with the given class.
\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
112 public Object getSecurityDomain(Class cl);
\r
115 * Return true iff the Java class with the given name should be exposed
\r
118 * An embedding may filter which Java classes are exposed through
\r
119 * LiveConnect to JavaScript scripts.
\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
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
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
147 public boolean visibleToScripts(String fullClassName);
\r