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 \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:
-Djava.security.policy=/home/jmx.policy MyJavaProgram
...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.
grant codeBase "file:/home/mylib/" {
permission com.tivoli.jmx.MBeanServerPermission "MBeanServer.invoke";
};
...
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>;
}
});
...
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.
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
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" {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:
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";
};
grant signedBy "MyOrg" {and the following one grants access to all the MBeanServerFactory methods:
permission com.tivoli.jmx.MbeanServerPermission "MBeanServer.*", signedBy "tivoli";
};
grant signedBy "MyDomain" {An administrator may also grant access to invoke all the methods of the MBeanServer interface and MBeanServerFactory class by adding the line:
permission com.tivoli.jmx.MbeanServerPermission "MBeanServerFactory.*";
};
grant signedBy "MyOrg" {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.
permission com.tivoli.jmx.MbeanServerPermission "*";
};
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:
...4.1 The MBeanPermission Class
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
// MBean method invocation
// Note: result must be subclass of Object
return <result>;
}
});
...
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).
grant signedBy "MyOrg" {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.
permission com.tivoli.jmx.MBeanPermission "<method-name>", "invoke";
};
grant signedBy "MyXYXOrg" {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.
permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "get";
};
grant codeBase "file:/opt/apps/" {where <attribute-name> is the fully qualified name of the attribute as described above.
permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "set";
};
grant signedBy "MyXYXOrg" {
permission com.tivoli.jmx.MBeanPermission "<attribute-name>", "get,set";
};