View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.security;
27  
28  import sun.security.util.Debug;
29  import sun.reflect.CallerSensitive;
30  import sun.reflect.Reflection;
31  
32  /**
33   * <p> The AccessController class is used for access control operations
34   * and decisions.
35   *
36   * <p> More specifically, the AccessController class is used for
37   * three purposes:
38   *
39   * <ul>
40   * <li> to decide whether an access to a critical system
41   * resource is to be allowed or denied, based on the security policy
42   * currently in effect,
43   * <li>to mark code as being "privileged", thus affecting subsequent
44   * access determinations, and
45   * <li>to obtain a "snapshot" of the current calling context so
46   * access-control decisions from a different context can be made with
47   * respect to the saved context. </ul>
48   *
49   * <p> The {@link #checkPermission(Permission) checkPermission} method
50   * determines whether the access request indicated by a specified
51   * permission should be granted or denied. A sample call appears
52   * below. In this example, {@code checkPermission} will determine
53   * whether or not to grant "read" access to the file named "testFile" in
54   * the "/temp" directory.
55   *
56   * <pre>
57   *
58   * FilePermission perm = new FilePermission("/temp/testFile", "read");
59   * AccessController.checkPermission(perm);
60   *
61   * </pre>
62   *
63   * <p> If a requested access is allowed,
64   * {@code checkPermission} returns quietly. If denied, an
65   * AccessControlException is
66   * thrown. AccessControlException can also be thrown if the requested
67   * permission is of an incorrect type or contains an invalid value.
68   * Such information is given whenever possible.
69   *
70   * Suppose the current thread traversed m callers, in the order of caller 1
71   * to caller 2 to caller m. Then caller m invoked the
72   * {@code checkPermission} method.
73   * The {@code checkPermission} method determines whether access
74   * is granted or denied based on the following algorithm:
75   *
76   *  <pre> {@code
77   * for (int i = m; i > 0; i--) {
78   *
79   *     if (caller i's domain does not have the permission)
80   *         throw AccessControlException
81   *
82   *     else if (caller i is marked as privileged) {
83   *         if (a context was specified in the call to doPrivileged)
84   *             context.checkPermission(permission)
85   *         if (limited permissions were specified in the call to doPrivileged) {
86   *             for (each limited permission) {
87   *                 if (the limited permission implies the requested permission)
88   *                     return;
89   *             }
90   *         } else
91   *             return;
92   *     }
93   * }
94   *
95   * // Next, check the context inherited when the thread was created.
96   * // Whenever a new thread is created, the AccessControlContext at
97   * // that time is stored and associated with the new thread, as the
98   * // "inherited" context.
99   *
100  * inheritedContext.checkPermission(permission);
101  * }</pre>
102  *
103  * <p> A caller can be marked as being "privileged"
104  * (see {@link #doPrivileged(PrivilegedAction) doPrivileged} and below).
105  * When making access control decisions, the {@code checkPermission}
106  * method stops checking if it reaches a caller that
107  * was marked as "privileged" via a {@code doPrivileged}
108  * call without a context argument (see below for information about a
109  * context argument). If that caller's domain has the
110  * specified permission and at least one limiting permission argument (if any)
111  * implies the requested permission, no further checking is done and
112  * {@code checkPermission}
113  * returns quietly, indicating that the requested access is allowed.
114  * If that domain does not have the specified permission, an exception
115  * is thrown, as usual. If the caller's domain had the specified permission
116  * but it was not implied by any limiting permission arguments given in the call
117  * to {@code doPrivileged} then the permission checking continues
118  * until there are no more callers or another {@code doPrivileged}
119  * call matches the requested permission and returns normally.
120  *
121  * <p> The normal use of the "privileged" feature is as follows. If you
122  * don't need to return a value from within the "privileged" block, do
123  * the following:
124  *
125  *  <pre> {@code
126  * somemethod() {
127  *     ...normal code here...
128  *     AccessController.doPrivileged(new PrivilegedAction<Void>() {
129  *         public Void run() {
130  *             // privileged code goes here, for example:
131  *             System.loadLibrary("awt");
132  *             return null; // nothing to return
133  *         }
134  *     });
135  *     ...normal code here...
136  * }}</pre>
137  *
138  * <p>
139  * PrivilegedAction is an interface with a single method, named
140  * {@code run}.
141  * The above example shows creation of an implementation
142  * of that interface; a concrete implementation of the
143  * {@code run} method is supplied.
144  * When the call to {@code doPrivileged} is made, an
145  * instance of the PrivilegedAction implementation is passed
146  * to it. The {@code doPrivileged} method calls the
147  * {@code run} method from the PrivilegedAction
148  * implementation after enabling privileges, and returns the
149  * {@code run} method's return value as the
150  * {@code doPrivileged} return value (which is
151  * ignored in this example).
152  *
153  * <p> If you need to return a value, you can do something like the following:
154  *
155  *  <pre> {@code
156  * somemethod() {
157  *     ...normal code here...
158  *     String user = AccessController.doPrivileged(
159  *         new PrivilegedAction<String>() {
160  *         public String run() {
161  *             return System.getProperty("user.name");
162  *             }
163  *         });
164  *     ...normal code here...
165  * }}</pre>
166  *
167  * <p>If the action performed in your {@code run} method could
168  * throw a "checked" exception (those listed in the {@code throws} clause
169  * of a method), then you need to use the
170  * {@code PrivilegedExceptionAction} interface instead of the
171  * {@code PrivilegedAction} interface:
172  *
173  *  <pre> {@code
174  * somemethod() throws FileNotFoundException {
175  *     ...normal code here...
176  *     try {
177  *         FileInputStream fis = AccessController.doPrivileged(
178  *         new PrivilegedExceptionAction<FileInputStream>() {
179  *             public FileInputStream run() throws FileNotFoundException {
180  *                 return new FileInputStream("someFile");
181  *             }
182  *         });
183  *     } catch (PrivilegedActionException e) {
184  *         // e.getException() should be an instance of FileNotFoundException,
185  *         // as only "checked" exceptions will be "wrapped" in a
186  *         // PrivilegedActionException.
187  *         throw (FileNotFoundException) e.getException();
188  *     }
189  *     ...normal code here...
190  *  }}</pre>
191  *
192  * <p> Be *very* careful in your use of the "privileged" construct, and
193  * always remember to make the privileged code section as small as possible.
194  * You can pass {@code Permission} arguments to further limit the
195  * scope of the "privilege" (see below).
196  *
197  *
198  * <p> Note that {@code checkPermission} always performs security checks
199  * within the context of the currently executing thread.
200  * Sometimes a security check that should be made within a given context
201  * will actually need to be done from within a
202  * <i>different</i> context (for example, from within a worker thread).
203  * The {@link #getContext() getContext} method and
204  * AccessControlContext class are provided
205  * for this situation. The {@code getContext} method takes a "snapshot"
206  * of the current calling context, and places
207  * it in an AccessControlContext object, which it returns. A sample call is
208  * the following:
209  *
210  * <pre>
211  *
212  * AccessControlContext acc = AccessController.getContext()
213  *
214  * </pre>
215  *
216  * <p>
217  * AccessControlContext itself has a {@code checkPermission} method
218  * that makes access decisions based on the context <i>it</i> encapsulates,
219  * rather than that of the current execution thread.
220  * Code within a different context can thus call that method on the
221  * previously-saved AccessControlContext object. A sample call is the
222  * following:
223  *
224  * <pre>
225  *
226  * acc.checkPermission(permission)
227  *
228  * </pre>
229  *
230  * <p> There are also times where you don't know a priori which permissions
231  * to check the context against. In these cases you can use the
232  * doPrivileged method that takes a context. You can also limit the scope
233  * of the privileged code by passing additional {@code Permission}
234  * parameters.
235  *
236  *  <pre> {@code
237  * somemethod() {
238  *     AccessController.doPrivileged(new PrivilegedAction<Object>() {
239  *         public Object run() {
240  *             // Code goes here. Any permission checks within this
241  *             // run method will require that the intersection of the
242  *             // caller's protection domain and the snapshot's
243  *             // context have the desired permission. If a requested
244  *             // permission is not implied by the limiting FilePermission
245  *             // argument then checking of the thread continues beyond the
246  *             // caller of doPrivileged.
247  *         }
248  *     }, acc, new FilePermission("/temp/*", read));
249  *     ...normal code here...
250  * }}</pre>
251  * <p> Passing a limiting {@code Permission} argument of an instance of
252  * {@code AllPermission} is equivalent to calling the equivalent
253  * {@code doPrivileged} method without limiting {@code Permission}
254  * arguments. Passing a zero length array of {@code Permission} disables
255  * the code privileges so that checking always continues beyond the caller of
256  * that {@code doPrivileged} method.
257  *
258  * @see AccessControlContext
259  *
260  * @author Li Gong
261  * @author Roland Schemers
262  */
263 
264 public final class AccessController {
265 
266     /**
267      * Don't allow anyone to instantiate an AccessController
268      */
269     private AccessController() { }
270 
271     /**
272      * Performs the specified {@code PrivilegedAction} with privileges
273      * enabled. The action is performed with <i>all</i> of the permissions
274      * possessed by the caller's protection domain.
275      *
276      * <p> If the action's {@code run} method throws an (unchecked)
277      * exception, it will propagate through this method.
278      *
279      * <p> Note that any DomainCombiner associated with the current
280      * AccessControlContext will be ignored while the action is performed.
281      *
282      * @param <T> the type of the value returned by the PrivilegedAction's
283      *                  {@code run} method.
284      *
285      * @param action the action to be performed.
286      *
287      * @return the value returned by the action's {@code run} method.
288      *
289      * @exception NullPointerException if the action is {@code null}
290      *
291      * @see #doPrivileged(PrivilegedAction,AccessControlContext)
292      * @see #doPrivileged(PrivilegedExceptionAction)
293      * @see #doPrivilegedWithCombiner(PrivilegedAction)
294      * @see java.security.DomainCombiner
295      */
296 
297     @CallerSensitive
298     public static native <T> T doPrivileged(PrivilegedAction<T> action);
299 
300     /**
301      * Performs the specified {@code PrivilegedAction} with privileges
302      * enabled. The action is performed with <i>all</i> of the permissions
303      * possessed by the caller's protection domain.
304      *
305      * <p> If the action's {@code run} method throws an (unchecked)
306      * exception, it will propagate through this method.
307      *
308      * <p> This method preserves the current AccessControlContext's
309      * DomainCombiner (which may be null) while the action is performed.
310      *
311      * @param <T> the type of the value returned by the PrivilegedAction's
312      *                  {@code run} method.
313      *
314      * @param action the action to be performed.
315      *
316      * @return the value returned by the action's {@code run} method.
317      *
318      * @exception NullPointerException if the action is {@code null}
319      *
320      * @see #doPrivileged(PrivilegedAction)
321      * @see java.security.DomainCombiner
322      *
323      * @since 1.6
324      */
325     @CallerSensitive
326     public static <T> T doPrivilegedWithCombiner(PrivilegedAction<T> action) {
327         AccessControlContext acc = getStackAccessControlContext();
328         if (acc == null) {
329             return AccessController.doPrivileged(action);
330         }
331         DomainCombiner dc = acc.getAssignedCombiner();
332         return AccessController.doPrivileged(action,
333                                              preserveCombiner(dc, Reflection.getCallerClass()));
334     }
335 
336 
337     /**
338      * Performs the specified {@code PrivilegedAction} with privileges
339      * enabled and restricted by the specified {@code AccessControlContext}.
340      * The action is performed with the intersection of the permissions
341      * possessed by the caller's protection domain, and those possessed
342      * by the domains represented by the specified {@code AccessControlContext}.
343      * <p>
344      * If the action's {@code run} method throws an (unchecked) exception,
345      * it will propagate through this method.
346      * <p>
347      * If a security manager is installed and the specified
348      * {@code AccessControlContext} was not created by system code and the
349      * caller's {@code ProtectionDomain} has not been granted the
350      * {@literal "createAccessControlContext"}
351      * {@link java.security.SecurityPermission}, then the action is performed
352      * with no permissions.
353      *
354      * @param <T> the type of the value returned by the PrivilegedAction's
355      *                  {@code run} method.
356      * @param action the action to be performed.
357      * @param context an <i>access control context</i>
358      *                representing the restriction to be applied to the
359      *                caller's domain's privileges before performing
360      *                the specified action.  If the context is
361      *                {@code null}, then no additional restriction is applied.
362      *
363      * @return the value returned by the action's {@code run} method.
364      *
365      * @exception NullPointerException if the action is {@code null}
366      *
367      * @see #doPrivileged(PrivilegedAction)
368      * @see #doPrivileged(PrivilegedExceptionAction,AccessControlContext)
369      */
370     @CallerSensitive
371     public static native <T> T doPrivileged(PrivilegedAction<T> action,
372                                             AccessControlContext context);
373 
374 
375     /**
376      * Performs the specified {@code PrivilegedAction} with privileges
377      * enabled and restricted by the specified
378      * {@code AccessControlContext} and with a privilege scope limited
379      * by specified {@code Permission} arguments.
380      *
381      * The action is performed with the intersection of the permissions
382      * possessed by the caller's protection domain, and those possessed
383      * by the domains represented by the specified
384      * {@code AccessControlContext}.
385      * <p>
386      * If the action's {@code run} method throws an (unchecked) exception,
387      * it will propagate through this method.
388      * <p>
389      * If a security manager is installed and the specified
390      * {@code AccessControlContext} was not created by system code and the
391      * caller's {@code ProtectionDomain} has not been granted the
392      * {@literal "createAccessControlContext"}
393      * {@link java.security.SecurityPermission}, then the action is performed
394      * with no permissions.
395      *
396      * @param <T> the type of the value returned by the PrivilegedAction's
397      *                  {@code run} method.
398      * @param action the action to be performed.
399      * @param context an <i>access control context</i>
400      *                representing the restriction to be applied to the
401      *                caller's domain's privileges before performing
402      *                the specified action.  If the context is
403      *                {@code null},
404      *                then no additional restriction is applied.
405      * @param perms the {@code Permission} arguments which limit the
406      *              scope of the caller's privileges. The number of arguments
407      *              is variable.
408      *
409      * @return the value returned by the action's {@code run} method.
410      *
411      * @throws NullPointerException if action or perms or any element of
412      *         perms is {@code null}
413      *
414      * @see #doPrivileged(PrivilegedAction)
415      * @see #doPrivileged(PrivilegedExceptionAction,AccessControlContext)
416      *
417      * @since 1.8
418      */
419     @CallerSensitive
420     public static <T> T doPrivileged(PrivilegedAction<T> action,
421         AccessControlContext context, Permission... perms) {
422 
423         AccessControlContext parent = getContext();
424         if (perms == null) {
425             throw new NullPointerException("null permissions parameter");
426         }
427         Class <?> caller = Reflection.getCallerClass();
428         return AccessController.doPrivileged(action, createWrapper(null,
429             caller, parent, context, perms));
430     }
431 
432 
433     /**
434      * Performs the specified {@code PrivilegedAction} with privileges
435      * enabled and restricted by the specified
436      * {@code AccessControlContext} and with a privilege scope limited
437      * by specified {@code Permission} arguments.
438      *
439      * The action is performed with the intersection of the permissions
440      * possessed by the caller's protection domain, and those possessed
441      * by the domains represented by the specified
442      * {@code AccessControlContext}.
443      * <p>
444      * If the action's {@code run} method throws an (unchecked) exception,
445      * it will propagate through this method.
446      *
447      * <p> This method preserves the current AccessControlContext's
448      * DomainCombiner (which may be null) while the action is performed.
449      * <p>
450      * If a security manager is installed and the specified
451      * {@code AccessControlContext} was not created by system code and the
452      * caller's {@code ProtectionDomain} has not been granted the
453      * {@literal "createAccessControlContext"}
454      * {@link java.security.SecurityPermission}, then the action is performed
455      * with no permissions.
456      *
457      * @param <T> the type of the value returned by the PrivilegedAction's
458      *                  {@code run} method.
459      * @param action the action to be performed.
460      * @param context an <i>access control context</i>
461      *                representing the restriction to be applied to the
462      *                caller's domain's privileges before performing
463      *                the specified action.  If the context is
464      *                {@code null},
465      *                then no additional restriction is applied.
466      * @param perms the {@code Permission} arguments which limit the
467      *              scope of the caller's privileges. The number of arguments
468      *              is variable.
469      *
470      * @return the value returned by the action's {@code run} method.
471      *
472      * @throws NullPointerException if action or perms or any element of
473      *         perms is {@code null}
474      *
475      * @see #doPrivileged(PrivilegedAction)
476      * @see #doPrivileged(PrivilegedExceptionAction,AccessControlContext)
477      * @see java.security.DomainCombiner
478      *
479      * @since 1.8
480      */
481     @CallerSensitive
482     public static <T> T doPrivilegedWithCombiner(PrivilegedAction<T> action,
483         AccessControlContext context, Permission... perms) {
484 
485         AccessControlContext parent = getContext();
486         DomainCombiner dc = parent.getCombiner();
487         if (dc == null && context != null) {
488             dc = context.getCombiner();
489         }
490         if (perms == null) {
491             throw new NullPointerException("null permissions parameter");
492         }
493         Class <?> caller = Reflection.getCallerClass();
494         return AccessController.doPrivileged(action, createWrapper(dc, caller,
495             parent, context, perms));
496     }
497 
498     /**
499      * Performs the specified {@code PrivilegedExceptionAction} with
500      * privileges enabled.  The action is performed with <i>all</i> of the
501      * permissions possessed by the caller's protection domain.
502      *
503      * <p> If the action's {@code run} method throws an <i>unchecked</i>
504      * exception, it will propagate through this method.
505      *
506      * <p> Note that any DomainCombiner associated with the current
507      * AccessControlContext will be ignored while the action is performed.
508      *
509      * @param <T> the type of the value returned by the
510      *                  PrivilegedExceptionAction's {@code run} method.
511      *
512      * @param action the action to be performed
513      *
514      * @return the value returned by the action's {@code run} method
515      *
516      * @exception PrivilegedActionException if the specified action's
517      *         {@code run} method threw a <i>checked</i> exception
518      * @exception NullPointerException if the action is {@code null}
519      *
520      * @see #doPrivileged(PrivilegedAction)
521      * @see #doPrivileged(PrivilegedExceptionAction,AccessControlContext)
522      * @see #doPrivilegedWithCombiner(PrivilegedExceptionAction)
523      * @see java.security.DomainCombiner
524      */
525     @CallerSensitive
526     public static native <T> T
527         doPrivileged(PrivilegedExceptionAction<T> action)
528         throws PrivilegedActionException;
529 
530 
531     /**
532      * Performs the specified {@code PrivilegedExceptionAction} with
533      * privileges enabled.  The action is performed with <i>all</i> of the
534      * permissions possessed by the caller's protection domain.
535      *
536      * <p> If the action's {@code run} method throws an <i>unchecked</i>
537      * exception, it will propagate through this method.
538      *
539      * <p> This method preserves the current AccessControlContext's
540      * DomainCombiner (which may be null) while the action is performed.
541      *
542      * @param <T> the type of the value returned by the
543      *                  PrivilegedExceptionAction's {@code run} method.
544      *
545      * @param action the action to be performed.
546      *
547      * @return the value returned by the action's {@code run} method
548      *
549      * @exception PrivilegedActionException if the specified action's
550      *         {@code run} method threw a <i>checked</i> exception
551      * @exception NullPointerException if the action is {@code null}
552      *
553      * @see #doPrivileged(PrivilegedAction)
554      * @see #doPrivileged(PrivilegedExceptionAction,AccessControlContext)
555      * @see java.security.DomainCombiner
556      *
557      * @since 1.6
558      */
559     @CallerSensitive
560     public static <T> T doPrivilegedWithCombiner(PrivilegedExceptionAction<T> action)
561         throws PrivilegedActionException
562     {
563         AccessControlContext acc = getStackAccessControlContext();
564         if (acc == null) {
565             return AccessController.doPrivileged(action);
566         }
567         DomainCombiner dc = acc.getAssignedCombiner();
568         return AccessController.doPrivileged(action,
569                                              preserveCombiner(dc, Reflection.getCallerClass()));
570     }
571 
572     /**
573      * preserve the combiner across the doPrivileged call
574      */
575     private static AccessControlContext preserveCombiner(DomainCombiner combiner,
576                                                          Class<?> caller)
577     {
578         return createWrapper(combiner, caller, null, null, null);
579     }
580 
581     /**
582      * Create a wrapper to contain the limited privilege scope data.
583      */
584     private static AccessControlContext
585         createWrapper(DomainCombiner combiner, Class<?> caller,
586                       AccessControlContext parent, AccessControlContext context,
587                       Permission[] perms)
588     {
589         ProtectionDomain callerPD = getCallerPD(caller);
590         // check if caller is authorized to create context
591         if (context != null && !context.isAuthorized() &&
592             System.getSecurityManager() != null &&
593             !callerPD.impliesCreateAccessControlContext())
594         {
595             ProtectionDomain nullPD = new ProtectionDomain(null, null);
596             return new AccessControlContext(new ProtectionDomain[] { nullPD });
597         } else {
598             return new AccessControlContext(callerPD, combiner, parent,
599                                             context, perms);
600         }
601     }
602 
603     private static ProtectionDomain getCallerPD(final Class <?> caller) {
604         ProtectionDomain callerPd = doPrivileged
605             (new PrivilegedAction<ProtectionDomain>() {
606             public ProtectionDomain run() {
607                 return caller.getProtectionDomain();
608             }
609         });
610 
611         return callerPd;
612     }
613 
614     /**
615      * Performs the specified {@code PrivilegedExceptionAction} with
616      * privileges enabled and restricted by the specified
617      * {@code AccessControlContext}.  The action is performed with the
618      * intersection of the permissions possessed by the caller's
619      * protection domain, and those possessed by the domains represented by the
620      * specified {@code AccessControlContext}.
621      * <p>
622      * If the action's {@code run} method throws an <i>unchecked</i>
623      * exception, it will propagate through this method.
624      * <p>
625      * If a security manager is installed and the specified
626      * {@code AccessControlContext} was not created by system code and the
627      * caller's {@code ProtectionDomain} has not been granted the
628      * {@literal "createAccessControlContext"}
629      * {@link java.security.SecurityPermission}, then the action is performed
630      * with no permissions.
631      *
632      * @param <T> the type of the value returned by the
633      *                  PrivilegedExceptionAction's {@code run} method.
634      * @param action the action to be performed
635      * @param context an <i>access control context</i>
636      *                representing the restriction to be applied to the
637      *                caller's domain's privileges before performing
638      *                the specified action.  If the context is
639      *                {@code null}, then no additional restriction is applied.
640      *
641      * @return the value returned by the action's {@code run} method
642      *
643      * @exception PrivilegedActionException if the specified action's
644      *         {@code run} method threw a <i>checked</i> exception
645      * @exception NullPointerException if the action is {@code null}
646      *
647      * @see #doPrivileged(PrivilegedAction)
648      * @see #doPrivileged(PrivilegedAction,AccessControlContext)
649      */
650     @CallerSensitive
651     public static native <T> T
652         doPrivileged(PrivilegedExceptionAction<T> action,
653                      AccessControlContext context)
654         throws PrivilegedActionException;
655 
656 
657     /**
658      * Performs the specified {@code PrivilegedExceptionAction} with
659      * privileges enabled and restricted by the specified
660      * {@code AccessControlContext} and with a privilege scope limited by
661      * specified {@code Permission} arguments.
662      *
663      * The action is performed with the intersection of the permissions
664      * possessed by the caller's protection domain, and those possessed
665      * by the domains represented by the specified
666      * {@code AccessControlContext}.
667      * <p>
668      * If the action's {@code run} method throws an (unchecked) exception,
669      * it will propagate through this method.
670      * <p>
671      * If a security manager is installed and the specified
672      * {@code AccessControlContext} was not created by system code and the
673      * caller's {@code ProtectionDomain} has not been granted the
674      * {@literal "createAccessControlContext"}
675      * {@link java.security.SecurityPermission}, then the action is performed
676      * with no permissions.
677      *
678      * @param <T> the type of the value returned by the
679      *                  PrivilegedExceptionAction's {@code run} method.
680      * @param action the action to be performed.
681      * @param context an <i>access control context</i>
682      *                representing the restriction to be applied to the
683      *                caller's domain's privileges before performing
684      *                the specified action.  If the context is
685      *                {@code null},
686      *                then no additional restriction is applied.
687      * @param perms the {@code Permission} arguments which limit the
688      *              scope of the caller's privileges. The number of arguments
689      *              is variable.
690      *
691      * @return the value returned by the action's {@code run} method.
692      *
693      * @throws PrivilegedActionException if the specified action's
694      *         {@code run} method threw a <i>checked</i> exception
695      * @throws NullPointerException if action or perms or any element of
696      *         perms is {@code null}
697      *
698      * @see #doPrivileged(PrivilegedAction)
699      * @see #doPrivileged(PrivilegedAction,AccessControlContext)
700      *
701      * @since 1.8
702      */
703     @CallerSensitive
704     public static <T> T doPrivileged(PrivilegedExceptionAction<T> action,
705                                      AccessControlContext context, Permission... perms)
706         throws PrivilegedActionException
707     {
708         AccessControlContext parent = getContext();
709         if (perms == null) {
710             throw new NullPointerException("null permissions parameter");
711         }
712         Class <?> caller = Reflection.getCallerClass();
713         return AccessController.doPrivileged(action, createWrapper(null, caller, parent, context, perms));
714     }
715 
716 
717     /**
718      * Performs the specified {@code PrivilegedExceptionAction} with
719      * privileges enabled and restricted by the specified
720      * {@code AccessControlContext} and with a privilege scope limited by
721      * specified {@code Permission} arguments.
722      *
723      * The action is performed with the intersection of the permissions
724      * possessed by the caller's protection domain, and those possessed
725      * by the domains represented by the specified
726      * {@code AccessControlContext}.
727      * <p>
728      * If the action's {@code run} method throws an (unchecked) exception,
729      * it will propagate through this method.
730      *
731      * <p> This method preserves the current AccessControlContext's
732      * DomainCombiner (which may be null) while the action is performed.
733      * <p>
734      * If a security manager is installed and the specified
735      * {@code AccessControlContext} was not created by system code and the
736      * caller's {@code ProtectionDomain} has not been granted the
737      * {@literal "createAccessControlContext"}
738      * {@link java.security.SecurityPermission}, then the action is performed
739      * with no permissions.
740      *
741      * @param <T> the type of the value returned by the
742      *                  PrivilegedExceptionAction's {@code run} method.
743      * @param action the action to be performed.
744      * @param context an <i>access control context</i>
745      *                representing the restriction to be applied to the
746      *                caller's domain's privileges before performing
747      *                the specified action.  If the context is
748      *                {@code null},
749      *                then no additional restriction is applied.
750      * @param perms the {@code Permission} arguments which limit the
751      *              scope of the caller's privileges. The number of arguments
752      *              is variable.
753      *
754      * @return the value returned by the action's {@code run} method.
755      *
756      * @throws PrivilegedActionException if the specified action's
757      *         {@code run} method threw a <i>checked</i> exception
758      * @throws NullPointerException if action or perms or any element of
759      *         perms is {@code null}
760      *
761      * @see #doPrivileged(PrivilegedAction)
762      * @see #doPrivileged(PrivilegedAction,AccessControlContext)
763      * @see java.security.DomainCombiner
764      *
765      * @since 1.8
766      */
767     @CallerSensitive
768     public static <T> T doPrivilegedWithCombiner(PrivilegedExceptionAction<T> action,
769                                                  AccessControlContext context,
770                                                  Permission... perms)
771         throws PrivilegedActionException
772     {
773         AccessControlContext parent = getContext();
774         DomainCombiner dc = parent.getCombiner();
775         if (dc == null && context != null) {
776             dc = context.getCombiner();
777         }
778         if (perms == null) {
779             throw new NullPointerException("null permissions parameter");
780         }
781         Class <?> caller = Reflection.getCallerClass();
782         return AccessController.doPrivileged(action, createWrapper(dc, caller,
783             parent, context, perms));
784     }
785 
786     /**
787      * Returns the AccessControl context. i.e., it gets
788      * the protection domains of all the callers on the stack,
789      * starting at the first class with a non-null
790      * ProtectionDomain.
791      *
792      * @return the access control context based on the current stack or
793      *         null if there was only privileged system code.
794      */
795 
796     private static native AccessControlContext getStackAccessControlContext();
797 
798 
799     /**
800      * Returns the "inherited" AccessControl context. This is the context
801      * that existed when the thread was created. Package private so
802      * AccessControlContext can use it.
803      */
804 
805     static native AccessControlContext getInheritedAccessControlContext();
806 
807     /**
808      * This method takes a "snapshot" of the current calling context, which
809      * includes the current Thread's inherited AccessControlContext and any
810      * limited privilege scope, and places it in an AccessControlContext object.
811      * This context may then be checked at a later point, possibly in another thread.
812      *
813      * @see AccessControlContext
814      *
815      * @return the AccessControlContext based on the current context.
816      */
817 
818     public static AccessControlContext getContext()
819     {
820         AccessControlContext acc = getStackAccessControlContext();
821         if (acc == null) {
822             // all we had was privileged system code. We don't want
823             // to return null though, so we construct a real ACC.
824             return new AccessControlContext(null, true);
825         } else {
826             return acc.optimize();
827         }
828     }
829 
830     /**
831      * Determines whether the access request indicated by the
832      * specified permission should be allowed or denied, based on
833      * the current AccessControlContext and security policy.
834      * This method quietly returns if the access request
835      * is permitted, or throws an AccessControlException otherwise. The
836      * getPermission method of the AccessControlException returns the
837      * {@code perm} Permission object instance.
838      *
839      * @param perm the requested permission.
840      *
841      * @exception AccessControlException if the specified permission
842      *            is not permitted, based on the current security policy.
843      * @exception NullPointerException if the specified permission
844      *            is {@code null} and is checked based on the
845      *            security policy currently in effect.
846      */
847 
848     public static void checkPermission(Permission perm)
849         throws AccessControlException
850     {
851         //System.err.println("checkPermission "+perm);
852         //Thread.currentThread().dumpStack();
853 
854         if (perm == null) {
855             throw new NullPointerException("permission can't be null");
856         }
857 
858         AccessControlContext stack = getStackAccessControlContext();
859         // if context is null, we had privileged system code on the stack.
860         if (stack == null) {
861             Debug debug = AccessControlContext.getDebug();
862             boolean dumpDebug = false;
863             if (debug != null) {
864                 dumpDebug = !Debug.isOn("codebase=");
865                 dumpDebug &= !Debug.isOn("permission=") ||
866                     Debug.isOn("permission=" + perm.getClass().getCanonicalName());
867             }
868 
869             if (dumpDebug && Debug.isOn("stack")) {
870                 Thread.dumpStack();
871             }
872 
873             if (dumpDebug && Debug.isOn("domain")) {
874                 debug.println("domain (context is null)");
875             }
876 
877             if (dumpDebug) {
878                 debug.println("access allowed "+perm);
879             }
880             return;
881         }
882 
883         AccessControlContext acc = stack.optimize();
884         acc.checkPermission(perm);
885     }
886 }