Java 2 Security

Java™ 2 Security functionality is supported in the WebSphere® Application Server Liberty. Java 2 Security provides a policy-based, fine-grained access control mechanism that increases overall system integrity by checking for permissions before allowing access to certain protected system resources.

Java 2 Security is independent of Java Platform, Enterprise Edition role-based authorization. Java 2 Security guards access to system resources such as file input and output, sockets, and properties; whereas Java Platform, Enterprise Edition security guards access to web resources such as servlets and JSP files.

Java 2 Security for deployers and administrators

Before you enable Java 2 Security, you need to make sure that all the applications are granted the required permissions, otherwise, applications might fail to run. By default, applications are granted the permissions per the Java Platform, Enterprise Edition 7.0 specification. If an application is not prepared for Java 2 Security or if the application provider does not provide a permissions.xml file as part of the application, then the application might cause Java 2 Security access control exceptions at run time when Java 2 Security is enabled. Even if the application is running, it might not run correctly.

Java 2 Security for application developers

Application developers must understand the permissions that are granted in the default WebSphere policy and the permission requirements of the Java SDK APIs. You need to know whether the APIs that your application calls require extra permissions or not. For more information about which Java APIs require permissions, see Permissions in the Java 2 SDK.
Permissions are added to an application by way of the permissions.xml file, and the codebase that is associated with the listed permissions is based on the location of the file. For a stand-alone .war application, the permissions.xml file is bundled under the META-INF directory and all specified permissions apply to all modules included in the .war file. For a .ear application, the permissions.xml is bundled directly under the META-INF directory for the .ear itself, and the specified permissions apply to all modules included in the .ear file.
Note: In the case of an .ear application, permissions.xml files that are bundled under the META-INF directory of any module other than the .ear are ignored.

When you work with OSGi applications that contain Web Application Bundles (WABs), permissions are added by way of the permissions.perm file. If the WAB has no permissions.perm file, the policy defaults to java.security.AllPermission.

Enabling Java 2 Security

Java 2 Security functions are part of the kernel extension and are enabled at bootstrap time by updating the bootstrap.properties file with the websphere.java.security property.

If the websphere.java.security property is specified in the bootstrap.properties file, Java 2 Security is enforced; otherwise, no permission checking occurs.

Specifying restricted permissions

Liberty provides a mechanism to specify restricted permissions when it runs a web or EJB application component. A restricted permission ensures no instance of that permission is granted to a bundle or application. They provide a mechanism to prevent applications from granting themselves more permissions than what must be allowed, for example, the permission to exit VM.
Restricted permissions are specified in the server.xml and client.xml files. The following example shows how the PropertyPermission that is used to write the System property os.name is restricted. This syntax is identical in both the server.xml and client.xml files:

<javaPermission className="java.security.PropertyPermission" name="os.name" actions="write" restriction="true" />

Granting permissions

OSGi bundles can self-regulate the permissions that are granted to the libraries/classes within the bundle through the permissions.perm file.

Applications can also self-regulate permissions that are granted through the permissions.xml file, or by specifying the permission grants in the server.xml and client.xml files.

OSGi bundle permissions

The OSGi specification provides a mechanism to specify permissions for a bundle through the permissions.perm file in the OSGI-INF directory of the bundle. The mechanism allows fine-grained access control of permissions for the bundle.
The permissions.perm file specifies the maximum permissions that the bundles require.
Important: An empty permissions.perm file is not equivalent to no permissions.perm file. Make sure that you have a non-empty permissions.perm file if you want restricted permissions.

Declaring permissions in the server.xml and client.xml for applications

Permissions without a specified codebase, which are defined in the server.xml and client.xml files apply to all applications on that Liberty server.
You can specify the permissions to be granted in the server.xml and client.xml files as given in the following example. In this example, the PropertyPermission that enables all System properties to be read is granted:

<javaPermission className="java.util.PropertyPermission"  name="*" actions="read" />
You can specify the permissions to be restricted in the server.xml and client.xml files. The following example shows how the PropertyPermission that is used to write the System property os.name is restricted. This syntax is identical in both the server.xml and client.xml files:

<javaPermission className="java.security.PropertyPermission" name="os.name" actions="write" restriction="true" />
Notes:
  • A restricted permission has restriction set to true.
  • If an application attempts to grant itself a permission that is defined as a restricted permission, the restricted permission takes precedence over the grant and disallows the grant.

Declaring permissions in permissions.xml for applications

The permissions.xml file is a new file that is introduced by the Java EE7 specification. It is packaged under the META-INF directory for an application.

For applications packaged as a stand-alone .war file, the permissions that are specified at the META-INF WAR level apply to all modules and libraries that are packaged within the .war file.

For applications that are packages in an .ear file, the declaration of permissions must be at the .ear file level. This permission set is applied to all modules and libraries that are packaged within the .ear file or within its contained modules. Any permissions.xml file within such packaged modules is ignored, regardless of whether a permissions.xml file is supplied for the .ear file itself.

For applications that are packaged in a .rar file, the declaration of permissions must be at the META-INF RAR level.

No-rethrow option

When Java 2 Security is enabled, the JDK Security Manager throws an java.security.AccessControl exception by default when a permission violation occurs. If the exception is not handled, it might cause a runtime failure. To help the developers when they are preparing their applications for Java 2 Security, a no-rethrow option is available. The no-rethrow option allows the AccessControl exception to be logged in the console.log and messages.log but does not cause the application to fail. The no-rethrow option is enabled by specifying websphere.java.security.norethrow=true in the bootstrap.properties file. The no-rethrow option is not enabled by default, hence you must enable this property by specifying it in the bootstrap.properties file.
Note: Because this property does not allow the Security Manager to throw the exception, the Security Manager technically does not enforce Java 2 Security. The no-rethrow property must not be used in a production environment.

Dynamic updates

Dynamic updates to the permission files such as the permissions.perm, permissions.xml, server.xml, and client.xml are not supported. Updates to permissions require a Liberty server restart.