Chapter 4. Java Security Manager

4.1. About the Java Security Manager

The Java Security Manager is a class that manages the external boundary of the Java Virtual Machine (JVM) sandbox, controlling how code executing within the JVM can interact with resources outside the JVM. When the Java Security Manager is activated, the Java API checks with the security manager for approval before executing a wide range of potentially unsafe operations. The Java Security Manager uses a security policy to determine whether a given action will be allowed or denied.

4.2. Define a Java Security Policy

A Java security policy is a set of defined permissions for different classes of code. The Java Security Manager compares actions requested by applications against the security policy. If an action is allowed by the policy, the Security Manager will permit that action to take place. If the action is not allowed by the policy, the Security Manager will deny that action.

Important

Previous versions of JBoss EAP defined policies using an external file, e.g. EAP_HOME/bin/server.policy. JBoss EAP 7 defines Java Security Policies in two ways: the security-manager subsystem and through XML files in the individual deployments. The security-manager subsystem defines minimum and maximum permission for ALL deployments, while the XML files specify the permissions requested by the individual deployment.

4.2.1. Defining Policies in the Security Manager Subsystem

The security-manager subsystem allows you do define shared or common permissions for all deployments. This is accomplished by defining minimum and maximum permission sets. All deployments will be granted at the least all permissions defined in the minimum permission. The deployment process fails for a deployment if it requests a permission that exceeds the ones defined in the maximum permission set.

Example: Management CLI Command for Updating Minimum Permission Set

/subsystem=security-manager/deployment-permissions=default:write-attribute(name=minimum-permissions, value=[{class="java.util.PropertyPermission", actions="read", name="*"}])

Example: Management CLI Command for Updating Maximum Permission Set

/subsystem=security-manager/deployment-permissions=default:write-attribute(name=maximum-permissions, value=[{class="java.util.PropertyPermission", actions="read,write", name="*"}, {class="java.io.FilePermission", actions="read,write", name="/-"}])

Note

If the maximum permission set is not defined, its value defaults to java.security.AllPermission.

You can find a full reference of the security-manager subsystem in the JBoss EAP Configuration Guide.

4.2.2. Defining Policies in the Deployment

In JBoss EAP 7, you can add a META-INF/permissions.xml to your deployment, which is part of JSR 342 and is a part of the Java EE specification. This file allows you to specify the permissions needed by the deployment. If a minimum permissions set is defined in the security-manager subsystem and a META-INF/permissions.xml is added to your deployment, then the union of those permissions is granted. If the permissions requested in the permissions.xml exceed the maximum policies defined in the security-manager subsystem, its deployment will not succeed. If both META-INF/permissions.xml and META-INF/jboss-permissions.xml are present in the deployment, then only the permissions requested in the META-INF/jboss-permissions.xml are granted.

The specification dictates that permissions.xml cover the entire application or top-level deployment module. In cases where you wish to define specific permissions for a subdeployment, you can use the JBoss EAP-specific META-INF/jboss-permissions.xml. It follows the same exact format as permissions.xml and will apply only to the deployment module in which it is declared.

Example: Sample permissions.xml

<permissions version="7">
  <permission>
  <class-name>java.util.PropertyPermission</class-name>
  <name>*</name>
  <actions>read</actions>
  </permission>
</permissions>

4.2.3. Defining Policies in Modules

You can restrict the permissions of a module by adding a <permissions> element to the module.xml file. The <permissions> element contains zero or more <grant> elements, which define the permission to grant to the module. Each <grant> element contains the following attributes:

permission
The qualified class name of the permission to grant.
name
The permission name to provide to the permission class constructor.
actions
The (optional) list of actions, required by some permission types.

Example: module.xml with Defined Policies

<module xmlns="urn:jboss:module:1.5" name="org.jboss.test.example">
  <permissions>
    <grant permission="java.util.PropertyPermission" name="*" actions="read,write" />
    <grant permission="java.io.FilePermission" name="/etc/-" actions="read" />
  </permissions>
  ...
</module>

If the <permissions> element is present, the module will be restricted to only the permissions you have listed. If the <permissions> element is not present, there will be no restrictions on the module.

4.3. Run JBoss EAP With the Java Security Manager

Important

Previous version of JBoss EAP allowed for the use of the -Djava.security.manager Java system property as well as custom security managers. Neither of these are supported in JBoss EAP 7. In addition, the Java Security Manager policies are now defined within the security-manager subsystem, meaning external policy files and the -Djava.security.policy Java system property are not supported JBoss EAP 7.

Important

Before starting JBoss EAP with the Java Security Manager enabled, you need make sure all security policies are defined in the security-manager subsystem.

To run JBoss EAP with the Java Security Manager, you need to use the secmgr option during startup. There are two ways to do this:

  • Use the flag with the startup script To use the -secmgr flag with the startup script, include it when starting up your JBoss EAP instance:

    Example: Startup Script

    ./standalone.sh -secmgr

  • Using the Startup Configuration File

    Important

    The domain or standalone server must be completely stopped before you edit any configuration files.

    Note

    If you are using JBoss EAP in a managed domain, you must perform the following procedure on each physical host or instance in your domain.

    To enable the Java Security Manager using the startup configuration file, you need to edit either the standalone.conf or domain.conf file, depending if you are running a standalone instance or managed domain. If running in Windows, the standalone.conf.bat or domain.conf.bat files are used instead.

    Uncomment the SECMGR="true" line in the configuration file:

    Example: standalone.conf or domain.conf

    # Uncomment this to run with a security manager enabled
    SECMGR="true"

    Example: standalone.conf.bat or domain.conf.bat

    rem # Uncomment this to run with a security manager enabled
    set "SECMGR=true"

4.4. Considerations Moving from Previous Versions

When moving applications from a previous version of JBoss EAP to JBoss EAP 7 running with the Java Security Manager enabled, you need to be aware of the changes in how policies are defined as well as the necessary configuration needed with both the JBoss EAP configuration and the deployment.

4.4.1. Defining Policies

In previous versions of JBoss EAP, policies were defined in an external configuration file. In JBoss EAP 7, policies are defined using the security-manager subsystem and with permissions.xml or jboss-permissions.xml contained in the deployment. More details on how to use both to define your policies are covered in a previous section.

4.4.2. JBoss EAP Configuration Changes

In previous versions of JBoss EAP, you could use -Djava.security.manager and -Djava.security.policy Java system properties during JBoss EAP startup. These are no longer supported and the secmgr flag should be used instead to enable JBoss EAP to run with the Java Security Manager. More details on the secmgr flag are covered in a previous section.

4.4.3. Custom Security Managers

Custom security managers are not supported in JBoss EAP 7.