Index

Understanding the Java Security Model and the Java Service Wrapper

The Java Service Wrapper implements a series of Permissions, which can be used to fully control access to the Wrapper API using the standard Java Security Model.

As explained in the section below, the user can define the desired permissions in a policy file without any Java coding. This policy file is then used by the Java Service Wrapper via the Security Manager class.

WARNING

Java 17 deprecates the Security Manager. Usage of this security model is no longer recommended.

Controlling another service from within a Java Application

The Wrapper makes it possible to start, stop, interrogate, and perform other operations on any service on a system by sending the appropriate control codes. This can be very powerful, but if used incorrectly can also open up some severe security problems on a server. For this reason, access to the WrapperManager.sendServiceControlCode(...) method is disabled by default. To make use of it requires that a Security Manager be installed in the JVM and that specific permissions be granted.

Be aware that the act of setting a security manager will likely cause many things in your application to start failing with security errors. It is necessary to go in and grant the appropriate permissions for your application. See the following Oracle's tutorial for more information on security managers: http://docs.oracle.com/javase/tutorial/essential/environment/security.html

Setup a Security Manager

The simplest way to setup a security manager in your JVM is to add the following properties to your wrapper.conf file:

Configuration Example: 
wrapper.java.additional.1=-Djava.security.manager
wrapper.java.additional.2=-Djava.security.policy=../conf/java.policy

java.security.manager:

The first system property, java.security.manager (J2SE 5.0) (JavaSE6), tells Java that a security manager should be created when the JVM is created.

java.security.policy:

The second system property, java.security.policy (J2SE 5.0) (JavaSE6), then tells the location of a file which will describe the permissions that should be granted within your application.

The policy file is a simple text file.

Example of Policy file: 
// Give Wrapper classes full permissions
grant codeBase "file:../lib/wrapper.jar" {
        permission java.security.AllPermission;
};

// Grant various permissions to a specific service.
grant codeBase "file:../lib/-" {
        permission org.tanukisoftware.wrapper.security.WrapperServicePermission
"myservice", "interrogate,start,stop";
};

The first block lets the classes wrapper.jar have full permissions to do anything. This is advised as the Wrapper needs to be able to launch your entire application meaning that anything your application does is originating from the Wrapper.

The second block means that any other classes in jars in your lib directory are able to make calls to interrogate, start, and stop the "myservice" service via the Wrapper. If this is not there, then the calls will result in SecurityExceptions being thrown.

WrapperManager.fireUserEvent API

In Wrapper version 3.5.8, the ability to call user-defined events through the WrapperManager API has been added. While this is a powerful feature to ease the use of user events for developers, it may also cause security concerns if a program should be allowed to call all user events from itself.

To provide a solution for this concerns, the API makes use of the WrapperUserEventPermission Class which can be defined in the SecurityManager's policy file.

Example of Policy file: 
grant codeBase "file:../lib/some.jar" {
        permission org.tanukisoftware.wrapper.security.WrapperUserEventPermission "fireUserEvent", "-10, 50, 100-200, 555-";
}

The above example equips the library "../lib/some.jar" with the permission to call the following userEvents:

  • "-10" : if the start number of a range is not specified, it means the sequence starts with its first value, i.e. "1"

  • "50" : numbers can be defined individually

  • "100-200" : all numbers between 100 and 200 (incl. 100 and 200)

  • "555-" : all numbers between 555 up to the upper limit of available event numbers, i.e. 32767.

NOTE

For consistency, the numbers must be sorted, this means following would be invalid: "5, -4", "1, 8-10, 7", "9-, 7", etc. Any misconfigurations will cause access denied error.