This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new d89b38a Javadocs
d89b38a is described below
commit d89b38adcfe525987196640d2810f6ab2a5208de
Author: JamesBognar <jamesbog...@apache.org>
AuthorDate: Mon Jan 6 09:24:39 2020 -0500
Javadocs
---
juneau-doc/docs/Topics/20.Security.html | 24 ++++++
.../Topics/20.Security/01.juneau-marshall.html | 89 ++++++++++++++++++++++
.../docs/Topics/20.Security/02.juneau-svl.html | 61 +++++++++++++++
.../Topics/20.Security/03.juneau-rest-server.html | 28 +++++++
4 files changed, 202 insertions(+)
diff --git a/juneau-doc/docs/Topics/20.Security.html
b/juneau-doc/docs/Topics/20.Security.html
new file mode 100644
index 0000000..214f1da
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security.html
@@ -0,0 +1,24 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+Security Best-Practices
+
+<p>
+ Security is always an ongoing concern in any library.
+ If you discover any security vulnerabilities in this code, please refer
to the instructions found here:
+</p>
+<ul class='spaced-list'>
+ <li class='extlink'>{@doc http://www.apache.org/security SECURITY}
+</ul>
diff --git a/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html
b/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html
new file mode 100644
index 0000000..6644cda
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html
@@ -0,0 +1,89 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+juneau-marshall
+
+<h5 class='topic'>Demarshalling vulnerabilities</h5>
+<p>
+ One common security vulnerability is the ability to create arbitrary
Java object instances through crafted
+ user input. For example, support for constructing POJOs based on an
input attribute defining a
+ fully-qualified class name like <js>"{class:'com.foo.MyBean',...}"</js>
+</p>
+<p>
+ Fortunately, Juneau does not support an open-ended <js>"class</js>
attribute.
+ As a rule, it should not be possible to create arbitrary POJOs by any
of the parsers.
+ The demarshalled object types are inferred via reflection of the class
objects passed in through the parser
+ method (e.g. <c>JsonParser.<jsf>DEFAULT</jsf>.parse(input,
MyBean.<jk>class</jk>)</c>).
+ As long as the <c>Class</c> object passed into this method is not
constructed from user-generated input,
+ it should be free from demarshalling vulnerabilities.
+</p>
+<p>
+ The following example shows a potential vector that circumvents the
restriction above:
+</p>
+<p class='bpcode w800'>
+ <jc>// Don't do this!</jc>
+ Class c = Class.<jsf>forName</jsf>(someUserInputString);
+ JsonParser.<jsf>DEFAULT</jsf>.parse(input, c); <jc>// Oops! Security
hole!</jc>
+</p>
+<p>
+ Juneau does support something similar to a <js>"class"</js> attribute
that allows you to define the
+ POJO type at runtime.
+ This is the <js>"type"</js> attribute.
+ The difference is that it's not possible to specify fully-qualified
class names in <js>"type"</js> attributes,
+ and instead can only specify type keys defined through bean
dictionaries.
+ Instead of serializing the fully-qualified class names in the output,
we instead serialize type
+ names that represent those POJO types.
+ i.e. instead of <js>"class='com.foo.MyBean'"</js>, we instead serialize
<js>"type='MyBeanIdentifier'"</js>.
+ Since bean types are defined at compile time, it's impossible to
instantiate arbitrary POJOs.
+</p>
+<p>
+ POJO types of generalized input are also inferred through swaps.
+ Again, since the POJO types are hardcoded at compile time, these should
not be subject to demarshalling
+ vulnerabilities. However, it is possible to circumvent this through
your swap implementation as shown
+ below:
+</p>
+<p class='bpcode w800'>
+ <jc>// Don't do this!</jc>
+ <jk>public class</jk> MyInsecureSwap <jk>extends</jk>
PojoSwap<ObjectMap,Object> {
+ <jk>public</jk> Object swap(BeanSession session, ObjectMap
input) <jk>throws</jk> Exception {
+ <jc>// Security hole!</jc>
+ <jk>return</jk>
Class.<jsf>forName</jsf>(input.getString(<js>"class"</js>)).newInstance();
+ }
+ }
+</p>
+<p>
+ Note that the {@link oaj.jso.JsoParser}, a thin layer of the Juneau
Parser API written on
+ top of plain-old Java Object Serialization which itself is vulnerable
to demarshalling issues.
+ Due to this, the JSO parser is not included in any of the default REST
servlet implementations.
+ Be especially careful when using this parser, particularly if you want
to use it for handing
+ <c>application/x-java-serialized-object</c> input through REST
servlets.
+</p>
+<p>
+ All other parsers (JSON, URL-Encoding, MessagePack, etc...) work the
same way in determining POJO types, so
+ should be safe from demarshalling vulnerabilities.
+</p>
+
+<h5 class='topic'>Dependent libraries</h5>
+<p>
+ When accessing security vulnerabilities of any library, dependent
libraries must also be taken into account:
+</p>
+<ul>
+ <li>The JSON, HTML, MsgPack, URL-Encoding, and UON parsers are written
from scratch and do not rely on
+ any other parsing technologies.
+ <li>The XML and HTML parsers uses the built-in Java StAX parser.
+ This *should* be free from vulnerabilities.
+ <li>The RDF parsers rely on Apache Jena 2.7.1.
+ As of <c>7.0.1</c>, no known security vulnerabilities exist
that affect Juneau at this time.
+</ul>
diff --git a/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html
b/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html
new file mode 100644
index 0000000..4a833f3
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html
@@ -0,0 +1,61 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+juneau-svl
+
+<p>
+ Care must be used when defining new {@link oaj.svl.Var Vars} using the
SVL API since mistakes
+ could potentially expose system properties, environment variables, or
even file system files.
+</p>
+<p>
+ For recap, the SVL support allows you to embed variables of the form
<js>"$X{key}"</js> inside strings that
+ get resolved to other strings. The resolved strings themselves can
also contain variables that also
+ get recursively resolved.
+</p>
+<p>
+ An example of a potential security hole is shown below that could
potentially expose any file on a file
+ system through a REST request:
+</p>
+<p class='bpcode w800'>
+ <jk>public</jk> String doUnsafeGet(RestRequest req) {
+ <jc>// Security hole!</jc>
+ <jk>return</jk>
req.getVarResolver().resolve(<js>"$RQ{foo}"</js>);
+ }
+</p>
+<p>
+ This code is simply echoing the value of the <c>foo</c> query parameter.
+ Now say for example that a bad actor passes in the query string
<js>"foo=$F{/some/file/on/file/system}"</js>.
+ The <c>$F</c> variable allows you to resolve the contents of files
using SVL, and is provided
+ by default using the built-in variable resolver returned by the
<c>RestRequest</c> object.
+ You've potentially just exposed the contents of that file through your
REST interface.
+</p>
+<p>
+ In reality, the above security hole does not exist because of the
following restrictions:
+</p>
+<ul class='spaced-list'>
+ <li>
+ <c>Vars</c> have two methods {@link oaj.svl.Var#allowNested()}
and
+ {@link oaj.svl.Var#allowRecurse()} that can be overridden to
prevent recursive processing
+ of string variables. These are both <jk>false</jk> for the
<c>$R</c> variable, so the <c>$F</c>
+ variable in the result will never get processed and instead be
treated as plain text.
+ <li>
+ The <c>$F</c> variable only allows you to retrieve files within
the JVM starting directory.
+</ul>
+<p>
+ Even though the built-in Juneau variables are safe, special care is
needed when defining your own custom
+ variables. If your variable resolves user input in any way, it's
HIGHLY recommended that you override the
+ {@link oaj.svl.Var#allowNested()} and {@link
oaj.svl.Var#allowRecurse()}
+ methods to prevent recursive handling of variables.
+</p>
diff --git a/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html
b/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html
new file mode 100644
index 0000000..2d15a79
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html
@@ -0,0 +1,28 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+juneau-rest-server
+
+<p>
+ Denial of service attacks can be alleviated through the {@link
oajr.annotation.Rest#maxInput() maxInput()}
+ setting. Arbitrarily-large input will trigger an exception before
causing out-of-memory errors.
+ The default value for this setting is 100MB.
+</p>
+<p>
+ Since the parsers do not use intermediate DOMs and instead parse
directly into Java objects,
+ deeply nested data structures will almost always trigger stack overflow
errors long before memory consumption
+ becomes an issue. However, this is NOT true of the RDF parsers that
use an intermediate DOM. If parsing
+ RDF, you may want to consider lowering the max-input value above.
+</p>
