Page History

h1. Running Tuscany with Java 2 Security Enabled

*his article is currently a draft. The article should be completed in a day or two.*

h2. Overview of Java 2 Security

*Apache Tuscany* promotes the Java 2 security model by allowing one to run Service Component Architecture (SCA) applications in a secured environment. By default, with Java 2 security disabled, Java application code and the Tuscany runtime code base run in an unsecure environment with no security manager. This gives the Java application and Tuscany runtime access to all system resources. The application may read and write all system properties, open and read any system files, and do all sorts of unprotected actions. All Tuscany code will run unhindered in this environment. And all malicious Tuscany users will also run unhindered in this environment.

With Java 2 security enabled, the user contribution to the SCA domain has very tight security restrictions. This ensures that the user SCA application does not introduce mischevious code (for instance with a user-provided custom classloader) or perform unprotected investigations (such as when a user-provided application starts snooping around the file system looking for interesting files.) WithThe properTuscany securityruntime policies,is thealso Tuscanyforced runtimeto canabide performby these sensitivetight operationssecurity becauseresitrictions, itbut isthe partruntime ofhas thebeen runtimefitted and tested iswith givenprivileged permissioncode to performcheck thesefor privilegedproper actions.access Thepermissions Tuscanybefore runtimeperforming actsany as asensitive operations. Because of this privileged code which obeys the Java 2 security architecture, the Tuscany runtime acts as a proxy and performs sensitive operations on behalf of the user application.

The purpose of this article is to show how one can run *Apache Tuscany* and SCA applications in various environments while enabling Java 2 security and ensuring the application is running in a secured environment. Tuscany users and deployers and administrators should read this article. while moreMore in-depth runtime developers should also proceed onto the associated article [Security Aware Programming in Tuscany].

h2. Enabling Java 2 Security from a Command Line

The most basic way to run Tuscany applications is from a command line window or shell. You may enable security in this environment by running your Tuscany application with the java.exe {{-Djava.security.manager}} option on the command line. This enabledenables the default Java security manager which delegates access control decisions to {{java.security.AccessController}}. The {{AccessController}} determines access authority for your Java code by consulting the permissions in a {{java.security.Policy}} class usually specified in the default {{security.policy}} file.

There is only one {{Policy object}} installed into a Java runtime at any given time. The default behavior for Java is to  load the authorization data from one or more security policy files, but Tuscany users may add to or replace the policy by running with additional policy information on the command line. For instance {{"-Djava.security.manager -Djava.security.policy=tuscany.policy"}} will add the permissions in the tuscany.policy file to the default Java permissions. If you specify {{"-Djava.security.policy==tuscany.policy"}} you replace the default policy with those specified in the Tuscany policy file. WhenThe Tuscanyformat isof run by an application server (whether it be WebSphere, Geronimo, or other), the policy the java.security.policy is a URL, which can contain any of the serverlegal willURL formprotocols thesuch startingas pointfile: for Tuscany's security policy.or http: protocol.

Each policy file will contain a list of grant statements. A grant tells the runtime where the code came from (a URL specifying the code base), who signed the code (a list of signer certificates), and what permissions are given. The permissions can be read write permissions to the file system, access to system properties, or class loading privileges.
An example of a granting all permission to an unsigned Tuscany code base is given here:
{code:title=security.policy example|borderStyle=solid}
grant codeBase "file:$/{{user.home}}/tuscany/java/sca/-" {
  permission java.security.AllPermission;
};
{code}

This example grant statement is quite a broad bludgeon. Namely it says that all Tuscany code has been granted all permissions. This seems like this is not muchvery differentsecure thatas runningit withoutprovides aall securitypermissions manager.to InTuscany, practicehowever, ait useris policystill willa wantstep muchup finer-grainedfrom permissionsrunning towardswith theno Tuscany code and allow only specific pieces of the code to have privileged access. Additional information on Java application security is given at
[Java Security|http://java.sun.com/javase/6/docs/technotes/guides/security/overview/jsoverview.html].

h2. Enabling Java 2 Security in Eclipse

h2. Enabling Java 2 Security Using Maven


JIRA TUSCANY-2339 allows all itests and vtests to be run with Java 2 security enabled.  To run this profile, you must move the tuscany.policy file to your ${java.home}/lib/security directory (default location), or provide a tuscany.policy.file property to provide a local file URL, or copy the contents of tuscany.policy to another policy file. As the tuscany.policy file is written, you must have system properties tuscany.home and maven.repos defined, or you must hard code the location of these code bases.

Run the test profile by naming the security profile name explicitly or my providing a tuscany.policy.file property:
{code}
mvn test -P security
{code}

or

{code}
mvn "-Dtuscany.policy.file=file:///e:/tuscany.policy"
{code}

Here is the addition to the pom.xml file to run with security. You may uncomment or add other modules to perform tests.
{code}

        <profile>security policy. In this case Tuscany is provided with privileged access, while user application are not. In practice, a user policy might want much finer-grained permissions towards the Tuscany code and allow only specific pieces of the code to have privileged access. An example [tuscany.policy] is attachmed to this article.

Notice that the URL in this example supports the substitution of system properties. You can also provide other property names such as tuscany.home or whatever property you provide to the command line. Additionally you may end the URL with '*' which includes all JARs and class files in the current location or '-' which includes all JAR and class file recursively below this location. Additional information on Java application security architecture and features is given at [Java Security|http://java.sun.com/javase/6/docs/technotes/guides/security/overview/jsoverview.html].

h2. Enabling Java 2 Security Using Maven

JIRA TUSCANY-2339 allows *Maven* to run all Tuscany itests and vtests with Java 2 security enabled.  To run this Maven profile, you must provide a tuscany.policy file in your ${java.home}/lib/security directory (default location) or provide a tuscany.policy.file property to provide a local file URL, or copy the contents of tuscany.policy to another policy file. As the tuscany.policy file is written, you must have system properties tuscany.home and maven.repos defined, or you must hard code the location of these code bases.

Run the Tuscany test profile with Maven by naming the security profile name explicitly or my providing a tuscany.policy.file property:
{code}
mvn test -P security
{code}

or

{code}
mvn "-Dtuscany.policy.file=file:///e:/tuscany.policy"
{code}

Here is the addition to the pom.xml file to run with security. You may uncomment or add other modules to perform tests.
{code}
        <profile>
            <id>security</id>
            <modules>
                <!-- <module>demos</module> -->
                <module>itest</module>
                <module>vtest</module>
            </modules>
            <activation>
                <property>
                    <name>tuscany.policy.file</name>
                </property>
            </activation>
            <properties>
                <tuscany.policy.file><Your tuscany.policy file location></tuscany.policy.file>
            </properties>
            <id>security</id>
<build>
                <modules><plugins>
                 <!-- <module>demos</module> -->
   <plugin>
                  <module>itest</module>
      <groupId>org.apache.maven.plugins</groupId>
           <module>vtest</module>
             </modules><artifactId>maven-surefire-plugin</artifactId>
            <activation>
            <version>2.3.1</version>
    <property>
                    <name>tuscany.policy.file</name><configuration>
                </property>
            </activation><includes>
            <properties>
                 <tuscany.policy.file><Your tuscany.policy file location></tuscany.policy.file><include>**/*TestCase.java</include>
            </properties>
            <build>
    </includes>
            <plugins>
                <reportFormat>brief</reportFormat>
    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
   <useFile>false</useFile>
                     <artifactId>maven-surefire-plugin</artifactId>
       <forkMode>once</forkMode>
                 <version>2.3.1</version>
           <!-- Place tuscany.policy in your Java home security directory. Alternatively, hardcode the file location here. <configuration>-->
                            <argLine>-Djava.security.manager -Djava.security.policy=${tuscany.policy.file}  <includes>-Dpolicy.allowSystemProperty=true -Djava.security.debug=policy</argLine>
                        </configuration>
        <include>**/*TestCase.java</include>
            </plugin>
                </includes>
plugins>         
            </build>
        <reportFormat>brief</reportFormat>
                            <useFile>false</useFile>
                            <forkMode>once</forkMode>
                            <!-- Place tuscany.policy in your Java home security directory. Alternatively, hardcode the file location here. -->
                            <argLine>-Djava.security.manager -Djava.security.policy=${tuscany.policy.file} -Dpolicy.allowSystemProperty=true -Djava.security.debug=policy</argLine>
                        </configuration>
                    </plugin>
                </plugins>         
            </build>
        </profile>
{code}



h2. Security Tips for Popular Application Servers</profile>
{code}

h2. Enabling Java 2 Security in Eclipse

Many users import Tuscany projects into *Eclipse* or other Integrated Development Environment and run or develop applications in this type of environment. Whether you are running your own SCA application, or one of the many Tuscany samples or demos, the process for running with Java 2 security enabled is the same. Your application or sample has build and runtime dependencies on the Tuscany code, and the application is run with a security profile.

Eclipse provides a run dialog that determines how a project is run. For instance, many Tuscany samples are run as Java applications. The Tuscany samples also provide many test cases that may be run in a JUnit test suite. In either case, you specify Java 2 security options in a similar way. You create a 'run' configuration for your type of code (Java application, Java applet, JUnit test case, etc.). The run dialog has a 'Arguments' tab where you can provide Java Virtual Machine options. You provide the Java 2 security options in the 'Program Arguments' text box.

An example of this configuration is shown here:
!EclipseAppConfig.png!

h2. Security Tips for Popular Application Servers

When Tuscany is run by an application server (whether it be WebSphere, Geronimo, or other), the policy of the server will form the starting point for Tuscany's security policy.

h3. WebSphere Application Server

h3. Geronimo