Skip to content

Commit 7b9eacf

Browse files
dsoumisdsoumis
committed
Improve docs
1 parent 5c78c3f commit 7b9eacf

File tree

1 file changed

+93
-35
lines changed

1 file changed

+93
-35
lines changed

‎webapps/docs/config/filter.xml‎

Lines changed: 93 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -870,10 +870,32 @@ FINE: Request "/docs/config/manager.html" with response status "200"
870870

871871
<subsection name="Introduction">
872872

873-
<p>There are a number of HTTP headers that can be added to the response to
874-
improve the security of the connection. This filter provides a mechanism for
875-
adding those headers. Note that security related headers with more complex
876-
requirements, like CORS, are implemented as separate Filters.</p>
873+
<p>The HTTP Header Security Filter adds security-related HTTP response
874+
headers to help protect against common web vulnerabilities. It supports
875+
three independent protections, each of which can be enabled or disabled
876+
individually:</p>
877+
878+
<ul>
879+
<li><strong>HTTP Strict Transport Security (HSTS)</strong> - instructs
880+
browsers to only access the site over HTTPS, preventing protocol
881+
downgrade attacks and cookie hijacking. The
882+
<code>Strict-Transport-Security</code> header is only added to responses
883+
for secure (HTTPS) requests. See
884+
<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a> for further
885+
details.</li>
886+
<li><strong>Click-jacking protection</strong> - sets the
887+
<code>X-Frame-Options</code> header to control whether the page can be
888+
rendered in a frame, iframe, or object, preventing click-jacking
889+
attacks.</li>
890+
<li><strong>Content-Type sniffing protection</strong> - sets the
891+
<code>X-Content-Type-Options</code> header to <code>nosniff</code>,
892+
preventing browsers from MIME-sniffing the response away from the
893+
declared content type.</li>
894+
</ul>
895+
896+
<p>Note that security-related headers with more complex requirements, such
897+
as CORS, are implemented as separate filters.</p>
898+
877899

878900
</subsection>
879901

@@ -885,6 +907,39 @@ FINE: Request "/docs/config/manager.html" with response status "200"
885907

886908
</subsection>
887909

910+
<subsection name="Basic configuration sample">
911+
912+
<p>To enable the filter with a one-year HSTS policy including subdomains,
913+
click-jacking protection allowing same-origin framing, and content-type
914+
sniffing protection:</p>
915+
916+
<source><![CDATA[<filter>
917+
<filter-name>httpHeaderSecurity</filter-name>
918+
<filter-class>
919+
org.apache.catalina.filters.HttpHeaderSecurityFilter
920+
</filter-class>
921+
<async-supported>true</async-supported>
922+
<init-param>
923+
<param-name>hstsMaxAgeSeconds</param-name>
924+
<param-value>31536000</param-value>
925+
</init-param>
926+
<init-param>
927+
<param-name>hstsIncludeSubDomains</param-name>
928+
<param-value>true</param-value>
929+
</init-param>
930+
<init-param>
931+
<param-name>antiClickJackingOption</param-name>
932+
<param-value>SAMEORIGIN</param-value>
933+
</init-param>
934+
</filter>
935+
<filter-mapping>
936+
<filter-name>httpHeaderSecurity</filter-name>
937+
<url-pattern>/*</url-pattern>
938+
</filter-mapping>]]></source>
939+
940+
</subsection>
941+
942+
888943
<subsection name="Initialisation parameters">
889944

890945
<p>The HTTP Header Security Filter supports the following initialization
@@ -893,58 +948,61 @@ FINE: Request "/docs/config/manager.html" with response status "200"
893948
<attributes>
894949

895950
<attribute name="hstsEnabled" required="false">
896-
<p>Will an HTTP Strict Transport Security (HSTS) header
897-
(<code>Strict-Transport-Security</code>) be set on the response for
898-
secure requests. Any HSTS header already present will be replaced. See
899-
<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a> for further
900-
details of HSTS. If not specified, the default value of
901-
<code>true</code> will be used.</p>
951+
<p>Should the <code>Strict-Transport-Security</code> header be set on
952+
the response for secure requests? The header is only added when the
953+
request is secure (HTTPS). Any HSTS header already present will be
954+
replaced. If not specified, the default value of <code>true</code>
955+
will be used.</p>
902956
</attribute>
903957

904958
<attribute name="hstsMaxAgeSeconds" required="false">
905-
<p>The max age value that should be used in the HSTS header. Negative
906-
values will be treated as zero. If not specified, the default value of
907-
<code>0</code> will be used.</p>
959+
<p>The max age value (in seconds) to use in the HSTS header. This
960+
tells the browser how long to remember that the site should only be
961+
accessed over HTTPS. Negative values will be treated as zero. If not
962+
specified, the default value of <code>0</code> will be used.</p>
908963
</attribute>
909964

910965
<attribute name="hstsIncludeSubDomains" required="false">
911-
<p>Should the includeSubDomains parameter be included in the HSTS
912-
header. If not specified, the default value of <code>false</code> will
913-
be used.</p>
966+
<p>Should the <code>includeSubDomains</code> directive be included in
967+
the HSTS header? When enabled, the HSTS policy applies to all
968+
subdomains as well. If not specified, the default value of
969+
<code>false</code> will be used.</p>
914970
</attribute>
915971

916972
<attribute name="hstsPreload" required="false">
917-
<p>Should the preload parameter be included in the HSTS header. If not
918-
specified, the default value of <code>false</code> will be used. See
919-
<a href="https://hstspreload.org/">https://hstspreload.org</a> for
920-
important information about this parameter.</p>
973+
<p>Should the <code>preload</code> directive be included in the HSTS
974+
header? This signals to browser vendors that the domain should be
975+
included in built-in HSTS preload lists. If not specified, the default
976+
value of <code>false</code> will be used. See
977+
<a href="https://hstspreload.org/">https://hstspreload.org</a> for
978+
requirements and important information about this parameter.</p>
921979
</attribute>
922980

923981
<attribute name="antiClickJackingEnabled" required="false">
924-
<p>Should the anti click-jacking header (<code>X-Frame-Options</code>)
925-
be set on the response. Any anti click-jacking header already present
926-
will be replaced. If not specified, the default value of
927-
<code>true</code> will be used.</p>
982+
<p>Should the <code>X-Frame-Options</code> header be set on the
983+
response? Any existing header with the same name will be replaced. If
984+
not specified, the default value of <code>true</code> will be used.</p>
928985
</attribute>
929986

930987
<attribute name="antiClickJackingOption" required="false">
931-
<p>What value should be used for the anticlick-jacking header? Must be
932-
one of <code>DENY</code>, <code>SAMEORIGIN</code>,
933-
<code>ALLOW-FROM </code> (case-insensitive). If not specified, the
934-
default value of <code>DENY</code> will be used.</p>
988+
<p>The value to use for the <code>X-Frame-Options</code> header. Must
989+
be one of <code>DENY</code>, <code>SAMEORIGIN</code>, or
990+
<code>ALLOW-FROM</code> (case-insensitive). If not specified, the
991+
default value of <code>DENY</code> will be used.</p>
935992
</attribute>
936993

937994
<attribute name="antiClickJackingUri" required="false">
938-
<p>If ALLOW-FROM is used for <strong>antiClickJackingOption</strong>,
939-
what URI should be allowed? If not specified, the default value of an
940-
empty string will be used.</p>
995+
<p>When <code>ALLOW-FROM</code> is used for
996+
<strong>antiClickJackingOption</strong>, this specifies the URI that is
997+
permitted to frame the page. Must be a valid URI. If not specified, the
998+
default value of an empty string will be used.</p>
941999
</attribute>
9421000

9431001
<attribute name="blockContentTypeSniffingEnabled" required="false">
944-
<p>Should the header that blocks content type sniffing
945-
(<code>X-Content-Type-Options</code>) be set on every response. If
946-
already present, the header will be replaced. If not specified, the
947-
default value of <code>true</code> will be used.</p>
1002+
<p>Should the <code>X-Content-Type-Options: nosniff</code> header be
1003+
set on every response? Any existing header with the same name will be
1004+
replaced. If not specified, the default value of <code>true</code>
1005+
will be used.</p>
9481006
</attribute>
9491007

9501008
</attributes>

0 commit comments

Comments
 (0)