webapps/docs/config/cookie-processor.xml - tomcat80 - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   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.
 -->
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="cookie-processor.html">

   &project;

   <properties>
     <title>The Cookie Processor Component</title>
   </properties>

 <body>

 <section name="Table of Contents">
 <toc />
 </section>

 <section name="Introduction">

   <p>The <strong>CookieProcessor</strong> element represents the component that
   parses received cookie headers into <code>javax.servlet.http.Cookie</code>
   objects accessible through <code>HttpServletRequest.getCookies()</code> and
   converts <code>javax.servlet.http.Cookie</code> objects added to the response
   through <code>HttpServletResponse.addCookie()</code> to the HTTP headers
   returned to the client.</p>

   <p>A CookieProcessor element MAY be nested inside a
   <a href="context.html">Context</a> component. If it is not included, a default
   implementation will be created automatically.</p>

   <p><strong>Note:</strong> <strong>CookieProcessor</strong> is a new
   configuration element, introduced in Tomcat 8.0.15.</p>
   <ul>
     <li>The <strong>CookieProcessor</strong> element allows different cookie
     parsing configuration in each web application, or globally in the default
     <code>conf/context.xml</code> file. The legacy cookie parsing algorithm
     supported only limited global configuration via several
     <a href="systemprops.html#Specifications">system properties</a>. Those
     system properties are still supported, but are going to be deprecated in
     favor of this new configuration element.
     </li>
     <li>The new RFC6265-compliant implementation is a drop-in replacement for
     the original legacy one. The legacy implementation remains the default. You
     can select the implementation by setting <code>className</code> attribute
     on <strong>CookieProcessor</strong> element.</li>
   </ul>

 </section>


 <section name="Attributes">

   <subsection name="Common Attributes">

     <p>All implementations of <strong>CookieProcessor</strong> support the
     following attributes:</p>

     <attributes>

       <attribute name="className" required="false">
         <p>Java class name of the implementation to use. This class must
         implement the <code>org.apache.tomcat.util.http.CookieProcessor</code>
         interface. If not specified, the standard value (defined below) will be
         used.</p>
       </attribute>

     </attributes>

   </subsection>


   <subsection name="Standard Implementation">

     <p>The standard implementation of <strong>CookieProcessor</strong> is
     <code>org.apache.tomcat.util.http.LegacyCookieProcessor</code>. Note
     that it is anticipated that this will change to
     <code>org.apache.tomcat.util.http.Rfc6265CookieProcessor</code> in a future
     Tomcat 8 release.</p>

     <p>This is the legacy  cookie parser based on RFC6265, RFC2109 and RFC2616.
     It implements a strict interpretation of the cookie specifications. Due to
     various interoperability issues with browsers not all strict behaviours
     are enabled by default and additional options are available to further
     relax the behaviour of this cookie processor if required.</p>

     <attributes>

       <attribute name="allowEqualsInValue" required="false">
         <p>If this is <code>true</code> Tomcat will allow '<code>=</code>'
         characters when parsing unquoted cookie values. If <code>false</code>,
         cookie values containing '<code>=</code>' will be terminated when the
         '<code>=</code>' is encountered and the remainder of the cookie value
         will be dropped.</p>
         <p>If not set the specification compliant default value of
         <code>false</code> will be used. This default may be changed by setting
         the
         <code>org.apache.tomcat.util.http.ServerCookie.ALLOW_EQUALS_IN_VALUE</code>
         <a href="systemprops.html">system property</a>.</p>
       </attribute>

       <attribute name="allowHttpSepsInV0" required="false">
         <p>If this is <code>true</code> Tomcat will allow HTTP separators in
         cookie names and values.</p>
         <p>If not specified, the default specification compliant value of
         <code>false</code> will be used. This default may be changed by setting
         the
         <code>org.apache.tomcat.util.http.ServerCookie.ALLOW_HTTP_SEPARATORS_IN_V0</code>
         <a href="systemprops.html">system property</a>.</p>
       </attribute>

       <attribute name="allowNameOnly" required="false">
         <p>If this is <code>true</code> Tomcat will allow name only cookies
         (with or without trailing '<code>=</code>') when parsing cookie headers.
         If <code>false</code>, name only cookies will be dropped.</p>
         <p>If not set the specification compliant default value of
         <code>false</code> will be used. This default may be changed by setting
         the
         <code>org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY</code>
         <a href="systemprops.html">system property</a>.</p>
       </attribute>

       <attribute name="alwaysAddExpires" required="false">
         <p>If this is <code>true</code> Tomcat will always add an expires
         parameter to a SetCookie header even for cookies with version greater
         than zero. This is to work around a known IE6 and IE7 bug that causes I
         to ignore the Max-Age parameter in a SetCookie header.</p>
         <p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set
         to <code>true</code>, the default of this setting will be
         <code>false</code>, else the default value will be <code>true</code>.
         </p>
       </attribute>

       <attribute name="forwardSlashIsSeparator" required="false">
         <p>If this is <code>true</code> Tomcat will treat the forward slash
         character ('<code>/</code>') as an HTTP separator when processing cookie
         headers. If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
         is set to <code>true</code>, the default of this setting will be
         <code>true</code>, else the default value will be <code>false</code>.
         This default may be overridden by setting the
         <code>org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR</code>
         system property.</p>
       </attribute>

       <attribute name="preserveCookieHeader" required="false">
         <p>This attribute is no longer used. From Tomcat 8.0.31, Tomcat will
         always preserve the cookie header returned by
         <code>HttpServletRequest.getHeader()</code>.</p>
       </attribute>

     </attributes>

   </subsection>

   <subsection name="RFC 6265 Cookie Processor - org.apache.tomcat.util.http.Rfc6265CookieProcessor">

     <p>This cookie processor is based on RFC6265 with the following changes to
     support better interoperability:</p>

     <ul>
       <li>Values 0x80 to 0xFF are permitted in cookie-octet to support the use
       of UTF-8 in cookie values as used by HTML 5.</li>
       <li>For cookies without a value, the '=' is not required after the name as
       some browsers do not sent it.</li>
     </ul>

     <p>The RFC 6265 cookie processor is generally more lenient than the legacy
     cookie parser. In particular:</p>

     <ul>
       <li>The '<code>=</code>' and '<code>/</code>' characters are always
       permitted in a cookie value.</li>
       <li>Name only cookies are always permitted.</li>
       <li>The cookie header is always preserved.</li>
     </ul>

     <p>No additional attributes are supported by the <strong>RFC 6265 Cookie
     Processor</strong>.</p>

   </subsection>

 </section>


 <section name="Nested Components">

   <p>No element may be nested inside a <strong>CookieProcessor</strong>.</p>

 </section>


 <section name="Special Features">

   <p>No special features are associated with a <strong>CookieProcessor</strong>
   element.</p>

 </section>

 </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	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.
	-->
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="cookie-processor.html">

	&project;

	<properties>
	<title>The Cookie Processor Component</title>
	</properties>

	<body>

	<section name="Table of Contents">
	<toc />
	</section>

	<section name="Introduction">

	<p>The <strong>CookieProcessor</strong> element represents the component that
	parses received cookie headers into <code>javax.servlet.http.Cookie</code>
	objects accessible through <code>HttpServletRequest.getCookies()</code> and
	converts <code>javax.servlet.http.Cookie</code> objects added to the response
	through <code>HttpServletResponse.addCookie()</code> to the HTTP headers
	returned to the client.</p>

	<p>A CookieProcessor element MAY be nested inside a
	<a href="context.html">Context</a> component. If it is not included, a default
	implementation will be created automatically.</p>

	<p><strong>Note:</strong> <strong>CookieProcessor</strong> is a new
	configuration element, introduced in Tomcat 8.0.15.</p>
	<ul>
	<li>The <strong>CookieProcessor</strong> element allows different cookie
	parsing configuration in each web application, or globally in the default
	<code>conf/context.xml</code> file. The legacy cookie parsing algorithm
	supported only limited global configuration via several
	<a href="systemprops.html#Specifications">system properties</a>. Those
	system properties are still supported, but are going to be deprecated in
	favor of this new configuration element.
	</li>
	<li>The new RFC6265-compliant implementation is a drop-in replacement for
	the original legacy one. The legacy implementation remains the default. You
	can select the implementation by setting <code>className</code> attribute
	on <strong>CookieProcessor</strong> element.</li>
	</ul>

	</section>


	<section name="Attributes">

	<subsection name="Common Attributes">

	<p>All implementations of <strong>CookieProcessor</strong> support the
	following attributes:</p>

	<attributes>

	<attribute name="className" required="false">
	<p>Java class name of the implementation to use. This class must
	implement the <code>org.apache.tomcat.util.http.CookieProcessor</code>
	interface. If not specified, the standard value (defined below) will be
	used.</p>
	</attribute>

	</attributes>

	</subsection>


	<subsection name="Standard Implementation">

	<p>The standard implementation of <strong>CookieProcessor</strong> is
	<code>org.apache.tomcat.util.http.LegacyCookieProcessor</code>. Note
	that it is anticipated that this will change to
	<code>org.apache.tomcat.util.http.Rfc6265CookieProcessor</code> in a future
	Tomcat 8 release.</p>

	<p>This is the legacy cookie parser based on RFC6265, RFC2109 and RFC2616.
	It implements a strict interpretation of the cookie specifications. Due to
	various interoperability issues with browsers not all strict behaviours
	are enabled by default and additional options are available to further
	relax the behaviour of this cookie processor if required.</p>

	<attributes>

	<attribute name="allowEqualsInValue" required="false">
	<p>If this is <code>true</code> Tomcat will allow '<code>=</code>'
	characters when parsing unquoted cookie values. If <code>false</code>,
	cookie values containing '<code>=</code>' will be terminated when the
	'<code>=</code>' is encountered and the remainder of the cookie value
	will be dropped.</p>
	<p>If not set the specification compliant default value of
	<code>false</code> will be used. This default may be changed by setting
	the
	<code>org.apache.tomcat.util.http.ServerCookie.ALLOW_EQUALS_IN_VALUE</code>
	<a href="systemprops.html">system property</a>.</p>
	</attribute>

	<attribute name="allowHttpSepsInV0" required="false">
	<p>If this is <code>true</code> Tomcat will allow HTTP separators in
	cookie names and values.</p>
	<p>If not specified, the default specification compliant value of
	<code>false</code> will be used. This default may be changed by setting
	the
	<code>org.apache.tomcat.util.http.ServerCookie.ALLOW_HTTP_SEPARATORS_IN_V0</code>
	<a href="systemprops.html">system property</a>.</p>
	</attribute>

	<attribute name="allowNameOnly" required="false">
	<p>If this is <code>true</code> Tomcat will allow name only cookies
	(with or without trailing '<code>=</code>') when parsing cookie headers.
	If <code>false</code>, name only cookies will be dropped.</p>
	<p>If not set the specification compliant default value of
	<code>false</code> will be used. This default may be changed by setting
	the
	<code>org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY</code>
	<a href="systemprops.html">system property</a>.</p>
	</attribute>

	<attribute name="alwaysAddExpires" required="false">
	<p>If this is <code>true</code> Tomcat will always add an expires
	parameter to a SetCookie header even for cookies with version greater
	than zero. This is to work around a known IE6 and IE7 bug that causes I
	to ignore the Max-Age parameter in a SetCookie header.</p>
	<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set
	to <code>true</code>, the default of this setting will be
	<code>false</code>, else the default value will be <code>true</code>.
	</p>
	</attribute>

	<attribute name="forwardSlashIsSeparator" required="false">
	<p>If this is <code>true</code> Tomcat will treat the forward slash
	character ('<code>/</code>') as an HTTP separator when processing cookie
	headers. If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
	is set to <code>true</code>, the default of this setting will be
	<code>true</code>, else the default value will be <code>false</code>.
	This default may be overridden by setting the
	<code>org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR</code>
	system property.</p>
	</attribute>

	<attribute name="preserveCookieHeader" required="false">
	<p>This attribute is no longer used. From Tomcat 8.0.31, Tomcat will
	always preserve the cookie header returned by
	<code>HttpServletRequest.getHeader()</code>.</p>
	</attribute>

	</attributes>

	</subsection>

	<subsection name="RFC 6265 Cookie Processor - org.apache.tomcat.util.http.Rfc6265CookieProcessor">

	<p>This cookie processor is based on RFC6265 with the following changes to
	support better interoperability:</p>

	<ul>
	<li>Values 0x80 to 0xFF are permitted in cookie-octet to support the use
	of UTF-8 in cookie values as used by HTML 5.</li>
	<li>For cookies without a value, the '=' is not required after the name as
	some browsers do not sent it.</li>
	</ul>

	<p>The RFC 6265 cookie processor is generally more lenient than the legacy
	cookie parser. In particular:</p>

	<ul>
	<li>The '<code>=</code>' and '<code>/</code>' characters are always
	permitted in a cookie value.</li>
	<li>Name only cookies are always permitted.</li>
	<li>The cookie header is always preserved.</li>
	</ul>

	<p>No additional attributes are supported by the <strong>RFC 6265 Cookie
	Processor</strong>.</p>

	</subsection>

	</section>


	<section name="Nested Components">

	<p>No element may be nested inside a <strong>CookieProcessor</strong>.</p>

	</section>


	<section name="Special Features">

	<p>No special features are associated with a <strong>CookieProcessor</strong>
	element.</p>

	</section>

	</body>

	</document>