Class SecurityManager
The Security Manager is deprecated and subject to removal in a future release. There is no replacement for the Security Manager. See JEP 411 for discussion and alternatives.
The security manager is a class that allows applications to implement a security policy. It allows an application to determine, before performing a possibly unsafe or sensitive operation, what the operation is and whether it is being attempted in a security context that allows the operation to be performed. The application can allow or disallow the operation.
The SecurityManager class contains many methods with names that begin with the word check . These methods are called by various methods in the Java libraries before those methods perform certain potentially sensitive operations. The invocation of such a check method typically looks like this:
SecurityManager security = System.getSecurityManager(); if (security != null) < security.checkXXX(argument, . . . ); >
The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. A security manager routine simply returns if the operation is permitted, but throws a SecurityException if the operation is not permitted.
Setting a Security Manager
Environments using a security manager will typically set the security manager at startup. In the JDK implementation, this is done by setting the system property java.security.manager on the command line to the class name of the security manager. It can also be set to the empty String («») or the special token » default » to use the default java.lang.SecurityManager . If a class name is specified, it must be java.lang.SecurityManager or a public subclass and have a public no-arg constructor. The class is loaded by the built-in system class loader if it is not java.lang.SecurityManager . If the java.security.manager system property is not set, the default value is null , which means a security manager will not be set at startup.
The Java run-time may also allow, but is not required to allow, the security manager to be set dynamically by invoking the setSecurityManager method. In the JDK implementation, if the Java virtual machine is started with the java.security.manager system property set to the special token » allow «, then a security manager will not be set at startup but can be set dynamically. If the Java virtual machine is started with the java.security.manager system property not set or set to the special token » disallow «, then a security manager will not be set at startup and cannot be set dynamically (the setSecurityManager method will throw an UnsupportedOperationException ). Finally, if the java.security.manager system property is set to the class name of the security manager, or to the empty String («») or the special token » default «, then a security manager is set at startup (as described previously) and can also be subsequently replaced (or disabled) dynamically (subject to the policy of the currently installed security manager). The following table illustrates the behavior of the JDK implementation for the different settings of the java.security.manager system property:
| Property Value | The SecurityManager set at startup | System.setSecurityManager run-time behavior |
|---|---|---|
| null | None | Throws UnsupportedOperationException |
| empty String («») | java.lang.SecurityManager | Success or throws SecurityException if not permitted by the currently installed security manager |
| «default» | java.lang.SecurityManager | Success or throws SecurityException if not permitted by the currently installed security manager |
| «disallow» | None | Throws UnsupportedOperationException |
| «allow» | None | Success or throws SecurityException if not permitted by the currently installed security manager |
| a class name | the named class | Success or throws SecurityException if not permitted by the currently installed security manager |
The current security manager is returned by the getSecurityManager method.
Checking Permissions
The special method checkPermission(java.security.Permission) determines whether an access request indicated by a specified permission should be granted or denied. The default implementation calls
AccessController.checkPermission(perm);
If a requested access is allowed, checkPermission returns quietly. If denied, a SecurityException is thrown.
The default implementation of each of the other check methods in SecurityManager is to call the SecurityManager checkPermission method to determine if the calling thread has permission to perform the requested operation.
Note that the checkPermission method with just a single permission argument always performs security checks within the context of the currently executing thread. Sometimes a security check that should be made within a given context will actually need to be done from within a different context (for example, from within a worker thread). The getSecurityContext method and the checkPermission method that includes a context argument are provided for this situation. The getSecurityContext method returns a «snapshot» of the current calling context. (The default implementation returns an AccessControlContext object.) A sample call is the following:
Object context = null; SecurityManager sm = System.getSecurityManager(); if (sm != null) context = sm.getSecurityContext();
The checkPermission method that takes a context object in addition to a permission makes access decisions based on that context, rather than on that of the current execution thread. Code within a different context can thus call that method, passing the permission and the previously-saved context object. A sample call, using the SecurityManager sm obtained as in the previous example, is the following:
if (sm != null) sm.checkPermission(permission, context);
Permissions fall into these categories: File, Socket, Net, Security, Runtime, Property, AWT, Reflect, and Serializable. The classes managing these various permission categories are java.io.FilePermission , java.net.SocketPermission , java.net.NetPermission , java.security.SecurityPermission , java.lang.RuntimePermission , java.util.PropertyPermission , java.awt.AWTPermission , java.lang.reflect.ReflectPermission , and java.io.SerializablePermission .
All but the first two (FilePermission and SocketPermission) are subclasses of java.security.BasicPermission , which itself is an abstract subclass of the top-level class for permissions, which is java.security.Permission . BasicPermission defines the functionality needed for all permissions that contain a name that follows the hierarchical property naming convention (for example, «exitVM», «setFactory», «queuePrintJob», etc). An asterisk may appear at the end of the name, following a «.», or by itself, to signify a wildcard match. For example: «a.*» or «*» is valid, «*a» or «a*b» is not valid.
FilePermission and SocketPermission are subclasses of the top-level class for permissions ( java.security.Permission ). Classes like these that have a more complicated name syntax than that used by BasicPermission subclass directly from Permission rather than from BasicPermission. For example, for a java.io.FilePermission object, the permission name is the path name of a file (or directory).
Some of the permission classes have an «actions» list that tells the actions that are permitted for the object. For example, for a java.io.FilePermission object, the actions list (such as «read, write») specifies which actions are granted for the specified file (or for files in the specified directory).
Other permission classes are for «named» permissions — ones that contain a name but no actions list; you either have the named permission or you don’t.
Note: There is also a java.security.AllPermission permission that implies all permissions. It exists to simplify the work of system administrators who might need to perform multiple tasks that require all (or numerous) permissions.
See Permissions in the Java Development Kit (JDK) for permission-related information. This document includes a table listing the various SecurityManager check methods and the permission(s) the default implementation of each such method requires. It also contains a table of the methods that require permissions, and for each such method tells which permission it requires.
- ClassLoader
- SecurityException
- getSecurityManager
- setSecurityManager
- AccessController
- AccessControlContext
- AccessControlException
- Permission
- BasicPermission
- FilePermission
- SocketPermission
- PropertyPermission
- RuntimePermission
- Policy
- SecurityPermission
- ProtectionDomain
The Security Manager
A security manager is an object that defines a security policy for an application. This policy specifies actions that are unsafe or sensitive. Any actions not allowed by the security policy cause a SecurityException to be thrown. An application can also query its security manager to discover which actions are allowed.
Typically, a web applet runs with a security manager provided by the browser or Java Web Start plugin. Other kinds of applications normally run without a security manager, unless the application itself defines one. If no security manager is present, the application has no security policy and acts without restrictions.
This section explains how an application interacts with an existing security manager. For more detailed information, including information on how to design a security manager, refer to the Security Guide.
Interacting with the Security Manager
The security manager is an object of type SecurityManager ; to obtain a reference to this object, invoke System.getSecurityManager .
SecurityManager appsm = System.getSecurityManager();
If there is no security manager, this method returns null .
Once an application has a reference to the security manager object, it can request permission to do specific things. Many classes in the standard libraries do this. For example, System.exit , which terminates the Java virtual machine with an exit status, invokes SecurityManager.checkExit to ensure that the current thread has permission to shut down the application.
The SecurityManager class defines many other methods used to verify other kinds of operations. For example, SecurityManager.checkAccess verifies thread accesses, and SecurityManager.checkPropertyAccess verifies access to the specified property. Each operation or group of operations has its own checkXXX() method.
In addition, the set of checkXXX() methods represents the set of operations that are already subject to the protection of the security manager. Typically, an application does not have to directly invoke any checkXXX() methods.
Recognizing a Security Violation
Many actions that are routine without a security manager can throw a SecurityException when run with a security manager. This is true even when invoking a method that isn’t documented as throwing SecurityException . For example, consider the following code used to write to a file:
reader = new FileWriter("xanadu.txt"); In the absence of a security manager, this statement executes without error, provided xanadu.txt exists and is writeable. But suppose this statement is inserted in a web applet, which typically runs under a security manager that does not allow file output. The following error messages might result:
appletviewer fileApplet.html Exception in thread "AWT-EventQueue-1" java.security.AccessControlException: access denied (java.io.FilePermission xanadu.txt write) at java.security.AccessControlContext.checkPermission(AccessControlContext.java:323) at java.security.AccessController.checkPermission(AccessController.java:546) at java.lang.SecurityManager.checkPermission(SecurityManager.java:532) at java.lang.SecurityManager.checkWrite(SecurityManager.java:962) at java.io.FileOutputStream.(FileOutputStream.java:169) at java.io.FileOutputStream.(FileOutputStream.java:70) at java.io.FileWriter.(FileWriter.java:46) .
Note that the specific exception thrown in this case, java.security.AccessControlException , is a subclass of SecurityException .