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.

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 "disallow" then a security manager will not be set at startup and cannot be set dynamically (the setSecurityManager method will throw an UnsupportedOperationException). If the java.security.manager system property is not set or is set to the special token "allow", then a security manager will not be set at startup but can be set dynamically. 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	Success or throws SecurityException if not permitted by the currently installed security manager
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	Always 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

A future release of the JDK may change the default value of the java.security.manager system property to "disallow".

The current security manager is returned by the getSecurityManager method.

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.