Author: lmccay
Date: Wed Nov 1 19:59:07 2017
New Revision: 1813986
URL: http://svn.apache.org/viewvc?rev=1813986&view=rev
Log:
KNOX-1090 - Add Documentation for Strict-Transport-Security header in Knox
responses
Modified:
knox/site/books/knox-0-14-0/dev-guide.html
knox/site/books/knox-0-14-0/user-guide.html
knox/trunk/books/0.14.0/book.md
knox/trunk/books/0.14.0/config_webappsec_provider.md
knox/trunk/books/0.14.0/dev-guide/admin-ui.md
Modified: knox/site/books/knox-0-14-0/dev-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/dev-guide.html?rev=1813986&r1=1813985&r2=1813986&view=diff
==============================================================================
--- knox/site/books/knox-0-14-0/dev-guide.html (original)
+++ knox/site/books/knox-0-14-0/dev-guide.html Wed Nov 1 19:59:07 2017
@@ -1885,6 +1885,7 @@ public interface CustomResources {
<param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param>
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
<param><name>xframe-options.enabled</name><value>true</value></param>
+
<param><name>strict.transport.enabled</name><value>true</value></param>
</provider>
</code></pre><p>and </p>
Modified: knox/site/books/knox-0-14-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/user-guide.html?rev=1813986&r1=1813985&r2=1813986&view=diff
==============================================================================
--- knox/site/books/knox-0-14-0/user-guide.html (original)
+++ knox/site/books/knox-0-14-0/user-guide.html Wed Nov 1 19:59:07 2017
@@ -69,6 +69,7 @@
<li><a href="#CSRF">CSRF</a></li>
<li><a href="#CORS">CORS</a></li>
<li><a href="#X-Frame-Options">X-Frame-Options</a></li>
+ <li><a href="#HTTP+Strict-Tranport-Security+-+HSTS">HTTP
Strict-Tranport-Security - HSTS</a></li>
</ul></li>
<li><a href="#Websocket+Support">Websocket Support</a></li>
<li><a href="#Audit">Audit</a></li>
@@ -2290,7 +2291,7 @@ chmod 400 knox.service.keytab
</ul><h6><a id="Start/stop+Apache+HTTP+Server">Start/stop Apache HTTP
Server</a> <a href="#Start/stop+Apache+HTTP+Server"><img
src="markbook-section-link.png"/></a></h6>
<pre><code>APACHE_HOME/bin/apachectl -k start
APACHE_HOME/bin/apachectl -k stop
-</code></pre><h6><a id="Verify">Verify</a> <a href="#Verify"><img
src="markbook-section-link.png"/></a></h6><p>Use Knox samples.</p><h3><a
id="Web+App+Security+Provider">Web App Security Provider</a> <a
href="#Web+App+Security+Provider"><img
src="markbook-section-link.png"/></a></h3><p>Knox is a Web API (REST) Gateway
for Hadoop. The fact that REST interactions are HTTP based means that they are
vulnerable to a number of web application security vulnerabilities. This
project introduces a web application security provider for plugging in various
protection filters.</p><p>There are two aspects of web application security
that are handled now: Cross Site Request Forgery (CSRF) and Cross Origin
Resource Sharing. Others will be added in future releases.</p><h4><a
id="CSRF">CSRF</a> <a href="#CSRF"><img
src="markbook-section-link.png"/></a></h4><p>Cross site request forgery (CSRF)
attacks attempt to force an authenticated user to execute functionality without
their knowledge. By presentin
g them with a link or image that when clicked invokes a request to another
site with which the user may have already established an active
session.</p><p>CSRF is entirely a browser based attack. Some background
knowledge of how browsers work enables us to provide a filter that will prevent
CSRF attacks. HTTP requests from a web browser performed via form, image,
iframe, etc are unable to set custom HTTP headers. The only way to create a
HTTP request from a browser with a custom HTTP header is to use a technology
such as Javascript XMLHttpRequest or Flash. These technologies can set custom
HTTP headers, but have security policies built in to prevent web sites from
sending requests to each other unless specifically allowed by policy.
</p><p>This means that a website www.bad.com cannot send a request to <a
href="http://bank.example.com";>http://bank.example.com</a> with the custom
header X-XSRF-Header unless they use a technology such as a XMLHttpRequest.
That technology would prevent s
uch a request from being made unless the bank.example.com domain specifically
allowed it. This then results in a REST endpoint that can only be called via
XMLHttpRequest (or similar technology).</p><p>NOTE: by enabling this protection
within the topology, this custom header will be required for <em>all</em>
clients that interact with it - not just browsers.</p><h4><a id="CORS">CORS</a>
<a href="#CORS"><img src="markbook-section-link.png"/></a></h4><p>For security
reasons, browsers restrict cross-origin HTTP requests initiated from within
scripts. For example, XMLHttpRequest follows the same-origin policy. So, a web
application using XMLHttpRequest could only make HTTP requests to its own
domain. To improve web applications, developers asked browser vendors to allow
XMLHttpRequest to make cross-domain requests.</p><p>Cross Origin Resource
Sharing is a way to explicitly alter the same-origin policy for a given
application or API. In order to allow for applications to make cross domain
requests through Apache Knox, we need to configure the CORS filter of the
WebAppSec provider.</p><h4><a id="Configuration">Configuration</a> <a
href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a
id="Overview">Overview</a> <a href="#Overview"><img
src="markbook-section-link.png"/></a></h5><p>As with all providers in the Knox
gateway, the web app security provider is configured through provider params.
Unlike many other providers, the web app security provider may actually host
multiple vulnerability/security filters. Currently, we only have
implementations for CSRF and CORS but others will follow and you may be
interested in creating your own.</p><p>Because of this one-to-many
provider/filter relationship, there is an extra configuration element for this
provider per filter. As you can see in the sample below, the actual filter
configuration is defined entirely within the params of the WebAppSec
provider.</p>
+</code></pre><h6><a id="Verify">Verify</a> <a href="#Verify"><img
src="markbook-section-link.png"/></a></h6><p>Use Knox samples.</p><h3><a
id="Web+App+Security+Provider">Web App Security Provider</a> <a
href="#Web+App+Security+Provider"><img
src="markbook-section-link.png"/></a></h3><p>Knox is a Web API (REST) Gateway
for Hadoop. The fact that REST interactions are HTTP based means that they are
vulnerable to a number of web application security vulnerabilities. This
project introduces a web application security provider for plugging in various
protection filters.</p><p>There are three aspects of web application security
that are handled now: Cross Site Request Forgery (CSRF), Cross Origin Resource
Sharing and HTTP Strict-Transport-Security. Others will be added in future
releases.</p><h4><a id="CSRF">CSRF</a> <a href="#CSRF"><img
src="markbook-section-link.png"/></a></h4><p>Cross site request forgery (CSRF)
attacks attempt to force an authenticated user to execute functionality wit
hout their knowledge. By presenting them with a link or image that when
clicked invokes a request to another site with which the user may have already
established an active session.</p><p>CSRF is entirely a browser based attack.
Some background knowledge of how browsers work enables us to provide a filter
that will prevent CSRF attacks. HTTP requests from a web browser performed via
form, image, iframe, etc are unable to set custom HTTP headers. The only way to
create a HTTP request from a browser with a custom HTTP header is to use a
technology such as Javascript XMLHttpRequest or Flash. These technologies can
set custom HTTP headers, but have security policies built in to prevent web
sites from sending requests to each other unless specifically allowed by
policy. </p><p>This means that a website www.bad.com cannot send a request to
<a href="http://bank.example.com";>http://bank.example.com</a> with the custom
header X-XSRF-Header unless they use a technology such as a XMLHttpReques
t. That technology would prevent such a request from being made unless the
bank.example.com domain specifically allowed it. This then results in a REST
endpoint that can only be called via XMLHttpRequest (or similar
technology).</p><p>NOTE: by enabling this protection within the topology, this
custom header will be required for <em>all</em> clients that interact with it -
not just browsers.</p><h4><a id="CORS">CORS</a> <a href="#CORS"><img
src="markbook-section-link.png"/></a></h4><p>For security reasons, browsers
restrict cross-origin HTTP requests initiated from within scripts. For example,
XMLHttpRequest follows the same-origin policy. So, a web application using
XMLHttpRequest could only make HTTP requests to its own domain. To improve web
applications, developers asked browser vendors to allow XMLHttpRequest to make
cross-domain requests.</p><p>Cross Origin Resource Sharing is a way to
explicitly alter the same-origin policy for a given application or API. In
order to allow for
applications to make cross domain requests through Apache Knox, we need to
configure the CORS filter of the WebAppSec provider.</p><h4><a
id="HTTP+Strict-Tranport-Security+-+HSTS">HTTP Strict-Tranport-Security -
HSTS</a> <a href="#HTTP+Strict-Tranport-Security+-+HSTS"><img
src="markbook-section-link.png"/></a></h4><p>HTTP Strict Transport Security
(HSTS) is a web security policy mechanism which helps to protect websites
against protocol downgrade attacks and cookie hijacking. It allows web servers
to declare that web browsers (or other complying user agents) should only
interact with it using secure HTTPS connections and never via the insecure HTTP
protocol.</p><h4><a id="Configuration">Configuration</a> <a
href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a
id="Overview">Overview</a> <a href="#Overview"><img
src="markbook-section-link.png"/></a></h5><p>As with all providers in the Knox
gateway, the web app security provider is configured through provider pa
rams. Unlike many other providers, the web app security provider may actually
host multiple vulnerability/security filters. Currently, we only have
implementations for CSRF, CORS and HTTP STS but others will follow and you may
be interested in creating your own.</p><p>Because of this one-to-many
provider/filter relationship, there is an extra configuration element for this
provider per filter. As you can see in the sample below, the actual filter
configuration is defined entirely within the params of the WebAppSec
provider.</p>
<pre><code><provider>
<role>webappsec</role>
<name>WebAppSec</name>
@@ -2300,6 +2301,7 @@ APACHE_HOME/bin/apachectl -k stop
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
<param><name>cors.enabled</name><value>true</value></param>
<param><name>xframe-options.enabled</name><value>true</value></param>
+
<param><name>strict.transport.enabled</name><value>true</value></param>
</provider>
</code></pre><h4><a id="Descriptions">Descriptions</a> <a
href="#Descriptions"><img src="markbook-section-link.png"/></a></h4><p>The
following tables describes the configuration options for the web app security
provider:</p><h5><a id="CSRF">CSRF</a> <a href="#CSRF"><img
src="markbook-section-link.png"/></a></h5><h6><a id="Config">Config</a> <a
href="#Config"><img src="markbook-section-link.png"/></a></h6>
<table>
@@ -2411,6 +2413,27 @@ APACHE_HOME/bin/apachectl -k stop
<td>DENY</td>
</tr>
</tbody>
+</table><h5><a id="HTTP+Strict+Transport+Security">HTTP Strict Transport
Security</a> <a href="#HTTP+Strict+Transport+Security"><img
src="markbook-section-link.png"/></a></h5><p>Web applications can be protected
by protocol downgrade attacks and cookie hijacking by adding HTTP Strict
Transport Security response header.</p><h6><a id="Config">Config</a> <a
href="#Config"><img src="markbook-section-link.png"/></a></h6>
+<table>
+ <thead>
+ <tr>
+ <th>Name </th>
+ <th>Description </th>
+ <th>Default</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>strict.transport.enabled </td>
+ <td>This param enables the HTTP Strict-Transport-Security response
header</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>strict.transport </td>
+ <td>This param specifies a particular value for the HTTP
Strict-Transport-Security header. Default value is max-age=31536000. You can
also use <code>max-age=<expire-time></code> or
<code>max-age=<expire-time>; includeSubDomains</code> or
<code>max-age=<expire-time>;preload</code></td>
+ <td>max-age=31536000</td>
+ </tr>
+ </tbody>
</table><h3><a id="HadoopAuth+Authentication+Provider">HadoopAuth
Authentication Provider</a> <a href="#HadoopAuth+Authentication+Provider"><img
src="markbook-section-link.png"/></a></h3><p>The HadoopAuth authentication
provider for Knox integrates the use of the Apache Hadoop module for SPNEGO and
delegation token based authentication. This introduces the same authentication
pattern used across much of the Hadoop ecosystem to Apache Knox and allows
clients to using the strong authentication and SSO capabilities of
Kerberos.</p><h4><a id="Configuration">Configuration</a> <a
href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a
id="Overview">Overview</a> <a href="#Overview"><img
src="markbook-section-link.png"/></a></h5><p>As with all providers in the Knox
gateway, the HadoopAuth provider is configured through provider params. The
configuration parameters are the same parameters used within Apache Hadoop for
the same capabilities. In this section, we provide an
example configuration and description of each of the parameters. We do
encourage the reader to refer to the Hadoop documentation for this as well.
(see <a
href="http://hadoop.apache.org/docs/current/hadoop-auth/Configuration.html";>http://hadoop.apache.org/docs/current/hadoop-auth/Configuration.html</a>)</p><p>One
of the interesting things to note about this configuration is the use of the
config.prefix parameter. In Hadoop there may be multiple components with their
own specific configuration values for these parameters and since they may get
mixed into the same Configuration object - there needs to be a way to identify
the component specific values. The config.prefix parameter is used for this and
is prepended to each of the configuration parameters for this provider. Below,
you see an example configuration where the value for config.prefix happens to
be ‘hadoop.auth.config’. You will also notice that this same value
is prepended to the name of the rest of the configura
tion parameters.</p>
<pre><code><provider>
<role>authentication</role>
Modified: knox/trunk/books/0.14.0/book.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.14.0/book.md?rev=1813986&r1=1813985&r2=1813986&view=diff
==============================================================================
--- knox/trunk/books/0.14.0/book.md (original)
+++ knox/trunk/books/0.14.0/book.md Wed Nov 1 19:59:07 2017
@@ -68,6 +68,7 @@
* #[CSRF]
* #[CORS]
* #[X-Frame-Options]
+ * #[HTTP Strict-Tranport-Security - HSTS]
* #[Websocket Support]
* #[Audit]
* #[Client Details]
Modified: knox/trunk/books/0.14.0/config_webappsec_provider.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.14.0/config_webappsec_provider.md?rev=1813986&r1=1813985&r2=1813986&view=diff
==============================================================================
--- knox/trunk/books/0.14.0/config_webappsec_provider.md (original)
+++ knox/trunk/books/0.14.0/config_webappsec_provider.md Wed Nov 1 19:59:07
2017
@@ -18,7 +18,7 @@
### Web App Security Provider ###
Knox is a Web API (REST) Gateway for Hadoop. The fact that REST interactions
are HTTP based means that they are vulnerable to a number of web application
security vulnerabilities. This project introduces a web application security
provider for plugging in various protection filters.
-There are two aspects of web application security that are handled now: Cross
Site Request Forgery (CSRF) and Cross Origin Resource Sharing. Others will be
added in future releases.
+There are three aspects of web application security that are handled now:
Cross Site Request Forgery (CSRF), Cross Origin Resource Sharing and HTTP
Strict-Transport-Security. Others will be added in future releases.
#### CSRF
Cross site request forgery (CSRF) attacks attempt to force an authenticated
user to
@@ -36,10 +36,13 @@ For security reasons, browsers restrict
Cross Origin Resource Sharing is a way to explicitly alter the same-origin
policy for a given application or API. In order to allow for applications to
make cross domain requests through Apache Knox, we need to configure the CORS
filter of the WebAppSec provider.
+#### HTTP Strict-Tranport-Security - HSTS
+HTTP Strict Transport Security (HSTS) is a web security policy mechanism which
helps to protect websites against protocol downgrade attacks and cookie
hijacking. It allows web servers to declare that web browsers (or other
complying user agents) should only interact with it using secure HTTPS
connections and never via the insecure HTTP protocol.
+
#### Configuration ####
##### Overview #####
-As with all providers in the Knox gateway, the web app security provider is
configured through provider params. Unlike many other providers, the web app
security provider may actually host multiple vulnerability/security filters.
Currently, we only have implementations for CSRF and CORS but others will
follow and you may be interested in creating your own.
+As with all providers in the Knox gateway, the web app security provider is
configured through provider params. Unlike many other providers, the web app
security provider may actually host multiple vulnerability/security filters.
Currently, we only have implementations for CSRF, CORS and HTTP STS but others
will follow and you may be interested in creating your own.
Because of this one-to-many provider/filter relationship, there is an extra
configuration element for this provider per filter. As you can see in the
sample below, the actual filter configuration is defined entirely within the
params of the WebAppSec provider.
@@ -52,6 +55,7 @@ Because of this one-to-many provider/fil
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
<param><name>cors.enabled</name><value>true</value></param>
<param><name>xframe-options.enabled</name><value>true</value></param>
+ <param><name>strict.transport.enabled</name><value>true</value></param>
</provider>
#### Descriptions ####
@@ -104,3 +108,14 @@ Name | Descripti
xframe-options.enabled | This param enables the
X-Frame-Options capabilities|false
xframe-options.value | This param specifies a particular value
for the X-Frame-Options header. Most often the default value of DENY will be
most appropriate. You can also use SAMEORIGIN or ALLOW-FROM uri|DENY
+##### HTTP Strict Transport Security
+
+Web applications can be protected by protocol downgrade attacks and cookie
hijacking by adding HTTP Strict Transport Security response header.
+
+###### Config
+
+Name | Description | Default
+-----------------------------|-------------|---------
+strict.transport.enabled | This param enables the HTTP
Strict-Transport-Security response header|false
+strict.transport | This param specifies a particular value for
the HTTP Strict-Transport-Security header. Default value is max-age=31536000.
You can also use `max-age=<expire-time>` or `max-age=<expire-time>;
includeSubDomains` or `max-age=<expire-time>;preload`|max-age=31536000
+
Modified: knox/trunk/books/0.14.0/dev-guide/admin-ui.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.14.0/dev-guide/admin-ui.md?rev=1813986&r1=1813985&r2=1813986&view=diff
==============================================================================
--- knox/trunk/books/0.14.0/dev-guide/admin-ui.md (original)
+++ knox/trunk/books/0.14.0/dev-guide/admin-ui.md Wed Nov 1 19:59:07 2017
@@ -57,6 +57,7 @@ The topology hosts an instance of the Ad
<param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param>
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
<param><name>xframe-options.enabled</name><value>true</value></param>
+
<param><name>strict.transport.enabled</name><value>true</value></param>
</provider>
```
@@ -67,4 +68,4 @@ The topology hosts an instance of the Ad
<application>
<role>admin-ui</role>
</application>
-```
\ No newline at end of file
+```
