Menu Close

Chapter 5. Java security manager

By defining a Java security policy you can configure the Java Security Manager to manage the external boundary of the Java Virtual Machine (JVM).

5.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.

5.2. About 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.

5.2.1. About 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.

Additional resources

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

5.2.2. About defining policies in the deployment

In JBoss EAP 7, you can add a META-INF/permissions.xml to your deployment. 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>

5.2.3. About 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.

5.3. Run JBoss EAP with the Java security manager

You can run JBoss EAP with the Java Security Manager in two different ways. There are two ways to run the Java Security Manager:

  • Using the -secmgr flag with startup configuration script.
  • Using the Startup Configuration File.
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.

5.3.1. Using the -secmgr flag with startup configuration script.

You can run JBoss EAP with the Java Security Manager. To do this, use the secmgr option during startup.

Procedure

  • Include the -secmgr flag when starting up your JBoss EAP instance.

    Example of how to include the -secmgr flag

    ./standalone.sh -secmgr

5.3.2. Using the startup configuration file

You can run JBoss EAP with the Java Security Manager. To do this, you have to modify 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.

Procedure

  • 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"

5.4. Considerations before 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. Here are the changes that you should be aware of:

  • 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.
  • You could use -Djava.security.manager and -Djava.security.policy Java system properties during JBoss EAP startup In previous versions of JBoss EAP. These are no longer supported and the secmgr flag should be used instead to enable JBoss EAP to run with the Java Security Manager.
  • Custom security managers are not supported in JBoss EAP 7.