summaryrefslogtreecommitdiffstats
path: root/site/trunk/site-publish/security-aware-programming-in-tuscany.html
diff options
context:
space:
mode:
Diffstat (limited to 'site/trunk/site-publish/security-aware-programming-in-tuscany.html')
-rw-r--r--site/trunk/site-publish/security-aware-programming-in-tuscany.html247
1 files changed, 247 insertions, 0 deletions
diff --git a/site/trunk/site-publish/security-aware-programming-in-tuscany.html b/site/trunk/site-publish/security-aware-programming-in-tuscany.html
new file mode 100644
index 0000000000..14d9dfd2cd
--- /dev/null
+++ b/site/trunk/site-publish/security-aware-programming-in-tuscany.html
@@ -0,0 +1,247 @@
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+ <HEAD>
+ <!-- generateKeywords macro -->
+ <META name="description" content="Apache Tuscany">
+ <META name="keywords" content="apache, apache tuscany, tuscany, service, services, fabric, soa, service oriented architecture, sca, service component architecture, das, sdo, csa, ruby, opensource">
+ <!-- generateKeywords macro end -->
+
+ <LINK type="text/css" rel="stylesheet" href="http://tuscany.apache.org/stylesheets/default.css">
+ <LINK rel="SHORTCUT ICON" href="https://cwiki.apache.org/confluence/display/TUSCANY/$images/favicon.ico">
+ <TITLE>Apache Tuscany : Security Aware Programming in Tuscany</TITLE>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+
+ <BODY onload="init()">
+ <!-- topNav macro -->
+ <TABLE valign="top" border="0" cellspacing="0" cellpadding="0" width="100%" background="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg">
+ <TR>
+ <TD valing="top" align="left">
+ <A href="https://cwiki.apache.org/confluence/pages/viewpage.action?spaceKey=TUSCANY&title=$siteroot"><IMG src="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg" height="91" width="25" border="0"></A>
+ </TD>
+ <TD>
+ <A href="http://tuscany.apache.org/"><IMG src="http://tuscany.apache.org/images/TuscanyLogo.jpg" border="0"></A>
+ </TD>
+
+ <TD width="100%">
+ &nbsp;
+ </TD>
+
+ <!-- Adds the edit page link to the top banner-->
+ <TD valign="bottom">
+ <DIV style="padding: 2px 10px; margin: 0px;">
+ <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=80637">
+ <IMG src="http://tuscany.apache.org/images/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A>
+ </DIV>
+ </TD>
+
+ </TR>
+ </TABLE>
+ <!-- topNav macro end -->
+
+ <!-- breadCrumbs macro -->
+ <TABLE border="0" cellpadding="2" cellspacing="0" width="100%">
+ <TR class="topBar">
+ <TD align="left" valign="middle" class="topBarDiv" nowrap="true" width="100%">
+ &nbsp;<A href="home.html" title="Apache Tuscany">Apache Tuscany</A>&nbsp;&gt;&nbsp;<A href="home.html" title="Home">Home</A>&nbsp;&gt;&nbsp;<A href="sca-overview.html" title="SCA Overview">SCA Overview</A>&nbsp;&gt;&nbsp;<A href="sca-java.html" title="SCA Java">SCA Java</A>&nbsp;&gt;&nbsp;<A href="java-sca-documentation-menu.html" title="Java SCA Documentation Menu">Java SCA Documentation Menu</A>&nbsp;&gt;&nbsp;<A href="" title="Security Aware Programming in Tuscany">Security Aware Programming in Tuscany</A>
+ </TD>
+
+ <TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true">
+ <A href="http://mail-archives.apache.org/mod_mbox/tuscany-user">User List</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-dev">Dev List</A> | <A href="http://issues.apache.org/jira/browse/Tuscany">Issue Tracker</A>&nbsp;&nbsp;
+ </TD>
+ </TR>
+ </TABLE>
+ <!-- breadCrumbs macro end -->
+
+
+ <TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF">
+ <TR>
+ <TD align="left" valign="top">
+
+ <!-- pageContent macro -->
+ <DIV id="PageContent">
+
+ <DIV class="pagecontent">
+ <DIV class="wiki-content">
+ <H1><A name="SecurityAwareProgramminginTuscany-SecurityAwareProgramminginTuscany."></A>Security Aware Programming in Tuscany.</H1>
+<P><FONT color="green"> <BR>
+<A href="http://vcasmo.com/video/beckerdo/2750" class="external-link" rel="nofollow"><B>Java Security</B></A> is available in Video, use tuscany passcode</FONT> </P>
+
+<H2><A name="SecurityAwareProgramminginTuscany-IntroductiontoJavaSecurity"></A>Introduction to Java Security</H2>
+
+<P>As you develop software for the <B>Apache Tuscany</B> project, it is important to be aware and maintain the security features of the Java platform. Java's success is promoted by its security architecture and relative absence from security problems. Similarly, Tuscany will benefit as a platform if the developers take care to keep it secure and free from ill-intentioned users.</P>
+
+<P>This article focuses on the <B>security manager</B> and <B>access control</B> mechanisms in the Java platform and the Tuscany code base. The focus here is not on SCA applications and samples, but rather contributions that affect the Tuscany runtime including any contributions or additions such as new bindings, implementations, or data bindings. Taking advantage of the security manager and limiting access to secure areas of the code base are the primary defense against unsafe operation of Tuscany's SCA platform. And since Tuscany code is available for anyone to read, it is important to prevent any unprivileged access to the system on which Tuscany is running. This requires that developers understand application runtime and server policies and how to guard the system resources. Here is a good overview of <A href="http://java.sun.com/javase/6/docs/technotes/guides/security/overview/jsoverview.html" class="external-link" rel="nofollow">Java Security</A>.</P>
+
+<P>By default, Java application code and the Tuscany code base run in an unsecure environment with no security manager. This gives the Java application 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.</P>
+
+<P>You may turn security on by running your Tuscany application with the <TT>-Djava.security.manager</TT> option on the command line. The default security manager delegates access control decisions to <TT>java.security.AccessController</TT>. The <TT>AccessController</TT> determines access authority for your Java code by consulting the permissions in a <TT>java.security.Policy</TT> class usually specified in the default <TT>security.policy</TT> file.</P>
+
+<P>There is only one <TT>Policy object</TT> 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 <TT>&quot;-Djava.security.manager -Djava.security.policy=tuscany.policy -Dpolicy.allowSystemProperty=true&quot;</TT> will add the permissions in the tuscany.policy file to the default Java permissions. If you specify <TT>&quot;-Djava.security.policy==tuscany.policy&quot;</TT> you replace the default policy with those specified in the Tuscany policy file. 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.</P>
+
+<P>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.<BR>
+An example of a granting all permission to an unsigned Tuscany code base is given here:</P>
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>security.policy example</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+grant codeBase <SPAN class="code-quote">&quot;file:$/{{user.home}}/tuscany/java/sca/-&quot;</SPAN> {
+ permission java.security.AllPermission;
+};
+</PRE>
+</DIV></DIV>
+
+<P>This example grant statement is quite a broad bludgeon. Namely it says that all Tuscany code has been granted all permissions. This is not much different that running without a security manager. In practice, a user policy will want much finer-grained permissions towards the Tuscany code and allow only specific pieces of the code to have privileged access. The remainder of this article shows how to locate those permissions and how to enable secure checks for them.</P>
+
+<P>In summary, with security on, Tuscany class XYZ can access a secured resource only if the security manager's <TT>AccessController</TT> has determined the proper permissions are available in the security policy. Tuscany code that calls a protected Java API will only work with an <TT>AccessController doPrivileged</TT> block and the proper permissions in place. Otherwise, the Tuscany code will not run properly with security on, and it will throw <TT>SecurityExceptions</TT> left and right. Many times these <TT>SecurityExceptions</TT> will be passed back to the Tuscany runtime and then be wrappered in a <TT>ServiceRuntimeException</TT> and presented to the user. Not good.</P>
+
+<H2><A name="SecurityAwareProgramminginTuscany-CommonJavaAPIsThatRequireSecurityEnablement"></A>Common Java APIs That Require Security Enablement</H2>
+
+<P>What are some of the Java APIs that might cause your Tuscany code to produce a <TT>SecurityException</TT>? In the <A href="http://java.sun.com/javase/reference/api.jsp" class="external-link" rel="nofollow">Java API Reference</A>, any Java API that throws a <TT>SecurityException</TT> is a candidate.<BR>
+For instance, notice that <A href="http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String)" class="external-link" rel="nofollow"><TT>java.lang.System.getProperty(String)</TT></A> may throw a security exception. With security on, you are allowed to read some <TT>System</TT> properties (such as <TT>java.version</TT> or <TT>os.name</TT>) but by default you will get a <TT>SecurityException</TT> on other properties (such as <TT>user.home</TT> or <TT>java.home</TT>). In general, this makes sense because we do not want any intruders to have a map of the file system. A concise list of APIs with security checks is located at <A href="http://java.sun.com/javase/6/docs/technotes/guides/security/permissions.html#PermsAndMethods" class="external-link" rel="nofollow">Methods and the Permissions They Require</A>.</P>
+
+<P>Whenever you use one of these security enabled Java APIs (any API with a &quot;<TT>throws SecurityException</TT>&quot; suffix), you must do two things to ensure your code will run with security on:</P>
+<OL>
+ <LI>Add the required permission to your Tuscany or application sever security policy.</LI>
+ <LI>Add an <TT>AccessController.doPrivileged</TT> call block around your code.<BR>
+This section discusses identifying any necessary security permissions, and the next session shows how to write <TT>AccessController</TT> call blocks.</LI>
+</OL>
+
+
+<P>To be a little more concrete to Tuscany developers, let's go through some common API groups that they are likely to use.</P>
+<OL>
+ <LI><TT>System.getProperty(String)</TT>. This is quite a common item to check to make operating system or Java version specific code. If you use this API you need to add <TT>java.util.PropertyPermission</TT> to the security policy. For example, this permission allows the Tuscany code base to read two system properties:
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>security.policy property read example</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+grant codeBase <SPAN class="code-quote">&quot;file:$/{{user.home}}/tuscany/java/sca/-&quot;</SPAN> {
+ permission java.util.PropertyPermission <SPAN class="code-quote">&quot;user.home&quot;</SPAN>, <SPAN class="code-quote">&quot;read&quot;</SPAN>;
+ permission java.util.PropertyPermission <SPAN class="code-quote">&quot;java.home&quot;</SPAN>, <SPAN class="code-quote">&quot;read&quot;</SPAN>;
+};
+</PRE>
+</DIV></DIV></LI>
+ <LI>File IO. If you create a file stream, or attempt to check if a <TT>File</TT> exists or is a directory, or can read or write, you will have to add <TT>java.io.FilePermissions</TT>.</LI>
+ <LI>ClassLoader. Anytime you access the ClassLoader via <TT>getClassLoader()</TT> (which is common if you want to load a resource), you will have to add a <TT>java.lang.RuntimePermission</TT>.</LI>
+ <LI>Introspection. Whenever you do any sort of dynamic class loading and execution, say you want to check for methods in a business interface, or you want to instantiate a data object, you are going to add a <TT>java.lang.RuntimePermission</TT>.</LI>
+ <LI>URLS and sockets. Any sort of network access via <TT>URL</TT> streams or sockets will have to be checked by the security manager. You will have to add <TT>java.lang.RuntimePermission</TT> or <TT>java.net.SocketPermission</TT>.</LI>
+ <LI>Threads. Any starting or stopping or checking for threads is going to be guarded and you will have to have the proper <TT>java.lang.RuntimePermission</TT>.</LI>
+ <LI>The Security stack. Need it be said, but if you attempt to access the <TT>SecurityManager</TT>, <TT>AccessController</TT>, <TT>Policies</TT>, or other parts of the security architecture you are going to need <TT>java.security.SecurityPermission</TT>. In other words, hands off the security system.</LI>
+</OL>
+
+
+<P>This list is just a general overview. Once again, any API that throws a <TT>SecurityException</TT> is something that your Tuscany code should be privileged and permitted to use.</P>
+
+<H2><A name="SecurityAwareProgramminginTuscany-HowtoWriteAccessControlBlocks."></A>How to Write Access Control Blocks.</H2>
+
+<P>The final step of making your code security enabled is to add <TT>AccessController</TT> privileged blocks around your enabled code. You must be careful here. You cannot put a privileged block with a wide scope. That is similar to running with security turned off. You also must be careful not to grant privilege code that a malicious user could use. Be very careful of granting privilege to any public API that a user can use with malicious parameters. Here is a <A href="http://java.sun.com/javase/6/docs/technotes/guides/security/doprivileged.html" class="external-link" rel="nofollow">more in-depth article</A>.</P>
+
+<P>The type of coding pattern you use is based primarily on three considerations:</P>
+<UL>
+ <LI>the return type of the checked call</LI>
+ <LI>the input parameters to the checked call</LI>
+ <LI>the exceptions thrown by the checked call.</LI>
+</UL>
+
+
+<P>In the simplest case, let's say you use a checked Java API that throws no exceptions other than <TT>SecurityException</TT>. (Recall that <TT>SecurityException</TT> is thrown by all of these APIs.) For instance, your brand new Tuscany &quot;Blatz&quot; extension needs to load the &quot;blatz&quot; library before it runs.<BR>
+This is how you security enable the loading of the library.</P>
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>AccessController doPrivileged block - No parameters</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ <SPAN class="code-comment">// ... unchecked code here...
+</SPAN> AccessController.doPrivileged(<SPAN class="code-keyword">new</SPAN> PrivilegedAction&lt;<SPAN class="code-object">Object</SPAN>&gt;() {
+ <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">Object</SPAN> run() {
+ <SPAN class="code-object">System</SPAN>.loadLibrary(<SPAN class="code-quote">&quot;blatz&quot;</SPAN>);
+ <SPAN class="code-keyword">return</SPAN> <SPAN class="code-keyword">null</SPAN>;
+ }
+ });
+ <SPAN class="code-comment">// ... more unchecked code here </SPAN>
+</PRE>
+</DIV></DIV>
+<P>Notice that the code is using the Java type safe syntax to ensure the proper casting of the method run return type. The class in the &lt;class specification&gt; should always match the return type class type.</P>
+
+<P>In the next example, let us examine how a Java API with a boolean return type is handled. Notice that we are using the autoboxing feature of Java to convert from <TT>boolean</TT> to <TT>Boolean</TT>.</P>
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>AccessController doPrivileged block - With Return Type</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ <SPAN class="code-object">boolean</SPAN> isDirectory = AccessController.doPrivileged(<SPAN class="code-keyword">new</SPAN> PrivilegedAction&lt;<SPAN class="code-object">Boolean</SPAN>&gt;() {
+ <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">Boolean</SPAN> run() {
+ <SPAN class="code-keyword">return</SPAN> rootFolder.isDirectory();
+ }
+ });
+</PRE>
+</DIV></DIV>
+<P>Using this succinct anonymous class, you must make sure any input parameters are final instances. This is a requirement of the Java syntax. If you have a parameter that has undergone multiple assignments, you can easily create a final version of that input parameter and pass it into the block.</P>
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>AccessController doPrivileged block - Input Parameters</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ URL constructedURL = protocol;
+ constructedURL += pathName;
+ constructedURL += parameters;
+
+ <SPAN class="code-keyword">final</SPAN> URL xsdURL = constructedURL;
+ URL definitionsFileUrl = AccessController.doPrivileged(<SPAN class="code-keyword">new</SPAN> PrivilegedAction&lt;URL&gt;() {
+ <SPAN class="code-keyword">public</SPAN> URL run() {
+ <SPAN class="code-keyword">return</SPAN> getClass().getClassLoader().getResource(definitionsFile);
+ }
+ });
+</PRE>
+</DIV></DIV>
+<P>Finally, if your checked Java API throws an exception, such as the <TT>IOException</TT> shown here, you need to catch it and cast it to match any checked exceptions on your method, or you need to add the PrivilegedActionException to the throws signature of your method.</P>
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>AccessController doPrivileged block - With Exceptions</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ InputStream is;
+ <SPAN class="code-keyword">try</SPAN> {
+ is = AccessController.doPrivileged(<SPAN class="code-keyword">new</SPAN> PrivilegedExceptionAction&lt;InputStream&gt;() {
+ <SPAN class="code-keyword">public</SPAN> InputStream run() <SPAN class="code-keyword">throws</SPAN> IOException {
+ <SPAN class="code-keyword">return</SPAN> url.openStream();
+ }
+ });
+ } <SPAN class="code-keyword">catch</SPAN> ( PrivilegedActionException e ) {
+ <SPAN class="code-keyword">throw</SPAN> (IOException) e.getException();
+ }
+</PRE>
+</DIV></DIV>
+
+<P>This article shows just a few techniques that cover many of the security issues that arise in the Tuscany code base. If you are aware of the Java security architecture and how to control access to guarded resources, you can guard against malicious users who might use the Tuscany code base for no good.</P>
+
+ </DIV>
+ </DIV>
+ </DIV>
+ <!-- pageContent macro end -->
+
+ </TD>
+ </TR>
+ </TABLE>
+
+ <!-- footer macro -->
+ <SCRIPT src="http://www.google-analytics.com/urchin.js" type="text/javascript">
+ </SCRIPT>
+ <SCRIPT type="text/javascript">
+ _uacct = "UA-1174707-5";
+ urchinTracker();
+ </SCRIPT>
+
+ <A href="http://www.statcounter.com/" target="_blank"><IMG src="http://c26.statcounter.com/counter.php?sc_project=2619156&java=0&security=94bd7e7d&invisible=0" alt="website stats" border="0"></A>
+
+ <DIV class="footer">
+ Copyright � 2003-2012, The Apache Software Foundation&nbsp;&nbsp;</BR>
+ Apache Tuscany and the Apache Tuscany project logo are trademarks of The Apache Software Foundation.
+ </DIV>
+ <!-- footer macro end -->
+
+ </BODY>
+</HTML>