webapps/docs/config/cookie-processor.xml - tomcat - 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>jakarta.servlet.http.Cookie</code>
   objects accessible through <code>HttpServletRequest.getCookies()</code> and
   converts <code>jakarta.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>

 </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.Rfc6265CookieProcessor</code>.</p>

     <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>The <strong>RFC 6265 Cookie Processor</strong> supports the following
     additional attributes.</p>

     <attributes>

       <attribute name="cookiesWithoutEquals" required="false">
         <p>Determines how a cookie received from a user agent should be
         interpreted when the name value pair does not contain an equals sign.
         The default value is <code>ignore</code> which means the cookie will be
         ignored. The other option is <code>name</code> which means that the
         cookie will be treated as a cookie with a name but no value. In Tomcat
         11 and earlier the default was <code>name</code>.</p>
       </attribute>

       <attribute name="partitioned" required="false">
        <p>Should the Partitioned flag be set on cookies? Defaults to <code>false</code>.</p>
        <p>Note: The name of the attribute used to indicate a partitioned cookie as part of
        <a href="https://developers.google.com/privacy-sandbox/3pcd#partitioned">CHIPS</a> is not defined by an RFC and
        may change in a non-backwards compatible way once equivalent functionality is included in an RFC.</p>
       </attribute>

       <attribute name="sameSiteCookies" required="false">
         <p>Enables setting same-site cookie attribute.</p>

         <p>If value is <code>unset</code> then the same-site cookie attribute
         won't be set. This is the default value.</p>

         <p>If value is <code>none</code> then the same-site cookie attribute
         will be set and the cookie will always be sent in cross-site requests.</p>

         <p>If value is <code>lax</code> then the browser only sends the cookie
         in same-site requests and cross-site top level GET requests.</p>

         <p>If value is <code>strict</code> then the browser prevents sending the
         cookie in any cross-site request.</p>
       </attribute>

     </attributes>

   </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>jakarta.servlet.http.Cookie</code>
	objects accessible through <code>HttpServletRequest.getCookies()</code> and
	converts <code>jakarta.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>

	</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.Rfc6265CookieProcessor</code>.</p>

	<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>The <strong>RFC 6265 Cookie Processor</strong> supports the following
	additional attributes.</p>

	<attributes>

	<attribute name="cookiesWithoutEquals" required="false">
	<p>Determines how a cookie received from a user agent should be
	interpreted when the name value pair does not contain an equals sign.
	The default value is <code>ignore</code> which means the cookie will be
	ignored. The other option is <code>name</code> which means that the
	cookie will be treated as a cookie with a name but no value. In Tomcat
	11 and earlier the default was <code>name</code>.</p>
	</attribute>

	<attribute name="partitioned" required="false">
	<p>Should the Partitioned flag be set on cookies? Defaults to <code>false</code>.</p>
	<p>Note: The name of the attribute used to indicate a partitioned cookie as part of
	<a href="https://developers.google.com/privacy-sandbox/3pcd#partitioned">CHIPS</a> is not defined by an RFC and
	may change in a non-backwards compatible way once equivalent functionality is included in an RFC.</p>
	</attribute>

	<attribute name="sameSiteCookies" required="false">
	<p>Enables setting same-site cookie attribute.</p>

	<p>If value is <code>unset</code> then the same-site cookie attribute
	won't be set. This is the default value.</p>

	<p>If value is <code>none</code> then the same-site cookie attribute
	will be set and the cookie will always be sent in cross-site requests.</p>

	<p>If value is <code>lax</code> then the browser only sends the cookie
	in same-site requests and cross-site top level GET requests.</p>

	<p>If value is <code>strict</code> then the browser prevents sending the
	cookie in any cross-site request.</p>
	</attribute>

	</attributes>

	</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>