ejbd-transport.html - tomee-site-pub - Git at Google

 <!DOCTYPE html>
 <html lang="en">
   <head>

     <meta charset="UTF-8">
       <title>Ejbd Transport</title>
     <meta name="description" content="Apache TomEE">
     <meta name="author" content="Apache TomEE">
     <meta name="google-translate-customization" content="f36a520c08f4c9-0a04e86a9c075ce9-g265f3196f697cf8f-10">
     <meta http-equiv="Pragma" content="no-cache">
     <meta http-equiv="Expires" content="0">
     <meta http-equiv="Cache-Control" content="no-store, no-cache, must-revalidate, max-age=0">

     <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
     <!--[if lt IE 9]>
       <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
     <![endif]-->

     <!-- Le styles -->
     <link href="./resources/css/bootstrap.css" rel="stylesheet">
     <link href="./resources/css/prettify.css" rel="stylesheet">
     <!--link href="./resources/css/bootstrap-mods.css" rel="stylesheet"-->
     <link href="./resources/css/main.css" rel="stylesheet">
     <link href="./resources/font-awesome-4.6.3/css/font-awesome.min.css" rel="stylesheet">

     <script type="text/javascript">
         var t = encodeURIComponent(document.title.replace(/^\s+|\s+$/g,""));
         var u = encodeURIComponent(""+document.URL);

       function fbshare () {
           window.open(
                   "http://www.facebook.com/sharer/sharer.php?u="+u,
                   'Share on Facebook',
                   'width=640,height=426');
       };
       function gpshare () {
           window.open(
                   "https://plus.google.com/share?url="+u,
                   'Share on Google+',
                   'width=584,height=385');
       };
       function twshare () {
           window.open(
                   "https://twitter.com/intent/tweet?url="+u+"&text="+t,
                   'Share on Twitter',
                   'width=800,height=526');
       };
       function pinshare () {
           window.open("//www.pinterest.com/pin/create/button/?url="+u+"&media=http%3A%2F%2Ftomee.apache.org%2Fresources%2Fimages%2Ffeather-logo.png&description="+t,
                   'Share on Pinterest',
                   'width=800,height=526');
       };
     </script>

     <!-- Le fav and touch icons -->
     <link rel="shortcut icon" href="./favicon.ico">
     <link rel="apple-touch-icon" href="./resources/images/apple-touch-icon.png">
     <link rel="apple-touch-icon" sizes="72x72" href="./resources/images/apple-touch-icon-72x72.png">
     <link rel="apple-touch-icon" sizes="114x114" href="./resources/images/apple-touch-icon-114x114.png">

     <script src="./resources/js/prettify.js" type="text/javascript"></script>
     <script src="./resources/js/jquery-latest.js"></script>
     <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
     <script src="./resources/js/common.js"></script>
     <script src="./resources/js/prettyprint.js"></script>
     <!--script src="//assets.pinterest.com/js/pinit.js" type="text/javascript" async></script//-->

     <script type="text/javascript">

       var _gaq = _gaq || [];
       _gaq.push(['_setAccount', 'UA-2717626-1']);
       _gaq.push(['_setDomainName', 'apache.org']);
       _gaq.push(['_trackPageview']);

       (function() {
         var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
         ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
       })();

     </script>
   </head>

   <body>

     <div class="topbar" data-dropdown="dropdown">
       <div class="fill">
         <div class="container">
           <a class="brand" href="./index.html">Apache TomEE</a>
           <ul class="nav">
               <li class="dropdown">
                   <a class="dropdown-toggle" data-toggle="dropdown" href="#">
                   Apache
                       <b class="caret"></b>
                   </a>
                   <ul class="dropdown-menu">
                      <!-- <li><a href="./misc/whoweare.html">Who we are?</a></li> -->
                      <!-- <li><a href="./misc/heritage.html">Heritage</a></li> -->
                      <li><a href="http://www.apache.org">Apache Home</a></li>
                      <!-- <li><a href="./misc/resources.html">Resources</a></li> -->
                      <li><a href="./misc/contact.html">Contact</a></li>
                      <li><a href="./misc/legal.html">Legal</a></li>
                      <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
                      <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
                      <li class="divider"/>
                      <li><a href="http://www.apache.org/security">Security</a></li>
                   </ul>
               </li>
               <li><a href="./index.html">Home</a></li>
               <li><a href="./downloads.html">Downloads</a></li>
               <li><a href="./documentation.html">Documentation</a></li>
               <li><a href="./examples-trunk/index.html">Examples</a></li>
               <li><a href="./support.html">Support</a></li>
               <li><a href="./contribute.html">Contribute</a></li>
               <li><a href="./security/index.html">Security</a></li>
           </ul>

             <!-- Google CSE Search Box Begins  -->
             <FORM class="pull-right" id="searchbox_010475492895890475512:_t4iqjrgx90" action="http://www.google.com/cse">
                 <INPUT type="hidden" name="cx" value="010475492895890475512:_t4iqjrgx90">
                 <INPUT type="hidden" name="cof" value="FORID:0">
                 <INPUT size="18" width="130" style="width:130px" name="q" type="text" placeholder="Search">
             </FORM>
             <!--<SCRIPT type="text/javascript" src="http://www.google.com/coop/cse/brand?form=searchbox_010475492895890475512:_t4iqjrgx90"></SCRIPT>-->
             <!-- Google CSE Search Box Ends -->
         </div>
       </div>
     </div>

     <div class="container">


 <div class="page-header">
     <small><a href="./index.html">Home</a></small><br>
     <h1>Ejbd Transport

         <div style="float: right; position: relative; bottom: -10px; ">
             <a onclick="javascript:gpshare()" class="gp-share sprite" title="Share on Google+">share [gp]</a>
             <a onclick="javascript:fbshare()" class="fb-share sprite" title="Share on Facebook">share [fb]</a>
             <a onclick="javascript:twshare()" class="tw-share sprite" title="Share on Twitter">share [tw]</a>
             <a onclick="javascript:pinshare()" class="pin-share sprite" title="Share on Pinterest">share [pin]</a>
             <a data-toggle="modal" href="#edit" class="edit-page" title="Contribute to this Page">contribute</a>
         </div>
     </h1>
 </div>

 <p>The Ejbd Transport allows to remotely access EJBs that have a remote interface.
 Nevertheless it is not based on IIOP.</p>

 <p>Ejbd Transport is different using TomEE or OpenEJB.</p>

 <p>In OpenEJB it uses openejb http layer and ejbd is configured through ejbd service (same for ejbds).
 So to activate/deactivate them use conf/ejbd(s).properties files. You can set property disabled to true
 if you don't want them to be started.</p>

 <p>In TomEE the transport is the Tomcat one. It uses a servlet brought by TomEE webapp.
 Here is the servlet as defined in TomEE webapp:</p>

 <pre><code>&lt;servlet&gt;
     &lt;servlet-name&gt;ServerServlet&lt;/servlet-name&gt;
     &lt;servlet-class&gt;org.apache.openejb.server.httpd.ServerServlet&lt;/servlet-class&gt;
 &lt;/servlet&gt;

 &lt;servlet-mapping&gt;
     &lt;servlet-name&gt;ServerServlet&lt;/servlet-name&gt;
     &lt;url-pattern&gt;/ejb/*&lt;/url-pattern&gt;
 &lt;/servlet-mapping&gt;
 </code></pre>

 <p>You can easily remove it if you don't use remote EJBs. Another way is to deactivate the servlet
 using the "activated" init parameter of the servlet.</p>

 <p>Finally you can move this servlet in your own webapp if you want to use a provider url
 containing your webapp context. Simply copy paste the servlet definition in your web.xml
 and set the url mapping to what you want (let say /foo/*). Then use the provider url
 http://&lt;host&gt;:&lt;port&gt;/&lt;webapp context name&gt;/foo</p>

 <h3>Remote communication and serialization</h3>

 <p>Remotely calling EJBs, independent of using Ejbd or other RMI/IIOP based protocols, involves serialization and deserialization of objects.
 Deserializing unknown content coming from an untrusted source imposes a security risk as the stream could be manipulated.
 A much publicized <a href="http://www.kb.cert.org/vuls/id/576313">vulnerability</a> was found in the commons-collections library which allowed to remotely execute arbitrary code simply by deserializing instances of the class <code>InvokerTransformer</code>.</p>

 <p>To prevent this risk TomEE and the OpenEJB client since 1.7.4 before deserializing every object checks its class against a configurable blacklist and a whitelist.
 The default black list is defined as <code>*</code>, meaning that requests cannot be deserialized at all and the Ejbd transport in fact cannot be used.</p>

 <p>The blacklist and whitelist is configured via the system properties:</p>

 <ul>
 <li><code>tomee.serialization.class.whitelist</code></li>
 <li><code>tomee.serialization.class.blacklist</code></li>
 </ul>

 <p>You will also find these properties in <a href="properties-listing.html">System Properties Listing</a></p>

 <p>These rules apply for the whitelist:</p>

 <ul>
 <li>The whitelist has a lower priority than the blacklist. That means a class that is part of the blacklist cannot be whitelisted and will always be refused.</li>
 <li>If a whitelist is not defined, either by not defining the property at all or defining it with an empty value, every class is on the whitelist. In this case only the blacklist applies.</li>
 <li>If a whitelist is defined it must be a comma separated list of prefixes of fully qualified class names. Then deserialization of an object fails if its class is not part of this whitelist. A class is on the whitelist if its fully qualified classname is prefixed by one of the values in the whitelist.</li>
 </ul>

 <p>These rules apply for the blacklist:</p>

 <ul>
 <li>If the blacklist should be deactivated it must be configured to the value <code>-</code>. This will open your system to the serialization vulnerability if you don't configure a whitelist!</li>
 <li>If the blacklist is not configured its default value is <code>org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process</code> so that for example the class <code>org.apache.commons.collections.functors.InvokerTransformer</code> cannot be deserialized.</li>
 <li>If the blacklist is configured with an empty value the blacklist is effectively <code>*</code>, therefore preventing any Ejbd communication.</li>
 <li>If you want to blacklist certain classes the property must be configured to a comma separated list of prefixes of fully qualified class names. A class is on the blacklist if its fully qualified classname is prefixed by one of the values in the blacklist.</li>
 </ul>

 <p>The default for <code>tomee.serialization.class.whitelist</code> is empty, the default for <code>tomee.serialization.class.blacklist</code> is <code>*</code> since TomEE 1.7.4.</p>

 <p>If an EJB request fails because a class is not whitelisted you will find this log entry:</p>

 <pre><code>WARN - "null OEJP/4.7" FAIL "Security error - foo.Bar is not whitelisted as deserializable, prevented before loading it." - Debug for StackTrace
 </code></pre>

 <p>If you trust this class and want to support serialization in remote communication you have to configure these properties appropriately both on server side as well as on client side.</p>

 <p>If you only want to support serialization of the classes <code>foo.Bar</code> and <code>foo.Baz</code> you can configure the properties like this:</p>

 <pre><code>tomee.serialization.class.whitelist = foo.Bar,foo.Baz
 tomee.serialization.class.blacklist = -
 </code></pre>

 <p>If you trust all classes in the package <code>foo</code> define the properties like this:</p>

 <pre><code>tomee.serialization.class.whitelist = foo.
 tomee.serialization.class.blacklist = -
 </code></pre>

 <p>(Don't forget the trailing <code>.</code> after foo, as it will also whitelist all classes in the package <code>foo2</code> otherwise.)</p>

 <p>If you trust all classes in the package <code>foo</code> except the class <code>foo.Bar</code> you have to configure the properties like this:</p>

 <pre><code>tomee.serialization.class.whitelist = foo.
 tomee.serialization.class.blacklist = foo.Bar
 </code></pre>

 <h4>Revert to behavior of TomEE 1.7.3</h4>

 <p>TomEE 1.7.3 already contained a fixed blacklist that was not configurable and contained the packages org.codehaus.groovy.runtime, org.apache.commons.collections.functors and org.apache.xalan including subpackages and the class java.lang.Process.
 If you know that your applications runs on TomEE 1.7.3 but does not on TomEE 1.7.4 showing the aforementioned log message, you can define the configuration so that the serialization will work in the same way as it did with TomEE 1.7.3:</p>

 <pre><code>tomee.serialization.class.whitelist =
 tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process
 </code></pre>

 <p>Please note that with this configuration your server may be vulnerable to Java serialization attacks not yet identified by the Zero Day initiative.
 Also note that the following versions of the affected libraries have been patched and approved by the Zero Day initiative and <em>may</em> be safe to deserialize.</p>

 <ul>
 <li>Groovy 2.4.4</li>
 <li>Commons Collections 3.2.2</li>
 <li>Xalan 2.7.2</li>
 </ul>

 <p>As Ejbd transport is tunneled over HTTP please make sure that the <code>ServerServlet</code> is not publicly accessible.
 When the applications running on TomEE do not package the <code>ServerServlet</code> themselves ensure that the URL http://&lt;host&gt;:&lt;port&gt;/tomee/ejb is not accessible from untrusted sources.</p>

 <p>If your applications package declare it in their own web.xml make sure that the respective URL is not accessible from untrusted sources.</p>

 <h4>Revert to behavior of TomEE 1.7.2</h4>

 <p>TomEE 1.7.2 did not have any kind of blacklist when deserializing objects over Ejbd.
 If you want to revert to this behavior you can simply deactivate the blacklist with this configuration:</p>

 <pre><code>tomee.serialization.class.whitelist =
 tomee.serialization.class.blacklist = -
 </code></pre>

 <p>Note that this configuration makes your system highly vulnerable to serialization attacks!
 Consider your system as unsafe!</p>

 <h4>Remote communication and Arquillian tests</h4>

 <p>The mechanism described above principally also works when running Arquillian tests.
 As the Ejbd transport is already used for deploying applications all Arquillian tests would fail with the default settings.</p>

 <p>Therefore the TomEE Arquillian adapter automatically starts the container so that all classes except for a set of well-know dangerous classes are whitelisted.</p>

 <p>As Ejbd is by default disabled since TomEE 7.0.0, the TomEE Arquillian adapter automatically activates it when starting a remote container.</p>

 <h4>Remote communication and the TomEE Maven Plugin</h4>

 <p>The same mentioned above on Arquillian and TomEE is also valid when using the TomEE Maven Plugin.</p>


         <div id="edit" class="modal hide fade in" style="display: none; ">
             <div class="modal-header">
                 <a class="close" data-dismiss="modal">x</a>

                 <h3>Thank you for contributing to the documentation!</h3>
             </div>
             <div class="modal-body">
                 <h4>Any help with the documentation is greatly appreciated.</h4>
                 <p>All edits are reviewed before going live, so feel free to do much more than fix typos or links.  If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it.  Don't be surprised if we like it so much we ask you for help with other pages :)</p>
                 <small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
                 <!--[if gt IE 6]>
                 <h4>Internet Explorer Users</h4>
                 <p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
                 <![endif]-->

             </div>
             <div class="modal-footer">
                 Do you have an Apache ID?
                 <a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
                 <a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
             </div>
         </div>
         <script src="./resources/js/bootstrap-modal.js"></script>

         <footer>
             <p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
                 Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation.
                 All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
         </footer>

     </div> <!-- /container -->

     <!-- Javascript
     ================================================== -->
     <!-- Placed at the end of the document so the pages load faster -->
     <script src="./resources/js/bootstrap-dropdown.js"></script>

   </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>

	<meta charset="UTF-8">
	<title>Ejbd Transport</title>
	<meta name="description" content="Apache TomEE">
	<meta name="author" content="Apache TomEE">
	<meta name="google-translate-customization" content="f36a520c08f4c9-0a04e86a9c075ce9-g265f3196f697cf8f-10">
	<meta http-equiv="Pragma" content="no-cache">
	<meta http-equiv="Expires" content="0">
	<meta http-equiv="Cache-Control" content="no-store, no-cache, must-revalidate, max-age=0">

	<!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
	<!--[if lt IE 9]>
	<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
	<![endif]-->

	<!-- Le styles -->
	<link href="./resources/css/bootstrap.css" rel="stylesheet">
	<link href="./resources/css/prettify.css" rel="stylesheet">
	<!--link href="./resources/css/bootstrap-mods.css" rel="stylesheet"-->
	<link href="./resources/css/main.css" rel="stylesheet">
	<link href="./resources/font-awesome-4.6.3/css/font-awesome.min.css" rel="stylesheet">

	<script type="text/javascript">
	var t = encodeURIComponent(document.title.replace(/^\s+\|\s+$/g,""));
	var u = encodeURIComponent(""+document.URL);

	function fbshare () {
	window.open(
	"http://www.facebook.com/sharer/sharer.php?u="+u,
	'Share on Facebook',
	'width=640,height=426');
	};
	function gpshare () {
	window.open(
	"https://plus.google.com/share?url="+u,
	'Share on Google+',
	'width=584,height=385');
	};
	function twshare () {
	window.open(
	"https://twitter.com/intent/tweet?url="+u+"&text="+t,
	'Share on Twitter',
	'width=800,height=526');
	};
	function pinshare () {
	window.open("//www.pinterest.com/pin/create/button/?url="+u+"&media=http%3A%2F%2Ftomee.apache.org%2Fresources%2Fimages%2Ffeather-logo.png&description="+t,
	'Share on Pinterest',
	'width=800,height=526');
	};
	</script>

	<!-- Le fav and touch icons -->
	<link rel="shortcut icon" href="./favicon.ico">
	<link rel="apple-touch-icon" href="./resources/images/apple-touch-icon.png">
	<link rel="apple-touch-icon" sizes="72x72" href="./resources/images/apple-touch-icon-72x72.png">
	<link rel="apple-touch-icon" sizes="114x114" href="./resources/images/apple-touch-icon-114x114.png">

	<script src="./resources/js/prettify.js" type="text/javascript"></script>
	<script src="./resources/js/jquery-latest.js"></script>
	<script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
	<script src="./resources/js/common.js"></script>
	<script src="./resources/js/prettyprint.js"></script>
	<!--script src="//assets.pinterest.com/js/pinit.js" type="text/javascript" async></script//-->

	<script type="text/javascript">

	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-2717626-1']);
	_gaq.push(['_setDomainName', 'apache.org']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();

	</script>
	</head>

	<body>

	<div class="topbar" data-dropdown="dropdown">
	<div class="fill">
	<div class="container">
	<a class="brand" href="./index.html">Apache TomEE</a>
	<ul class="nav">
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">
	Apache
	<b class="caret"></b>
	</a>
	<ul class="dropdown-menu">
	<!-- <li><a href="./misc/whoweare.html">Who we are?</a></li> -->
	<!-- <li><a href="./misc/heritage.html">Heritage</a></li> -->
	<li><a href="http://www.apache.org">Apache Home</a></li>
	<!-- <li><a href="./misc/resources.html">Resources</a></li> -->
	<li><a href="./misc/contact.html">Contact</a></li>
	<li><a href="./misc/legal.html">Legal</a></li>
	<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
	<li class="divider"/>
	<li><a href="http://www.apache.org/security">Security</a></li>
	</ul>
	</li>
	<li><a href="./index.html">Home</a></li>
	<li><a href="./downloads.html">Downloads</a></li>
	<li><a href="./documentation.html">Documentation</a></li>
	<li><a href="./examples-trunk/index.html">Examples</a></li>
	<li><a href="./support.html">Support</a></li>
	<li><a href="./contribute.html">Contribute</a></li>
	<li><a href="./security/index.html">Security</a></li>
	</ul>

	<!-- Google CSE Search Box Begins -->
	<FORM class="pull-right" id="searchbox_010475492895890475512:_t4iqjrgx90" action="http://www.google.com/cse">
	<INPUT type="hidden" name="cx" value="010475492895890475512:_t4iqjrgx90">
	<INPUT type="hidden" name="cof" value="FORID:0">
	<INPUT size="18" width="130" style="width:130px" name="q" type="text" placeholder="Search">
	</FORM>
	<!--<SCRIPT type="text/javascript" src="http://www.google.com/coop/cse/brand?form=searchbox_010475492895890475512:_t4iqjrgx90"></SCRIPT>-->
	<!-- Google CSE Search Box Ends -->
	</div>
	</div>
	</div>

	<div class="container">


	<div class="page-header">
	<small><a href="./index.html">Home</a></small><br>
	<h1>Ejbd Transport

	<div style="float: right; position: relative; bottom: -10px; ">
	<a onclick="javascript:gpshare()" class="gp-share sprite" title="Share on Google+">share [gp]</a>
	<a onclick="javascript:fbshare()" class="fb-share sprite" title="Share on Facebook">share [fb]</a>
	<a onclick="javascript:twshare()" class="tw-share sprite" title="Share on Twitter">share [tw]</a>
	<a onclick="javascript:pinshare()" class="pin-share sprite" title="Share on Pinterest">share [pin]</a>
	<a data-toggle="modal" href="#edit" class="edit-page" title="Contribute to this Page">contribute</a>
	</div>
	</h1>
	</div>

	<p>The Ejbd Transport allows to remotely access EJBs that have a remote interface.
	Nevertheless it is not based on IIOP.</p>

	<p>Ejbd Transport is different using TomEE or OpenEJB.</p>

	<p>In OpenEJB it uses openejb http layer and ejbd is configured through ejbd service (same for ejbds).
	So to activate/deactivate them use conf/ejbd(s).properties files. You can set property disabled to true
	if you don't want them to be started.</p>

	<p>In TomEE the transport is the Tomcat one. It uses a servlet brought by TomEE webapp.
	Here is the servlet as defined in TomEE webapp:</p>

	<pre><code><servlet>
	<servlet-name>ServerServlet</servlet-name>
	<servlet-class>org.apache.openejb.server.httpd.ServerServlet</servlet-class>
	</servlet>

	<servlet-mapping>
	<servlet-name>ServerServlet</servlet-name>
	<url-pattern>/ejb/*</url-pattern>
	</servlet-mapping>
	</code></pre>

	<p>You can easily remove it if you don't use remote EJBs. Another way is to deactivate the servlet
	using the "activated" init parameter of the servlet.</p>

	<p>Finally you can move this servlet in your own webapp if you want to use a provider url
	containing your webapp context. Simply copy paste the servlet definition in your web.xml
	and set the url mapping to what you want (let say /foo/*). Then use the provider url
	http://<host>:<port>/<webapp context name>/foo</p>

	<h3>Remote communication and serialization</h3>

	<p>Remotely calling EJBs, independent of using Ejbd or other RMI/IIOP based protocols, involves serialization and deserialization of objects.
	Deserializing unknown content coming from an untrusted source imposes a security risk as the stream could be manipulated.
	A much publicized <a href="http://www.kb.cert.org/vuls/id/576313">vulnerability</a> was found in the commons-collections library which allowed to remotely execute arbitrary code simply by deserializing instances of the class <code>InvokerTransformer</code>.</p>

	<p>To prevent this risk TomEE and the OpenEJB client since 1.7.4 before deserializing every object checks its class against a configurable blacklist and a whitelist.
	The default black list is defined as <code>*</code>, meaning that requests cannot be deserialized at all and the Ejbd transport in fact cannot be used.</p>

	<p>The blacklist and whitelist is configured via the system properties:</p>

	<ul>
	<li><code>tomee.serialization.class.whitelist</code></li>
	<li><code>tomee.serialization.class.blacklist</code></li>
	</ul>

	<p>You will also find these properties in <a href="properties-listing.html">System Properties Listing</a></p>

	<p>These rules apply for the whitelist:</p>

	<ul>
	<li>The whitelist has a lower priority than the blacklist. That means a class that is part of the blacklist cannot be whitelisted and will always be refused.</li>
	<li>If a whitelist is not defined, either by not defining the property at all or defining it with an empty value, every class is on the whitelist. In this case only the blacklist applies.</li>
	<li>If a whitelist is defined it must be a comma separated list of prefixes of fully qualified class names. Then deserialization of an object fails if its class is not part of this whitelist. A class is on the whitelist if its fully qualified classname is prefixed by one of the values in the whitelist.</li>
	</ul>

	<p>These rules apply for the blacklist:</p>

	<ul>
	<li>If the blacklist should be deactivated it must be configured to the value <code>-</code>. This will open your system to the serialization vulnerability if you don't configure a whitelist!</li>
	<li>If the blacklist is not configured its default value is <code>org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process</code> so that for example the class <code>org.apache.commons.collections.functors.InvokerTransformer</code> cannot be deserialized.</li>
	<li>If the blacklist is configured with an empty value the blacklist is effectively <code>*</code>, therefore preventing any Ejbd communication.</li>
	<li>If you want to blacklist certain classes the property must be configured to a comma separated list of prefixes of fully qualified class names. A class is on the blacklist if its fully qualified classname is prefixed by one of the values in the blacklist.</li>
	</ul>

	<p>The default for <code>tomee.serialization.class.whitelist</code> is empty, the default for <code>tomee.serialization.class.blacklist</code> is <code>*</code> since TomEE 1.7.4.</p>

	<p>If an EJB request fails because a class is not whitelisted you will find this log entry:</p>

	<pre><code>WARN - "null OEJP/4.7" FAIL "Security error - foo.Bar is not whitelisted as deserializable, prevented before loading it." - Debug for StackTrace
	</code></pre>

	<p>If you trust this class and want to support serialization in remote communication you have to configure these properties appropriately both on server side as well as on client side.</p>

	<p>If you only want to support serialization of the classes <code>foo.Bar</code> and <code>foo.Baz</code> you can configure the properties like this:</p>

	<pre><code>tomee.serialization.class.whitelist = foo.Bar,foo.Baz
	tomee.serialization.class.blacklist = -
	</code></pre>

	<p>If you trust all classes in the package <code>foo</code> define the properties like this:</p>

	<pre><code>tomee.serialization.class.whitelist = foo.
	tomee.serialization.class.blacklist = -
	</code></pre>

	<p>(Don't forget the trailing <code>.</code> after foo, as it will also whitelist all classes in the package <code>foo2</code> otherwise.)</p>

	<p>If you trust all classes in the package <code>foo</code> except the class <code>foo.Bar</code> you have to configure the properties like this:</p>

	<pre><code>tomee.serialization.class.whitelist = foo.
	tomee.serialization.class.blacklist = foo.Bar
	</code></pre>

	<h4>Revert to behavior of TomEE 1.7.3</h4>

	<p>TomEE 1.7.3 already contained a fixed blacklist that was not configurable and contained the packages org.codehaus.groovy.runtime, org.apache.commons.collections.functors and org.apache.xalan including subpackages and the class java.lang.Process.
	If you know that your applications runs on TomEE 1.7.3 but does not on TomEE 1.7.4 showing the aforementioned log message, you can define the configuration so that the serialization will work in the same way as it did with TomEE 1.7.3:</p>

	<pre><code>tomee.serialization.class.whitelist =
	tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process
	</code></pre>

	<p>Please note that with this configuration your server may be vulnerable to Java serialization attacks not yet identified by the Zero Day initiative.
	Also note that the following versions of the affected libraries have been patched and approved by the Zero Day initiative and <em>may</em> be safe to deserialize.</p>

	<ul>
	<li>Groovy 2.4.4</li>
	<li>Commons Collections 3.2.2</li>
	<li>Xalan 2.7.2</li>
	</ul>

	<p>As Ejbd transport is tunneled over HTTP please make sure that the <code>ServerServlet</code> is not publicly accessible.
	When the applications running on TomEE do not package the <code>ServerServlet</code> themselves ensure that the URL http://<host>:<port>/tomee/ejb is not accessible from untrusted sources.</p>

	<p>If your applications package declare it in their own web.xml make sure that the respective URL is not accessible from untrusted sources.</p>

	<h4>Revert to behavior of TomEE 1.7.2</h4>

	<p>TomEE 1.7.2 did not have any kind of blacklist when deserializing objects over Ejbd.
	If you want to revert to this behavior you can simply deactivate the blacklist with this configuration:</p>

	<pre><code>tomee.serialization.class.whitelist =
	tomee.serialization.class.blacklist = -
	</code></pre>

	<p>Note that this configuration makes your system highly vulnerable to serialization attacks!
	Consider your system as unsafe!</p>

	<h4>Remote communication and Arquillian tests</h4>

	<p>The mechanism described above principally also works when running Arquillian tests.
	As the Ejbd transport is already used for deploying applications all Arquillian tests would fail with the default settings.</p>

	<p>Therefore the TomEE Arquillian adapter automatically starts the container so that all classes except for a set of well-know dangerous classes are whitelisted.</p>

	<p>As Ejbd is by default disabled since TomEE 7.0.0, the TomEE Arquillian adapter automatically activates it when starting a remote container.</p>

	<h4>Remote communication and the TomEE Maven Plugin</h4>

	<p>The same mentioned above on Arquillian and TomEE is also valid when using the TomEE Maven Plugin.</p>




	<div id="edit" class="modal hide fade in" style="display: none; ">
	<div class="modal-header">
	<a class="close" data-dismiss="modal">x</a>

	<h3>Thank you for contributing to the documentation!</h3>
	</div>
	<div class="modal-body">
	<h4>Any help with the documentation is greatly appreciated.</h4>
	<p>All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)</p>
	<small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
	<!--[if gt IE 6]>
	<h4>Internet Explorer Users</h4>
	<p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
	<![endif]-->

	</div>
	<div class="modal-footer">
	Do you have an Apache ID?
	<a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
	<a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
	</div>
	</div>
	<script src="./resources/js/bootstrap-modal.js"></script>

	<footer>
	<p>Copyright © 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
	Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation.
	All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
	</footer>

	</div> <!-- /container -->

	<!-- Javascript
	================================================== -->
	<!-- Placed at the end of the document so the pages load faster -->
	<script src="./resources/js/bootstrap-dropdown.js"></script>

	</body>
	</html>