3Permissions and Security Policy

3.1The Permission Classes

The permission classes represent access to system resources. The java.security.Permission class is an abstract class and is subclassed, as appropriate, to represent specific accesses.

As an example of a permission, the following code can be used to produce a permission to read the file named "abc" in the /tmp directory:

perm = new java.io.FilePermission("/tmp/abc", "read");

New permissions are subclassed either from the Permission class or one of its subclasses, such as java.security.BasicPermission. Subclassed permissions (other than BasicPermission) generally belong to their own packages. Thus, FilePermission is found in the java.io package.

A crucial abstract method that needs to be implemented for each new class of permission is theimpliesmethod. Basically, "a implies b" means that if one is granted permission "a", one is naturally granted permission "b". This is important when making access control decisions.

Associated with the abstract class java.security.Permission are the abstract class named java.security.PermissionCollection and the final class java.security.Permissions.

Class java.security.PermissionCollection represents a collection (i.e., a set that allows duplicates) of Permission objects for a single category (such as file permissions), for ease of grouping. In cases where permissions can be added to the PermissionCollection object in any order, such as for file permissions, it is crucial that the PermissionCollection object ensure that the correct semantics are followed when theimpliesfunction is called.

Class java.security.Permissions represents a collection of collections of Permission objects, or in other words, a super collection of heterogeneous permissions.

Applications are free to add new categories of permissions that the system supports. How to add such application-specific permissions is discussed later in this document.

Now we describe the syntax and semantics of all built-in permissions.

3.1.1 java.security.Permission

This abstract class is the ancestor of all permissions. It defines the essential functionalities required for all permissions.

Each permission instance is typically generated by passing one or more string parameters to the constructor. In a common case with two parameters, the first parameter is usually "the name of the target" (such as the name of a file for which the permission is aimed), and the second parameter is the action (such as "read" action on a file). Generally, a set of actions can be specified together as a comma-separated composite string.

3.1.2 java.security.PermissionCollection

This class holds a homogeneous collection of permissions. In other words, each instance of the class holds only permissions of the same type.

3.1.3 java.security.Permissions

This class is designed to hold a heterogeneous collection of permissions. Basically, it is a collection of java.security.PermissionCollection objects.

3.1.4 java.security.UnresolvedPermission

Recall that the internal state of a security policy is normally expressed by the permission objects that are associated with each code source. Given the dynamic nature of Java technology, however, it is possible that when the policy is initialized the actual code that implements a particular permission class has not yet been loaded and defined in the Java application environment. For example, a referenced permission class may be in a JAR file that will later be loaded.

The UnresolvedPermission class is used to hold such "unresolved" permissions. Similarly, the class java.security.UnresolvedPermissionCollection stores a collection of UnresolvedPermission permissions.

During access control checking on a permission of a type that was previously unresolved, but whose class has since been loaded, the unresolved permission is "resolved" and the appropriate access control decision is made. That is, a new object of the appropriate class type is instantiated, if possible, based on the information in the UnresolvedPermission. This new object replaces the UnresolvedPermission, which is removed.

If the permission is still unresolvable at this time, the permission is considered invalid, as if it is never granted in a security policy.

3.1.5 java.io.FilePermission

The targets for this class can be specified in the following ways, where directory and file names are strings that cannot contain white spaces.

file

directory (same as directory/)

directory/file

directory/* (all files in this directory)

* (all files in the current directory)

directory/- (all files in the file system under this directory)

- (all files in the file system under the current directory)

"<<ALL FILES>>" (all files in the file system)

Note that "<>" is a special string denoting all files in the system. On a Unix system, this includes all files under the root directory. On an MS-DOS system, this includes all files on all drives.

The actions are:read,write,delete, andexecute. Therefore, the following are valid code samples for creating file permissions:

import java.io.FilePermission;

FilePermission p = new FilePermission("myfile", "read,write");

FilePermission p = new FilePermission("/home/gong/", "read");

FilePermission p = new FilePermission("/tmp/mytmp", "read,delete");

FilePermission p = new FilePermission("/bin/*", "execute");

FilePermission p = new FilePermission("*", "read");

FilePermission p = new FilePermission("/-", "read,execute");

FilePermission p = new FilePermission("-", "read,execute");

FilePermission p = new FilePermission("<<ALL FILES>>", "read");

>Theimpliesmethod in this class correctly interprets the file system. For example, FilePermission("/-", "read,execute") implies FilePermission("/home/gong/public_html/index.html", "read"), and FilePermission("bin/*", "execute") implies FilePermission("bin/emacs19.31", "execute").

Note: Most of these strings are given in platform-dependent format. For example, to represent read access to the file named "foo" in the "temp" directory on the C drive of a Windows system, you would use

FilePermission p = new FilePermission("c:\\temp\\foo", "read");

The double backslashes are necessary to represent a single backslash because the strings are processed by a tokenizer (java.io.StreamTokenizer), which allows "\" to be used as an escape string (e.g., "\n" to indicate a new line) and which thus requires two backslashes to indicate a single backslash. After the tokenizer has processed the above FilePermission target string, converting double backslashes to single backslashes, the end result is the actual path

"c:\temp\foo"

It is necessary that the strings be given in platform-dependent format until there is a universal file description language. Note also that the use of meta symbols such as "*" and "-" prevents the use of specific file names. We think this is a small limitation that can be tolerated for the moment. Finally, note that "/-" and "<>" are the same target on Unix systems in that they both refer to the entire file system. (They can refer to multiple file systems if they are all available). The two targets are potentially different on other operating systems, such as MS Windows and MacOS.

Also note that a target name that specifies just a directory, with a "read" action, as in

FilePermission p = new FilePermission("/home/gong/", "read");

means you are only giving permission to list the files in that directory, not read any of them. To allow read access to files, you must specify either an explicit file name, or an "*" or "-", as in

FilePermission p = new FilePermission("/home/gong/myfile", "read");

FilePermission p = new FilePermission("/home/gong/*", "read");

FilePermission p = new FilePermission("/home/gong/-", "read");

And finally, note that code always automatically has permission to read files from its same (URL) location, and subdirectories of that location; it does not need explicit permission to do so.

3.1.6 java.net.SocketPermission

This class represents access to a network via sockets. The target for this class can be given as "hostname:port_range", where hostname can be given in the following ways:

hostname (a single host)

IP address (a single host)

localhost (the local machine)

"" (equivalent to "localhost")

hostname.domain (a single host within the domain)

hostname.subdomain.domain

*.domain (all hosts in the domain)

*.subdomain.domain

* (all hosts)

That is, the host is expressed as a DNS name, as a numerical IP address, as "localhost" (for the local machine) or as "" (which is equivalent to specifying "localhost").

The wildcard "*" may be included once in a DNS name host specification. If it is included, it must be in the leftmost position, as in "*.sun.com".

The port_range can be given as follows:

N (a single port)

N- (all ports numbered N and above)

-N (all ports numbered N and below)

N1-N2 (all ports between N1 and N2, inclusive)

Here N, N1, and N2 are non-negative integers ranging from 0 to 65535 (2^16-1).

The actions on sockets areaccept,connect,listen, andresolve(which is basically DNS lookup). Note that implicitly, the action "resolve" is implied by "accept", "connect", and "listen" -- i.e., those who can listen or accept incoming connections from or initiate out-going connections to a host should be able to look up the name of the remote host.

Below are some examples of socket permissions.

import java.net.SocketPermission;

SocketPermission p = new SocketPermission("java.example.com","accept");

p = new SocketPermission("192.0.2.99","accept");

p = new SocketPermission("*.com","connect");

p = new SocketPermission("*.example.com:80","accept");

p = new SocketPermission("*.example.com:-1023","accept");

p = new SocketPermission("*.example.com:1024-","connect");

p = new SocketPermission("java.example.com:8000-9000",

"connect,accept");

p = new SocketPermission("localhost:1024-",

"accept,connect,listen");

Note that SocketPermission("java.example.com:80,8080","accept") and SocketPermission("java.example.com,javasun.example.com","accept") are not valid socket permissions.

Moreover, becauselistenis an action that applies only to ports on the local host, whereasacceptis an action that applies to ports on both the local and remote host, both actions are necessary.

3.1.7 java.security.BasicPermission

The BasicPermission class extends the Permission class. It can be used as the base class for permissions that want to follow the same naming convention as BasicPermission (see below).

The name for a BasicPermission is the name of the given permission (for example, "exitVM", "setFactory", "queuePrintJob", etc). The naming convention follows the hierarchical property naming convention. An asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "java.*" or "*" is valid, "*java" or "a*b" is not valid.

The action string (inherited from Permission) is unused.Thus, BasicPermission is commonly used as the base class for "named" permissions (ones that contain a name but no actions list; you either have the named permission or you don't.) Subclasses may implement actions on top of BasicPermission, if desired.

Some of the BasicPermission subclasses are java.lang.RuntimePermission, java.security.SecurityPermission, java.util.PropertyPermission, and java.net.NetPermission.

3.1.8 java.util.PropertyPermission

The targets for this class are basically the names of Java properties as set in various property files. Examples are the "java.home" and "os.name" properties. Targets can be specified as "*" (any property), "a.*" (any property whose name has a prefix "a."), "a.b.*", and so on. Note that the wildcard can occur only once and can only be at the rightmost position.

This is one of the BasicPermission subclasses that implements actions on top of BasicPermission. The actions are read and write. Their meaning is defined as follows: "read" permission allows thegetPropertymethod in java.lang.System to be called to get the property value, and "write" permission allows thesetPropertymethod to be called to set the property value.

3.1.9 java.lang.RuntimePermission

The target for a RuntimePermission can be represented by any string, and there is no action associated with the targets. For example, RuntimePermission("exitVM") denotes the permission to exit the Java Virtual Machine.

The target names are:

createClassLoader

getClassLoader

setContextClassLoader

setSecurityManager

createSecurityManager

exitVM

setFactory

setIO

modifyThread

stopThread

modifyThreadGroup

getProtectionDomain

readFileDescriptor

writeFileDescriptor

loadLibrary.{library name}

accessClassInPackage.{package name}

defineClassInPackage.{package name}

accessDeclaredMembers.{class name}

queuePrintJob

3.1.10 java.awt.AWTPermission

This is in the same spirit as the RuntimePermission; it's a permission without actions. The targets for this class are:

accessClipboard

accessEventQueue

listenToAllAWTEvents

showWindowWithoutWarningBanner

3.1.11 java.net.NetPermission

This class contains the following targets and no actions:

requestPasswordAuthentication

setDefaultAuthenticator

specifyStreamHandler

3.1.12 java.lang.reflect.ReflectPermission

This is the Permission class for reflective operations. A ReflectPermission is a named permission (like RuntimePermission) and has no actions. The only name currently defined is

suppressAccessChecks

which allows suppressing the standard Java programming language access checks -- for public, default (package) access, protected, and private members -- performed by reflected objects at their point of use.

3.1.13 java.io.SerializablePermission

This class contains the following targets and no actions:

enableSubclassImplementation

enableSubstitution

3.1.14 java.security.SecurityPermission

SecurityPermissions control access to security-related objects, such as Security, Policy, Provider, Signer, and Identity objects. This class contains the following targets and no actions:

getPolicy

setPolicy

getProperty.{key}

setProperty.{key}

insertProvider.{provider name}

removeProvider.{provider name}

setSystemScope

setIdentityPublicKey

setIdentityInfo

printIdentity

addIdentityCertificate

removeIdentityCertificate

clearProviderProperties.{provider name}

putProviderProperty.{provider name}

removeProviderProperty.{provider name}

getSignerPrivateKey

setSignerKeyPair

3.1.15 java.security.AllPermission

This permission implies all permissions. It is introduced to simplify the work of system administrators who might need to perform multiple tasks that require all (or numerous) permissions. It would be inconvenient to require the security policy to iterate through all permissions. Note that AllPermission also implies new permissions that are defined in the future.

Clearly much caution is necessary when considering granting this permission.

3.1.16 javax.security.auth.AuthPermsision

AuthPermission handles authentication permissions and authentication-related object such as Subject, SubjectDomainCombiner, LoginContext, and Configuration. This class contains the following targets and no actions:

doAs

doAsPrivileged

getSubject

getSubjectFromDomainCombiner

setReadOnly

modifyPrincipals

modifyPublicCredentials

modifyPrivateCredentials

refreshCredential

destroyCredential

createLoginContext.{name}

getLoginConfiguration

setLoginConfiguration

refreshLoginConfiguration

3.1.17 Discussion of Permission Implications

Recall that permissions are often compared against each other, and to facilitate such comparisons, we require that each permission class defines animpliesmethod that represents how the particular permission class relates to other permission classes. For example, java.io.FilePermission("/tmp/*", "read") implies java.io.FilePermission("/tmp/a.txt", "read") but does not imply any java.net.NetPermission.

There is another layer of implication that may not be immediately obvious to some readers. Suppose that one applet has been granted the permission to write to the entire file system. This presumbly allows the applet to replace the system binary, including the JVM runtime environment. This effectively means that the applet has been granted all permissions.

Another example is that if an applet is granted the runtime permission to create class loaders, it is effectively granted many more permissions, as a class loader can perform sensitive operations.

Other permissions that are "dangerous" to give out include those that allow the setting of system properties, runtime permissions for defining packages and for loading native code libraries (because the Java security architecture is not designed to and does not prevent malicious behavior at the level of native code), and of course the AllPermission.

For more information about permissions, including tables enumerating the risks of assigning specific permissions as well as a table of all the Java built-in methods that require permissions, seePermissions in JDK 7.

3.1.18 How To Create New Types of Permissions

It is essential that no one except Sun Microsystems should extend the permissions that are built into the Java 2 SDK, either by adding new functionality or by introducing additional target keywords into a class such as java.lang.RuntimePermission. This maintains consistency.

To create a new permission, the following steps are recommended, as shown by an example. Suppose an application developer from company ABC wants to create a customized permission to "watch TV".

First, create a new class com.abc.Permission that extends the abstract class java.security.Permission (or one of its subclasses), and another new class com.abc.TVPermission that extends the com.abc.Permission. Make sure that theimpliesmethod, among others, is correctly implemented. (Of course, com.abc.TVPermission can directly extend java.security.Permission; the intermediate com.abc.Permission is not required.)

public class com.abc.Permission extends java.security.Permission

public class com.abc.TVPermission extends com.abc.Permission

The following figure shows the subclass relationship.

Second, include these new classes with the application package.

Each user that wants to allow this new type of permission for specific code does so by adding an entry in a policy file. (Details of the policy file syntax are given in a later section.) An example of a policy file entry granting code from http://www.example.com/ permission to watch channel 5 would be:

grant codeBase "http://www.example.com/" {

permission com.abc.TVPermission "channel-5", "watch";

}

In the application's resource management code, when checking to see if a permission should be granted, call AccessController'scheckPermissionmethod using a com.abc.TVPermission object as the parameter.

com.abc.TVPermission tvperm = new

com.abc.TVPermission("channel-5", "watch");

AccessController.checkPermission(tvperm);

Note that, when adding a new permission, one should create a new (permission) class and not add a new method to the security manager. (In the past, in order to enable checking of a new type of access, you had to add a new method to the SecurityManager class.)

If more elaborate TVPermissions such as "channel-1:13" or "channel-*" are allowed, then it may be necessary to implement a TVPermissionCollection object that knows how to deal with the semantics of these pseudo names.

New code should always invoke a permission check by calling thecheckPermissionmethod of the AccessController class in order to exercise the built-in access control algorithm. There is no essential need to examine whether there is a ClassLoader or a SecurityManager. On the other hand, if the algorithm should be left to the installed security manager class, then the methodSecurityManager.checkPermissionshould be invoked instead.

3.2java.security.CodeSource

This class extends the concept of a codebase within HTML to encapsulate not only the code location (URL) but also the certificate(s) containing public keys that should be used to verify signed code originating from that location. Note that this is not the equivalent of the CodeBase tag in HTML files. Each certificate is represented as a java.security.cert.Certificate, and each URL as a java.net.URL.

3.3java.security.Policy

The system security policy for a Java application environment, specifying which permissions are available for code from various sources, is represented by a Policy object. More specifically, it is represented by a Policy subclass providing an implementation of the abstract methods in the Policy class.

In order for an applet (or an application running under a SecurityManager) to be allowed to perform secured actions, such as reading or writing a file, the applet (or application) must be granted permission for that particular action. The only exception is that code always automatically has permission to read files from its same CodeSource, and subdirectories of that CodeSource; it does not need explicit permission to do so.

There could be multiple instances of the Policy object, although only one is "in effect" at any time. The currently-installed Policy object can be obtained by calling thegetPolicymethod, and it can be changed by a call to thesetPolicymethod (by code with permission to reset the Policy).

The source location for the policy information utilized by the Policy object is up to the Policy implementation. The policy configuration may be stored, for example, as a flat ASCII file, as a serialized binary file of the Policy class, or as a database. There is a Policy reference implementation that obtains its information from static policy configuration files.

3.3.1 Policy File Format

In the Policy reference implementation, the policy can be specified within one or more policy configuration files. The configuration files indicate what permissions are allowed for code from specified code sources. Each configuration file must be encoded in UTF-8.

A policy configuration file essentially contains a list of entries. It may contain a "keystore" entry, and contains zero or more "grant" entries.

A keystore is a database of private keys and their associated digital certificates such as X.509 certificate chains authenticating the corresponding public keys. The keytool utility is used to create and administer keystores. The keystore specified in a policy configuration file is used to look up the public keys of the signers specified in the grant entries of the file. A keystore entry must appear in a policy configuration file if any grant entries specify signer aliases, or if any grant entries specify a principal alias (see below).

At this time, there can be only one keystore entry in the policy file (others after the first one are ignored), and it can appear anywhere outside the file's grant entries . It has the following syntax:

keystore "some_keystore_url", "keystore_type";

Here, "some_keystore_url" specifies the URL location of the keystore, and "keystore_type" specifies the keystore type. The latter is optional. If not specified, the type is assumed to be that specified by the "keystore.type" property in the security properties file.

The URL is relative to the policy file location. Thus if the policy file is specified in the security properties file as:

policy.url.1=http://foo.bar.example.com/blah/some.policy

and that policy file has an entry:

keystore ".keystore";

then the keystore will be loaded from:

http://foo.bar.example.com/blah/.keystore

The URL can also be absolute.

A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private keys in the keystore and the integrity of the keystore itself. The default type supported by Sun Microsystems is a proprietary keystore type named "JKS".

Each grant entry in a policy file essentially consists of a CodeSource and its permissions. Actually, a CodeSource consists of a URL and a set of certificates, while a policy file entry includes a URL and a list of signer names. The system creates the corresponding CodeSource after consulting the keystore to determine the certificate(s) of the specified signers.

Each grant entry in the policy file is of the following format, where the leading "grant" is a reserved word that signifies the beginning of a new entry and optional items appear in brackets. Within each entry, a leading "permission" is another reserved word that marks the beginning of a new permission in the entry. Each grant entry grants a set of permissions to a specified code source and principals.