Appendix A: Security and Permissions

Print-friendly Version

[<<BACK] [CONTENTS] [NEXT>>]

All applets and any applications invoked with a security manager must be granted explicit permission to access local system resources apart from read access to the directory and its subdirectories where the program is invoked. The Java platform provides permissions to allow various levels of access to different types of local information.

Because permissions let an applet or application override the default security policy, you should be very careful when you assign permissions to not create an opening for malicious code to attack your system.

This appendix describes the available permissions and explains how each permission can create an opening for malicious attacks. One way to use this information is to help you limit what permissions a given applet or application might need to successfully execute. Another way to use this information is to educate yourself on the ways in which a particular permission can be exploited by malicious code.

As a safeguard, never trust an unknown applet or application. Always check the code carefully against the information in this appendix to be sure you are not giving malicious code permission to cause serious problems on the local system.

• Overview
• Knowing Which Permissions
• AllPermission
• AWTPermission
• FilePermission
• NetPermission
• PropertyPermission
• ReflectPermission
• RuntimePermission
• SecurityPermission
• SerializablePermission
• SocketPermission

Overview

Permissions are granted to a program with a policy file. A policy file contains permissions for specific access. A permission consists of the permission name, a target, and in some cases, a comma-separated list of actions.

For example, the following policy file entry specifies a java.io.FilePermission permission that grants read access (the action) to the ${user.home}/text2.txt target.

grant {
  permission java.io.FilePermission 
	"${user.home}/text2.txt", "read";
};

There is one policy file for Java platform installation (system) and an optional policy file for each user. The system policy file is in {java.home}/lib/security/java.policy, and the user policy file is in each user's home directory. The system and user policy files are combined. So for example,there could be a system policy file with very few permissions granted to all users on the system, and individual policy files granting additional permissions to certain users.

To run an application with the security manager and a policy file named polfile in the user's home directory, type:

  java -Djava.security.main 
  -DJava.security.policy=polfile  FileIO

To run an applet in appletviewer with a policy file named polfile in the user's home directory, type:

  appletviewer 
  -J-Djava.security.policy=polfile fileIO.html

When running an applet in a browser, the browser looks for the user and system policy files to find the permissions the applet needs to access local system resources on behalf of the user who downloaded the applet.

Knowing Which Permissions

When you run an applet or invoke an application with a security manager that needs permissions, you will get a stack trace if you did not provide a policy file with all the needed permissions. The stack trace contains the information you need to add the permission to the policy file that caused the stack trace. If the program needs additional permissions, you will keep getting stack traces until all the required permissions are added to the policy file. The only drawback to this approach is you have to try every possible code path in your application.

Another way to determine which permission your program needs is to browse Appendix B: Methods and Permissions. This appendix tells you which Java 2 platform software methods are prevented from executing without the listed permission. The information in Appendix B is also useful for developers who want to write their own security manager to customize the verifications and approvals needed in a program.

Here is a short example to show you how to translate the first couple of lines in a stack trace to a policy file entry. The first line tells you access is denied. This means this stack trace was generated because the program tried to access a system resource without the proper permission. The second line means you need a java.net.SocketPermission that gives the program permission to connect to and resolve the host name for Internet Protocol (IP) address 129.144.176.176, port 1521.

java.security.AccessControlException: access denied 
     (java.net.SocketPermission 
     129.144.176.176:1521 connect,resolve)

To turn this into a policy file entry, list the permission name, a target, and an action list as follows where java.net.SocketPermission is the permission name, 129.144.176.176:1521 is the target, and connect,resolve is the action list.

grant {
  permission java.net.SocketPermission 
  "129.144.176.176:1521", "connect,resolve";
};

AllPermission

java.security.AllPermission specifies all permissions in the system for all possible targets and actions. This permission should be used only during testing because it grants permission to run with all security restrictions disabled as if there were no security manager.

grant {
  permission java.security.AllPermission;
};

AWTPermission

java.awt.AWTPermission grants access to the following Abstract Window Toolkit (AWT) targets. The possible targets are listed by name with no action list.

grant {
  permission java.awt.AWTPermission 
		"accessClipboard";
  permission java.awt.AWTPermission 
		"accessEventQueue";
  permission java.awt.AWTPermission 
		"showWindowWithoutWarningBanner";
};

accessClipboard: This target grants permission to post information to and retrieve information from the AWT clipboard. Granting this permission could allow malicious code to share potentially sensitive or confidential information.

accessEventQueue: This target grants permission to access the AWT event queue. Granting this permission could allow malicious code to peek at and remove existing events from the system, or post bogus events that could cause the application or applet to perform malicious actions.

listenToAllAWTEvents: This target grants permission to listen to all AWT events throughout the system. Granting this permission could allow malicious code to read and exploit confidential user input such as passwords.

Each AWT event listener is called from within the context of that event queue's EventDispatchThread, so if the accessEventQueue permission is also enabled, malicious code could modify the contents of AWT event queues throughout the system, which can cause the application or applet to perform unintended and malicious actions.

readDisplayPixels: This target grants permission to read pixels back from the display screen. Granting this permission could allow interfaces such as java.awt.Composite that allow arbitrary code to examine pixels on the display to include malicious code that snoops on user activities.

showWindowWithoutWarningBanner: This target grants permission to display a window without also displaying a banner warning that the window was created by an applet. Without this warning, an applet might pop up windows without the user knowing they belong to an applet. This could be a problem in environments where users make security-sensitive decisions based on whether the window belongs to an applet or an application. For example, disabling the banner warning might trick the end user into entering sensitive user name and password information.

FilePermission

java.io.FilePermission grants access to a file or directory. The targets consist of the target pathname and a comma-separated list of actions.

This policy file grants read, write, delete, and execute permission to all files.

grant {
  permission java.io.FilePermission 
	"<<ALL FILES>>", "read, write, delete, execute";
};

This policy file grants read and write permission to text.txt in the user's home directory.

grant {
  permission java.io.FilePermission 
	"${user.home}/text.txt", "read, write";
};

You can use the following wild cards to specify the target pathname.

• A pathname that ends in /*, where /* is the file separator character indicates a directory and all the files contained in that directory.

• A pathname that ends with /- indicates a directory, and recursively, all files and subdirectories contained in that directory.

• A pathname consisting of a single asterisk (*) indicates all files in the current directory.

• A pathname consisting of a single dash (-) indicates all files in the current directory, and recursively, all files and subdirectories contained in the current directory.

The actions are specified in a list of comma-separated keywords and have the following meanings:

• read: Permission to read a file or directory.
• write: Permission to write to and create a file or directory.
• execute: Permission to execute a file or search a directory.
• delete: Permission to delete a file or directory.

When granting file permissions, always think about the implications of granting read and especially write access to various files and directories. The <<ALL FILES>> permission with write action is especially dangerous because it grants permission to write to the entire file system. This means the system binary can be replaced, which includes the Java¹ Virtual Machine (VM) runtime environment.

NetPermission

java.net.NetPermission grants access to various network targets. The possible targets are listed by name with no action list.

grant {
  permission java.net.NetPermission 
	"setDefaultAuthenticator";
  permission java.net.NetPermission 
	"requestPasswordAuthentication";
};

setDefaultAuthenticator: This target grants permission to set the way authentication information is retrieved when a proxy or HTTP server asks for authentication. Granting this permission could mean malicious code can set an authenticator that monitors and steals user authentication input as it retrieves the input from the user.

requestPasswordAuthentication: This target grants permission to ask the authenticator registered with the system for a password. Granting this permission could mean malicious code might steal the password.

specifyStreamHandler: This target grants permission to specify a stream handler when constructing a Uniform Resource Locator (URL). Granting this permission could mean malicious code might create a URL with resources to which it would not normally have access, or specify a stream handler that gets the actual bytes from somewhere to which it does have access. This means the malicious code could trick the system into creating a ProtectionDomain/CodeSource for a class even though the class really did not come from that location.

PropertyPermission

java.util.PropertyPermission grants access to system properties. The java.util.Properties class represents persistent settings such as the location of the installation directory, the user name, or the user's home directory.

grant {
  permission java.util.PropertyPermission 
	"java.home", "read";
  permission java.util.PropertyPermission 
	"os.name", "write";
  permission java.util.PropertyPermission 
	"user.name", "read, write";
};

The target list contains the name of the property; for example, java.home or os.name. The naming convention for the properties follows the hierarchical property naming convention, and includes wild cards. An asterisk at the end of the property name, after a dot (.), or alone signifies a wild card match. For example, java.* or * are valid, but *java or a*b are invalid.

The actions are specified in a list of comma-separated keywords, and have the following meanings:

• read: Permission to read (get) a property.
• write: Permission to write (set) a property.

Granting property permissions can leave your system open to intrusion. For example, granting permission to access the java.home property makes the installation directory vulnerable to attack, and granting permission to access the user.name and user.home properties might reveal the user's account name and home directory to code that might misuse the informaiton.

ReflectPermission

java.lang.reflect.ReflectPermission grants permission for various reflective operations. The possible targets are listed by name with no action list.

grant {
  permission java.lang.reflect.ReflectPermission 
	"suppressAccessChecks";
};

suppressAccessChecks: This target grants permission to access fields and invoke methods in a class. This includes public, protected, and private fields and methods. Granting this permission could reveal confidential information and make normally unavailable methods accessible to malicious code.

RuntimePermission

java.lang.RuntimePermission grants access to various runtime targets such as the class loader, Java VM, and thread. The possible targets are listed by name with no action list.

grant {
  permission java.lang.RuntimePermission 
	"createClassLoader";
  permission java.lang.RuntimePermission 
	"getClassLoader";
  permission java.lang.RuntimePermission 
	"exitVM";
  permission java.lang.RuntimePermission 
	"setFactory";
  permission java.lang.RuntimePermission 
	"setIO";
  permission java.lang.RuntimePermission 
	"modifyThread";
  permission java.lang.RuntimePermission 
	"modifyThreadGroup";
  permission java.lang.RuntimePermission 
	"getProtectionDomain";
  permission java.lang.RuntimePermission 
	"setProtectionDomain";
  permission java.lang.RuntimePermission 
	"readFileDescriptor";
  permission java.lang.RuntimePermission 
	"writeFileDescriptor";
  permission java.lang.RuntimePermission 
	"loadLibrary.<library name>";
  permission java.lang.RuntimePermission 
	"accessClassInPackage.<package name>";
  permission java.lang.RuntimePermission 
	"defineClassInPackage.<package name>";
  permission java.lang.RuntimePermission 
	"accessDeclaredMembers.<class name>";
  permission java.lang.RuntimePermission 
	"queuePrintJob";
};

The naming convention for target information where a library, package, or class name is added follows the hierarchical property naming convention, and includes wild cards. An asterisk at the end of the target name, after a dot (.), or alone signifies a wild card match. For example, loadLibrary.* or * are valid, but *loadLibrary or a*b are not.

createClassLoader: This target grants permission to create a class loader. Granting this permission might allow a malicious application to instantiate its own class loader and load harmful classes into the system. Once loaded, the class loader could place these classes into any protection domain and give them full permissions for that domain.

getClassLoader: This target grants permission to retrieve the class loader for the calling class. Granting this permission could enable malicious code to get the class loader for a particular class and load additional classes.

setContextClassLoader: This target grants permission to set the context class loader used by a thread. System code and extensions use the context class loader to look up resources that might not exist in the system class loader. Granting this permission allows code to change which context class loader is used for a particular thread, including system threads. This can cause problems if the context class loader has malicious code.

setSecurityManager: This target grants permission to set or replace the security manager. The security manager is a class that allows applications to implement a security policy. Granting this permission could enable malicious code to install a less restrictive manager, and thereby, bypass checks that would have been enforced by the original security manager.

createSecurityManager: This target grants permission to create a new security manager. Granting this permission could give malicious code access to protected and sensitive methods that might disclose information about other classes or the execution stack. It could also allow the introduction of a weakened security manager.

exitVM: This target grants permission to halt the Java VM. Granting this permission could allow malicious code to mount a denial-of-service attack by automatically forcing the VM to stop.

setFactory: This target grants permission to set the socket factory used by the ServerSocket or Socket class, or the stream handler factory used by the URL class. Granting this permission allows code to set the actual implementation for the socket, server socket, stream handler, or Remote Method Invocation (RMI) socket factory. An attacker might set a faulty implementation that mangles the data stream.

setIO: This target grants permission to change the value of the System.out, System.in, and System.err standard system streams. Granting this permission could allow an attacker to change System.in to steal user input, or set System.err to a null output stream, which would hide any error messages sent to System.err.

modifyThread: This target grants permission to modify threads by calls to the stop, suspend, resume, setPriority, and setName methods in the Thread class. Granting this permission could allow an attacker to start or suspend any thread in the system.

stopThread: This target grants permission to stop threads. Granting this permission allows code to stop any thread in the system provided the code already has permission to access that thread. Malicious code could corrupt the system by killing existing threads.

modifyThreadGroup: This target grants permission to modify threads by calls to the destroy, resume, setDaemon, setmaxPriority, stop, and suspend methods of the ThreadGroup class. Granting this permission could allow an attacker to create thread groups and set their run priority.

getProtectionDomain This target grants permission to retrieve the ProtectionDomain instance for a class. Granting this permission allows code to obtain policy information for that code source. While obtaining policy information does not compromise the security of the system, it does give attackers additional information, such as local file names for example, to better aim an attack.

readFileDescriptor: This target grants permission to read file descriptors. Granting this permission allows code to read the particular file associated with the file descriptor, which is dangerous if the file contains confidential data.

writeFileDescriptor: This target grants permission to write file descriptors. Granting this permission allows code to write to the file associated with the descriptor, which is dangerous if the file descriptor points to a local file.

loadLibrary.{library name}: This target grants permission to dynamically link the specified library. Granting this permission could be dangerous because the security architecture is not designed to and does not extend to native code loaded by way of the java.lang.System.loadLibrary method.

accessClassInPackage.{package name} This target grants permission to access the specified package by way of a class loader's loadClass method when that class loader calls the SecurityManager.checkPackageAcesss method. Granting this permission gives code access to classes in packages to which it normally does not have access. Malicious code may use these classes to help in its attempt to compromise security in the system.

defineClassInPackage.{package name}: This target grants permission to define classes in the specified package by way of a class loader's defineClass method when that class loader calls the SecurityManager.checkPackageDefinition method. Granting this permission allows code to define a class in a particular package, which can be dangerous because malicious code with this permission might define rogue classes in trusted packages like java.security or java.lang, for example.

accessDeclaredMembers: This target grants permission to access the declared members of a class. Granting this permission allows code to query a class for its public, protected, default (package), and private fields and methods. Although the code would have access to the private and protected field and method names, it would not have access to the private and protected field data and would not be able to invoke any private methods. Nevertheless, malicious code may use this information to better aim an attack. Additionally, malicious code might invoke any public methods or access public fields in the class, which could be dangerous if the code would normally not be able to invoke those methods or access the fields because it cannot cast the object to the class or interface with those methods and fields.

queuePrintJob: This target grants permission to initiate a print job request. Granting this permission could allow code to print sensitive information to a printer or maliciously waste paper.

SecurityPermission

java.security.SecurityPermission grants access to various security configuration parameters. The possible targets are listed by name with no action list. Security permissions currently apply to methods called on the following objects:

• java.security.Policy, which represents the system security policy for applications.

• java.security.Security, which centralizes all security properties and common security methods. It manages providers.

• java.security.Provider, which represetns an implementation of such things as security algorithms (DSA, RSA, MD5, or SHA-1) and key generation.

• java.security.Signer, which manages private keys. Even though, Signer is deprecated, the related permissions are available for backwards compatibility.

• java.security.Identity, which manages real-world objects such as people, companies, or organizations whose identities can be authenticated using their public keys.

grant {
  permission java.security.SecurityPermission 
	"getPolicy";
  permission java.security.SecurityPermission 
	"setPolicy";
  permission java.security.SecurityPermission 
	"getProperty.os.name";
  permission java.security.SecurityPermission 
	"setProperty.os.name";
  permission java.security.SecurityPermission 
	"insertProvider.SUN";
  permission java.security.SecurityPermission 
	"removeProvider.SUN";
  permission java.security.SecurityPermission 
	"setSystemScope";
  permission java.security.SecurityPermission 
	"setIdentityPublicKey";
  permission java.security.SecurityPermission 
	"setIdentityInfo";
  permission java.security.SecurityPermission 
	"addIdentityCertificate";
  permission java.security.SecurityPermission 
	"removeIdentityCertificate";
  permission java.security.SecurityPermission 
	"clearProviderProperties.SUN";
  permission java.security.SecurityPermission 
	"putProviderProperty.<provider name>";
  permission java.security.SecurityPermission 
	"removeProviderProperty.SUN";
  permission java.security.SecurityPermission 
	"getSignerPrivateKey";
  permission java.security.SecurityPermission 
	"setSignerKeyPair";
};

getPolicy: This target grants permission to retrieve the system-wide security policy. Granting this permission discloses which permissions would be granted to a given application or applet. While revealing the policy does not compromise the security of the system, it does provide malicious code with additional information it could use to better aim an attack.

setPolicy: This target grants permission to set the system-wide security policy. Granting this permission could allow malicious code to grant itself all the necessary permissions to successfully mount an attack an attack on the system.

getProperty.{key}: This target grants permission to retrieve the security property specified by {key}. Depending on the particular key for which access has been granted, the code may have access to the list of security providers and the location of the system-wide and user security policies. While revealing this information does not compromise the security of the system, it does provide malicious code with additional information which it may use to better aim an attack.

setProperty.{key}: This target grants permission to set the security property specified by {key}. This could include setting a security provider or defining the location of the the system-wide security policy. Malicious code that has permission to set a new security provider may set a rogue provider that steals confidential information such as cryptographic private keys. In addition, malicious code with permission to set the location of the system-wide security policy may point it to a security policy that grants the attacker all the necessary permissions it requires to successfully mount an attack on the system.

insertProvider.{provider name}: This target grants permission to add the new security provider specified by {provider name}. Granting this permission allows the introduction of a possibly malicious provider that could do such things as disclose the private keys passed to it. This is possible because the Security object, which manages the installed providers, does not currently check the integrity or authenticity of a provider before attaching it.

removeProvider.{provider name}: This target grants permission to remove the provider specified by {provider name}. Granting this permission could change the behavior or disable execution of other parts of the program. If a provider requested by the program has been removed, execution might fail.

setSystemScope: This target grants permission to set the system identity scope. Granting this permission could allow an attacker to configure the system identity scope with certificates that should not be trusted. This could grant code signed with those certificates privileges that would be denied by the original identity scope.

setIdentityPublicKey: This target grants permission to set the public key for an Identity object. If the identity is marked trusted, this allows an attacker to introduce its own public key that is not trusted by the system's identity scope.This could grant code signed with that public key privileges that would be otherwise denied.

SetIdentityInfo: This target grants permission to set a general information string for an Identity object. Granting this permission allows attackers to set the general description for an identity. Doing so could trick applications into using a different identity than intended or prevent applications from finding a particular identity.

addIdentityCertificate: This target grants permission to add a certificate for an Identity object. Granting this permission allows attackers to set a certificate for an identity's public key making the public key trusted to a wider wider audience than originally intended.

removeIdentityCertificate: This target grants permission to remove a certificate for an Identity object. Granting this permission allows attackers to remove a certificate for an identity's public key. This could be dangerous because public key suddenly becomes considered less trustworthy than it otherwise would be.

printIdentity: This target grants permission to print out the name of a principal, the scope in which the principal is used, and whether the principal is considered trusted in that scope. The printed scope could be a filename, in which case it might convey local system information. For example, here is a sample printout of an identity named carol, who is marked not trusted in the user's identity database:

carol[/home/luehe/identitydb.obj][not trusted].

clearProviderProperties.{provider name} This target grants permission to clear a Provider object so it no longer contains the properties used to look up services implemented by the provider. Granting this permission disables the lookup of services implemented by the provider. This could change the behavior or disable execution of other parts of the program that would normally utilize the Provider, as described under the removeProvider.{provider name} permission above.

putProviderProperty.{provider name}: This target grants permission to set properties for the specified provider. The provider properties each specify the name and location of a particular service implemented by the provider. Granting this permission allows code to replace the service specification with another one with a different implementation and could be dangerous if the new implementation has malicaious code.

removeProviderProperty.{provider name}: This target grants permission to remove properties from the specified provider. Granting this permission disables the lookup of services implemented by the provider making them inaccessible. Granting this permission to malicious code could allow the malicious code to change the behavior or disable execution of other parts of the program that would normally utilize the Provider object, as described under the removeProvider.{provider name} permission above.

getSignerPrivateKey: This target grants permission to retrieve the private key of a Signer object. Private keys should always be kept secret. Granting this permission could allow malicious code to use the private key to sign files and claim the signature came from the Signer object.

setSignerKeyPair: This target grants permission to set the public and private key pair for a Signer object. Granting this permission could allow an attacker to replace the target's key pair with a possibly weaker (smaller) key pair. This would also allow an attacker to listen in on encrypted communication between the target and its peers. The target's peers might wrap an encryption session key under the target's new public key, which would allow the attacker (who possesses the corresponding private key) to unwrap the session key and decipher the communication data encrypted under that session key.

SerializablePermission

java.io.SerializablePermission grants access to serialization operations. The possible targets are listed by name with no action list.

grant {
  permission java.io.SerializablePermission 
	"enableSubclassImplementation";
  permission java.io.SerializablePermission 
	"enableSubstitution";
};

enableSubclassImplementation: This target grants permission to implement a subclass of ObjectOutputStream or ObjectInputStream to override the default serialization or deserialization of objects. Granting this permission could allow code to use this to serialize or deserialize classes in a malicious way. For example, during serialization, malicious code could store confidential private field data in a way easily accessible to attackers; or, during deserialization malicious code could deserialize a class with all its private fields zeroed out.

enableSubstitution: This target grants permission to substitute one object for another during serialization or deserialization. Granting this permission could allow malicious code to replace the actual object with one that has incorrect or malignant data.

SocketPermission

The java.net.SocketPermission permission grants access to a network by way of sockets. The target is a host name and port address, and the action list specifies ways to connect to that host. Possible connections are accept, connect, listen, and resolve.

This policy file entry allows a connection to and accepts connections on port 7777 on the host puffin.eng.sun.com.

grant {
  permission java.net.SocketPermission
        "puffin.eng.sun.com:7777", 
	"connect, accept";
};

This policy file entry allows connections to, accepts connections on, and listens on any port between 1024 and 65535 on the local host.

grant {
  permission java.net.SocketPermission
        "localhost:1024-", 
	"accept, connect, listen";
};

The host is expressed with the following syntax as a DNS name, as a numerical IP address, or as localhost (for the local machine). The asterisk (*) wild card can be included once in a DNS name host specification. If included, it must be in the left-most position, as in *.sun.com.

  host = (hostname | IPaddress)[:portrange]
  portrange = portnumber | -portnumber | 
	portnumber-[portnumber]

The port or port range is optional. A port specification of the form N-, where N is a port number, means all ports numbered N and above, while a specification of the form -N indicates all ports numbered N and below.

The listen action is only meaningful when used with localhost, and the resolve (resolve host/ip name service lookups) action is implied when any of the other actions are present.

Granting code permission to accept or make connections to remote hosts may be dangerous because malevolent code can more easily transfer and share confidential data among parties that might not otherwise have access to the data.

Note: On Unix platforms, only root is normally allowed access to ports lower than 1024.

[TOP]

_______
¹ As used on this web site, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.