Merge documentation from 1.4.x branch.

xstream-distribution/src/content/changes.html

@@ -101,11 +101,24 @@ <h2>Stream compatibility</h2>
 		<li>No support for Hibernate 3 collections.</li>
 	</ul>
 
-<!--
 	<h1 id="upcoming-1.4.x">Upcoming 1.4.x maintenance release</h1>
 
 	<p>Not yet released.</p>
--->
+
+	<h2>Stream compatibility</h2>
+
+	<p class="highlight">Starting with version 1.14.12 nine years ago, XStream contains a
+	<a href="security.html#framework">Security Framework</a> to implement a black- or whitelist for the allowed types
+	at deserialization time.  Until version 1.4.17, XStream kept a default blacklist in order to deny all types of the
+	Java runtime, which are used for all kinds of <a href="security.html#CVEs">security attacks</a>, in order to
+	guarantee optimal runtime compatibility for existing users.  However, this approach has failed.  The last months
+	have shown, that the Java runtime alone contains dozens of types that can be used for an attack, not even looking
+	at the 3rd party libraries on a classpath.  The new version of XStream uses therefore now by default a whitelist,
+	which is recommended since nine years.  It also has been complaining on the console for a long time about an
+	uninitialized security framework the first time it was run.  Anyone who has followed the advice and initialized the
+	security framework for their own scenario can easily update to the new version without any problem. Everyone else
+	will have to do a proper initialization now, otherwise the new version will fail with certainty at deserialization
+	time.</p>
 
 	<h1 id="1.4.17">1.4.17</h1>
 

xstream-distribution/src/content/security.html

@@ -19,9 +19,6 @@
 	constructor, call a method to convert an object into XML, then call another method to turn the XML back into an
 	equivalent Java object.  By design, there are few limits to the type of objects XStream can handle.</p>
 
-	<p class=highlight>Note: XStream supports other data formats than XML, e.g. JSON. Those formats can be used for
-	the same attacks.</p>
-
 	<p>This flexibility comes at a price.  XStream applies various techniques under the hood to ensure it is able to
  	handle all types of objects.  This includes using undocumented Java features and reflection.  The XML generated by
  	XStream includes all information required to build objects of almost any type.  This introduces a potential
@@ -32,6 +29,9 @@
 	advantage of this to access private data, delete local files, execute arbitrary code or shell commands in the
 	context of the server running the XStream process or cause a denial of service by crashing the application or
 	manage to enter an endless loop consuming 100% of CPU cycles.</p>
+
+	<p class=highlight>Note: XStream supports other data formats than XML, e.g. JSON. Those formats can be used for
+	the same attacks.</p>
 
 	<p>Note, that the XML data can be manipulated on different levels.  For example, manipulating values on existing
  	objects (such as a price value), accessing private data, or breaking the format and causing the XML parser to fail.
@@ -183,7 +183,7 @@ <h2 id="implicit">Implicit Security</h2>
  	<p>All those scenarios were based on types that are delivered with the Java runtime at some version.  Looking at 
  	other well-known and commonly used Java libraries libraries such as ASM, CGLIB, or Groovy, you will have to assume
  	other scenarios for exploits as well.  A class like InvokerTransformer of Apache Commons Collections has a high
- 	potential for attacks.   By default XStream 1.5 works now with a whitelist.  If you modify the default setup, it
+ 	potential for attacks.   By default XStream 1.4.18 works now with a whitelist.  If you modify the default setup, it
  	is also your responsibility to protect your clients from such vulnerabilities.</p>
 
 	<p>Note: This vulnerability is not even a special problem of XStream.  XML being deserialized by XStream acts here
@@ -196,7 +196,7 @@ <h2 id="implicit">Implicit Security</h2>
 
 	<p class="hightlight">A blacklist for special classes only creates therefore a scenario for a false security,
     because no-one can assure, that no other vulnerability is found.  A better approach is the usage of a whitelist
-    i.e. the allowed class types are setup explicitly. This is the default for XStream 1.5.x (see below).</p>
+    i.e. the allowed class types are setup explicitly. This is the default for XStream 1.4.18 (see below).</p>
 
     <h2 id="explicit">Explicit Security</h2>
 
@@ -205,10 +205,16 @@ <h2 id="explicit">Explicit Security</h2>
 	With these permissions it is at least not possible to inject unexpected types into an object graph.  The security
 	framework supports the setup of a blacklist or whitelist scenario.  Any application should use this feature to
 	limit the danger of arbitrary command execution if it deserializes data from an external source.</p>
-	
+
 	<p>XStream itself sets up a whitelist by default, i.e. it blocks all classes except those types it has explicit
-	converters for.  Nonetheless, it is still the better approach to maintain an own whitelist for an XStream
-	instance.  A blacklist scenario should be avoided in general, because it provides a false sense of security.</p>
+	converters for. Until version 1.4.17 it used a blacklist by default, i.e. it tried to block all currently known
+	critical classes of the Java	runtime.  Main reason for the blacklist were compatibility, it allowed to use newer
+	versions of XStream as drop-in replacement.  However, this approach has failed.  A growing list of security reports
+	has proven, that a blacklist is inherently unsafe, apart from the fact that types of 3rd libraries were not even
+	considered.  XStream provides the ability to setup a whitelist since version 1.4.7, a version released nine years
+	before 1.4.18.  Clients who have adapted their setup and initialize the security framework are able to use newer
+	versions again as drop-in replacement.  A blacklist scenario should be avoided in general, because it provides a
+	false sense of security.</p>
 
 	<p class=highlight>Note:  If a type on a whitelist contains itself other members that are handled by XStream, you
 	will have to add those member's types to the whitelist also.  There is no automatism for indirect references.</p>
@@ -231,8 +237,10 @@ <h1 id="framework">Security Framework</h1>
 	<p>Noted above, it might be possible that other combinations are found with the Java runtime itself, or other
 	commonly-used Java libraries that allow a similar vulnerability like the known case using the Java Beans
 	EventHandler.  To prevent such a possibility at all, XStream version 1.4.7 and above contains a security framework,
-	allowing application developers to define which types are allowed to be unmarshalled with XStream.</p>
-
+	allowing application developers to define which types are allowed to be unmarshalled with XStream.  Use
+	<a href="javadoc/com/thoughtworks/xstream/XStream.html#setupDefaultSecurity-com.thoughtworks.xstream.XStream-">XStream.setupDefaultSecurity()</a>
+	to install the default whitelist of 1.4.18 already with 1.4.7 to 1.4.10.</p>
+
 	<p>The core interface is <a href="javadoc/com/thoughtworks/xstream/security/TypePermission.html">TypePermission</a>.
 	The <a href="javadoc/com/thoughtworks/xstream/mapper/SecurityMapper.html">SecurityMapper</a> will evaluate a list
 	of registered instances for every type that will be required while unmarshalling input data.  The interface has one
@@ -398,8 +406,9 @@ <h2 id="example">Example Code Whitelist</h2>
     <h2 id="workaround">Workarounds for older XStream versions</h2>
 
     <p>As recommended, use XStream's security framework to implement a whitelist for the allowed types. This is
-    possible since XStream 1.4.7 and the default since XStream 1.5.0:</p>
-<div class="Source Java"><pre>XStream xstream = new XStream();
+    possible since XStream 1.4.7 and the default since XStream 1.4.18:</p>
+<div class="Source Java"><pre>XStream xstream= new XStream();
+XStream.setupDefaultSecurity(xstream);
 // add your allowed types, type hierarchies or packages here
 </pre></div>
     <p>Users of XStream 1.4.16 who insist to use XStream default blacklist - despite that clear recommendation - can

xstream/src/java/com/thoughtworks/xstream/XStream.java

@@ -752,14 +752,14 @@ protected void setupSecurity() {
     /**
      * Setup the security framework of a XStream instance.
      * <p>
-     * This method was a pure helper method for XStream 1.4.x. It initializes an XStream instance with a white list of
-     * well-known and simply types of the Java runtime as it is done in XStream 1.5.x by default. This method will do
-     * nothing.
+     * This method was a pure helper method for XStream 1.4.10 to 1.4.17.  It initialized an XStream instance with a
+     * whitelist of well-known and simply types of the Java runtime as it is done in XStream 1.4.18 by default.  This
+     * method will do therefore nothing in XStream 1.4.18 or higher.
      * </p>
      *
      * @param xstream
      * @since 1.4.10
-     * @deprecated As of upcoming, since it is superfluous in XStream 1.5.x
+     * @deprecated As of 1.4.18
      */
     @Deprecated
     public static void setupDefaultSecurity(final XStream xstream) {