Security in TMX4J

This document describes the use of the JavaTM 2 Platform's security mechanisms in Tivoli's implementation of the JavaTM Management Extensions (TMX4J). It does not describe the JMX and the Java security in a detailed way. For more information on JMX see the "Java Management Extensions Instrumentation and Agent Specification, v1.0". For more information on security in Java 2 (SDK 1.2) see the Java Tutorial and Java 2 SDK documentation.
 

1. The TMX4J Security Design

The TMX4J Security design is based only on the Java 2 Platform security architecture. That architecture enforces code source-based access controls, i.e., controls based on where code came from and who signed it. The core of this design involves the definition of appropriate new Permission classes to control access to JMX resources (we will examine these classes in detail later).

The TMX4J Security is based on two different levels. In the first level the SecurityManager.checkPermission method is called for checking if the MBean server client has the permission for invoking a specific MBeanServer's method (or MBeanServerFactory method). The second level provides a mechanism for granting permissions at the level of individual MBean's attributes and operations. The following figure shows how the key components of JMX relate to one another and how they interact with the TMX4J Security:

FIGURE 1 Relationship between the components of the JMX Architecture
and the TMX4J security mechanisms.




2. How enable the security

The straightforward application of the Java security mechanisms to JMX enables security for TMX4J in a way that is simple, flexible and transparent. For example, the default security policy is based on information found in a file, named policy file, on the user's local disk. This file gives the system administrator or end user the ability to specify which permissions should apply to which code sources and for any Java program (but only if the Java SecurityManager is active); this allows changes to the security model for the program without modifying the program's code.

It is possible to use the Tivoli JMX implementation with or without security enabled, i.e., with or without the presence of a security manager. The TMX4J packages behave in a standard way when security is not enabled. In order to enable the security you may specify the '-Djava.security.manager' flag when the JVM is loaded. In addition Java provides users with the option of specifying where the security policy file should be read from; this is accomplished by adding the '-Djava.security.policy=<URL>' switch to the command line. For example, the following command would load the policy file from /home/jmx.policy:

> java -Djava.security.manager \
     -Djava.security.policy=/home/jmx.policy MyJavaProgram
End-users, i.e., administrators responsible for installing and configuring TMX4J enabled software, need to understand how to use policy files to configure the desired access to available instrumentation. In a nutshell, a policy file is a set of several policy entries; each entry is specific to one code source and should list all the permissions for that code source. The following is a fragment of a policy file that represents a policy entry used for granting a specific permission to any code loaded from the /home/mylib/ directory:
...
grant codeBase "file:/home/mylib/" {
    permission com.tivoli.jmx.MBeanServerPermission "MBeanServer.invoke";
};
...
Click here to view a policy file example. This file is an extension of the default policy file that comes with the Java 1.2. It integrates some new policy entries for granting the new permissions.

Please see the appropriate Java documentation for getting more information on the syntax of a policy entry and policy files in general.
 

3. MBean Server's Access

The core component of the JMX architecture at the agent level is the MBean server. The MBean server provides access to all of the MBeans registered with it. Thus it would be possible for a client to connect to the MBean server, create an arbitrary MBean and invoke its operations and manipulate its attributes at will. MBeans may be registered either by the agent application, or by other MBeans.

Many methods of the MBean server API include an MBean Server's access control mechanism that provides an administrator a means for granting or denying access to any of these methods simply by modifying the content of the policy file. The MBean server client must invoke the target MBean server method in a context that has the necessary permissions; otherwise a lack of permission generates a security exception (wrapped in a javax.management.RuntimeOperationsException).
If the client is invoked from arbitrary code it may be necessary to use a privileged action to invoke the client's own privileges. The AccessController's doPrivileged method provides a means for the MBean server client to execute a PrivilegedAction in a context in which its permissions are available. For example, MBean server clients that use privileged actions to invoke their own permissions should invoke MBeanServer methods as follows:

 ...
 AccessController.doPrivileged(new PrivilegedAction() {
   public Object run() {
     // MBean server method invocation
     // Note: result must be subclass of Object
     return <result>;
   }
 });
 ...

3.1. The MBeanServerPermission class

The com.tivoli.jmx package provides the MBeanServerPermission class. This class represents permissions to invoke the methods of the MBeanServer interface and MBeanServerFactory class. It provides an indication of whether or not a code source may execute a given method. Like java.lang.RuntimePermission, MBeanServerPermission uses a set of permission target names to grant access to MBean server methods. Those permission target names are specified as dot-separeted names and the only valid names are:
 
MBeanServer.addNotificationListener
MBeanServer.createMBean
MBeanServer.deserialize
MBeanServer.getAttribute
MBeanServer.getDefaultDomain
MBeanServer.getMBeanCount
MBeanServer.getMBeanInfo
MBeanServer.getObjectInstance
MBeanServer.instantiate
MBeanServer.invoke
MBeanServer.isRegistered
MBeanServer.queryMBeans
MBeanServer.queryNames
MBeanServer.registerMBean
MBeanServer.removeNotificationListener
MBeanServer.setAttribute
MBeanServer.unregisterMBean
MBeanServerFactory.createMBeanServer
MBeanServerFactory.newMBeanServer
MBeanServerFactory.findMBeanServer
MBeanServerFactory.releaseMBeanServer
The above list must be used to get the name to use in the MBeanServerPermission constructor to create a permission object that represents the desired permission. The administrator may grant specific permissions based on these names. Their meaning is trivial. For example, the name "MBeanServer.invoke" represents the permission for accessing the invoke method defined in the MBeanServer interface.
 

3.2. Specify MBeanServerPermissions in the policy file

Like all other permissions in the Java API, an administrator may grant a specific MBeanServerPermission based on the code's signer, its code source, or both by placing the specific policy entry. For example, he could add the following lines in a policy file:

grant signedBy "TrustedOrg" {
    permission com.tivoli.jmx.MBeanServerPermission "MBeanServerFactory.createMBeanServer";
};

grant codeBase "file:/opt/apps/trusted" {
    permission com.tivoli.jmx.MBeanServerPermission "MBeanServer.invoke", signedBy "tivoli";
};

grant signedBy "TrustedOrg" codeBase "file:/opt/apps/trusted" {
    permission com.tivoli.jmx.MBeanServerPermission "MBeanServer.createMBean";
};

An administrator may grant an access to all the methods of the MBeanServer interface or MBeanServerFactory class by using a wildcard. For example, the following entry grants access to all the MBeanServer methods:
grant signedBy "MyOrg" {
    permission com.tivoli.jmx.MbeanServerPermission "MBeanServer.*", signedBy "tivoli";
};
and the following one grants access to all the MBeanServerFactory methods:
grant signedBy "MyDomain" {
    permission com.tivoli.jmx.MbeanServerPermission "MBeanServerFactory.*";
};
An administrator may also grant access to invoke all the methods of the MBeanServer interface and MBeanServerFactory class by adding the line:
grant signedBy "MyOrg" {
    permission com.tivoli.jmx.MbeanServerPermission "*";
};
Granting this type of permission is obviously somewhat dangerous; this permission is usually given only to classes within the TMX4J API and to classes in other Java extensions.
 
 

4. MBean Access

MBeans are the mechanism for monitoring and manipulating managed resources. An MBean allows a client to get and set resources attributes and to affect the resources behavior via method invocations. The TMX4J Security provides an MBean access mechanism for controlling the access to an MBean’s interface: possession of the required permission results in access; lack of permission generates a security exception (wrapped in a javax.management.RuntimeOperationsException).

A system administrator may grant permissions for access to MBean attributes and operations specifying by means of the MBeanPermission class, a new type of permission introduced within the TMX4J packages. In addition MBean clients that use privileged actions to invoke their own permissions will have to invoke MBean methods as follows:

 ...
 AccessController.doPrivileged(new PrivilegedAction() {
   public Object run() {
     // MBean method invocation
     // Note: result must be subclass of Object
     return <result>;
   }
 });
 ...
4.1 The MBeanPermission Class

The com.tivoli.jmx package provides the MBeanPermission class. This class provides an indication of whether or not a code source may execute a given MBean method. MBeanPermission supports three actions: "get", "set", "invoke". These actions apply to the attributes and operations exposed for management by the MBean. The "get" and "set" actions may only be applied to attributes. The "invoke" action may only be applied to operations.
 

4.2. Specify MBeanPermissions in the policy file

Like all other permissions in the Java API, an administrator may grant a specific MBeanPermission based on the code's signer, its code source, or both by placing the specific policy entry. It follows some examples that should provide an administrator with the necessary details to modify the policy file for granting this type of permission (see also the policy file example).
 

  • An administrator may grant a code source or signer invoke access to an MBean method that defines an operation by adding the following lines in a policy file:
  • grant signedBy "MyOrg" {
        permission com.tivoli.jmx.MBeanPermission "<method-name>", "invoke";
    };
    where <method-name> is the fully qualified name of the method identifying the operation. An asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "mypackage.MyClass.myOperation", "mypackage.MyClass.*", "*", etc.
     
  • An administrator may grant a a code source or signer get access to an MBean attribute by adding the lines:
  • grant signedBy "MyXYXOrg" {
        permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "get";
    };
    where <attribute-name> is the fully qualified name of the attribute. An asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "mypackage.MyClass.myAttribute", "mypackage.MyClass.*", "*", etc.
     
  • An administrator may grant a code source or signers set access to an MBean attribute by adding the lines:
  • grant codeBase "file:/opt/apps/" {
        permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "set";
    };
    where <attribute-name> is the fully qualified name of the attribute as described above.
     
  • Finally, an administrator may grant a code source or signer full access to an MBean attribute by adding the lines:
  • grant signedBy "MyXYXOrg" {
        permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "get,set";
    };