diff options
Diffstat (limited to 'files/de/web/http/headers/set-cookie/index.html')
| -rw-r--r-- | files/de/web/http/headers/set-cookie/index.html | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/files/de/web/http/headers/set-cookie/index.html b/files/de/web/http/headers/set-cookie/index.html new file mode 100644 index 0000000000..917e705959 --- /dev/null +++ b/files/de/web/http/headers/set-cookie/index.html @@ -0,0 +1,225 @@ +--- +title: Set-Cookie +slug: Web/HTTP/Headers/Set-Cookie +tags: + - Cookies + - HTTP + - NeedsTranslation + - Reference + - Response + - TopicStub + - header + - samesite +translation_of: Web/HTTP/Headers/Set-Cookie +--- +<div>{{HTTPSidebar}}</div> + +<p><span class="seoSummary">The <strong><code>Set-Cookie</code></strong> HTTP response header is used to send a cookie from the server to the user agent, so the user agent can send it back to the server later. To send multiple cookies, multiple <strong><code>Set-Cookie</code></strong></span> headers should be sent in the same response.</p> + +<div class="blockIndicator warning"> +<p>Browsers block frontend JavaScript code from accessing the <code>Set Cookie</code> header, as required by the Fetch spec, which defines <code>Set-Cookie</code> as a <a href="https://fetch.spec.whatwg.org/#forbidden-response-header-name">forbidden response-header name</a> that <a href="https://fetch.spec.whatwg.org/#ref-for-forbidden-response-header-name%E2%91%A0">must be filtered out</a> from any response exposed to frontend code.</p> +</div> + +<p>For more information, see the guide on <a href="/en-US/docs/Web/HTTP/Cookies">Using HTTP cookies</a>.</p> + +<table class="properties"> + <tbody> + <tr> + <th scope="row">Header type</th> + <td>{{Glossary("Response header")}}</td> + </tr> + <tr> + <th scope="row">{{Glossary("Forbidden header name")}}</th> + <td>no</td> + </tr> + <tr> + <th scope="row"><a href="https://fetch.spec.whatwg.org/#forbidden-response-header-name">Forbidden response-header name</a></th> + <td>yes</td> + </tr> + </tbody> +</table> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox notranslate">Set-Cookie: <cookie-name>=<cookie-value> +Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date> +Set-Cookie: <cookie-name>=<cookie-value>; Max-Age=<non-zero-digit> +Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value> +Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value> +Set-Cookie: <cookie-name>=<cookie-value>; Secure +Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly + +Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Strict +Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Lax +Set-Cookie: <cookie-name>=<cookie-value>; SameSite=None; Secure + +// Multiple attributes are also possible, for example: +Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly +</pre> + +<h2 id="Attributes">Attributes</h2> + +<dl> + <dt><code><cookie-name>=<cookie-value></code></dt> + <dd>A cookie begins with a name-value pair: + <ul> + <li>A <code><cookie-name></code> can be any US-ASCII characters, except control characters, spaces, or tabs. It also must not contain a separator character like the following: <code>( ) < > @ , ; : \ " / [ ] ? = { }</code>.</li> + <li>A <code><cookie-value></code> can optionally be wrapped in double quotes and include any US-ASCII characters excluding control characters, {{glossary("Whitespace")}}, double quotes, comma, semicolon, and backslash. <strong>Encoding</strong>: Many implementations perform URL encoding on cookie values, however it is not required per the RFC specification. It does help satisfying the requirements about which characters are allowed for <cookie-value> though.</li> + <li><strong><code>__Secure-</code> prefix</strong>: Cookies names starting with<code> __Secure-</code> (dash is part of the prefix) must be set with the <code>secure</code> flag from a secure page (HTTPS).</li> + <li><strong><code>__Host-</code> prefix</strong>: Cookies with names starting with <code>__Host-</code> must be set with the <code>secure</code> flag, must be from a secure page (HTTPS), must not have a domain specified (and therefore aren't sent to subdomains) and the path must be <code>/</code>.</li> + </ul> + </dd> + <dt><code>Expires=<date></code> {{optional_inline}}</dt> + <dd> + <p>The maximum lifetime of the cookie as an HTTP-date timestamp. See {{HTTPHeader("Date")}} for the required formatting.</p> + + <p>If unspecified, the cookie becomes a <strong>session cookie</strong>. A session finishes when the client shuts down, and session cookies will be removed.</p> + + <div class="blockIndicator warning"> + <p><strong>Warning:</strong> Many web browsers have a <em>session restore</em> feature that will save all tabs and restore them next time the browser is used. Session cookies will also be restored, as if the browser was never closed.</p> + </div> + + <p>When an Expires date is set, the deadline is relative to the <em>client</em> the cookie is being set on, not the server.</p> + </dd> + <dt><code>Max-Age=<number> </code>{{optional_inline}}</dt> + <dd>Number of seconds until the cookie expires. A zero or negative number will expire the cookie immediately. If both <code>Expires</code> and <code>Max-Age</code> are set, <code>Max-Age</code> has precedence.</dd> + <dt><code>Domain=<domain-value></code> {{optional_inline}}</dt> + <dd>Host to which the cookie will be sent. + <ul> + <li>If omitted, defaults to the host of the current document URL, not including subdomains.</li> + <li>Contrary to earlier specifications, leading dots in domain names (<code>.example.com</code>) are ignored.</li> + <li>Multiple host/domain values are <em>not</em> allowed, but if a domain <em>is</em> specified, then subdomains are always included.</li> + </ul> + </dd> + <dt><code>Path=<path-value></code> {{optional_inline}}</dt> + <dd>A path that must exist in the requested URL, or the browser won't send the <code>Cookie</code> header.</dd> + <dd>The forward slash (<code>/</code>) character is interpreted as a directory separator, and subdirectories will be matched as well: for <code>Path=/docs</code>, <code>/docs</code>, <code>/docs/Web/</code>, and <code>/docs/Web/HTTP</code> will all match.</dd> + <dt id="Secure"><code>Secure</code> {{optional_inline}}</dt> + <dd>Cookie is only sent to the server when a request is made with the <code>https:</code> scheme (except on localhost), and therefore is more resistent to <a href="https://wiki.developer.mozilla.org/en-US/docs/Glossary/MitM">man-in-the-middle</a> attacks. + <p class="note"><strong>Note:</strong> Do not assume that <code>Secure</code> prevents all access to sensitive information in cookies (session keys, login details, etc.). Cookies with this attribute can still be read/modified with access to the client's hard disk, or from JavaScript if the <code>HttpOnly</code> cookie attribute is not set.</p> + + <p class="note"><strong>Note:</strong> Insecure sites (<code>http:</code>) can't set cookies with the <code>Secure</code> attribute (since Chrome 52 and Firefox 52). For Firefox, the <code>https:</code> requirements are ignored when the <code>Secure</code> attribute is set by localhost (since Firefox 75).</p> + </dd> + <dt id="HttpOnly"><code>HttpOnly</code> {{optional_inline}}</dt> + <dd>Forbids JavaScript from accessing the cookie, for example, through the {{domxref("Document.cookie")}} property. Note that a cookie that has been created with HttpOnly will still be sent with JavaScript-initiated requests, e.g. when calling {{domxref("XMLHttpRequest.send()")}} or {{domxref("fetch()")}}. This mitigates attacks against cross-site scripting ({{Glossary("XSS")}}).</dd> + <dt id="SameSite"><code>SameSite=<samesite-value></code> {{optional_inline}}</dt> + <dd>Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks ({{Glossary("CSRF")}}).</dd> + <dd> + <div class="note"> + <p>Standards related to the <a href="/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite">SameSite Cookies</a> recently changed such that:</p> + + <ol> + <li>The cookie-sending behaviour if <code>SameSite</code> is not specified is <code>SameSite=Lax</code>. Previously the default was that cookies were sent for all requests.</li> + <li>Cookies with <code>SameSite=None</code> must now<br> + also specify the <code>Secure</code> attribute (i.e. they require a secure context).</li> + </ol> + + <p>The options below covers the new behaviour. See the <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#Browser_compatibility">Browser compatibility</a> table for information about specific browser implementation (rows: "<code>SameSite</code>: Defaults to <code>Lax</code>" and "<code>SameSite</code>: Secure context required").</p> + </div> + Inline options are: + + <ul> + <li><code>Strict</code>: The browser sends the cookie only for same-site requests (that is, requests originating from the same site that set the cookie). If the request originated from a different URL than the current one, no cookies with the <code>SameSite=Strict</code> attribute are sent.</li> + <li><code>Lax</code>: The cookie is not sent on cross-site requests, such as calls to load images or frames, but is sent when a user is navigating to the origin site from an external site (e.g. if following a link).<br> + This is the default behaviour if the <code>SameSite</code> attribute is not specified.</li> + <li><code>None</code>: The browser sends the cookie with both cross-site and same-site requests. The <code>Secure</code> attribute must also be set when <code>SameSite=None</code>!</li> + </ul> + </dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<h3 id="Session_cookie">Session cookie</h3> + +<p><strong>Session cookies</strong> are removed when the client shuts down. Cookies are session cookies if they don't specify the <code>Expires</code> or <code>Max-Age</code> attributes.</p> + +<pre class="notranslate">Set-Cookie: sessionId=38afes7a8</pre> + +<h3 id="Permanent_cookie">Permanent cookie</h3> + +<p>Instead of expiring when the client is closed, <strong>permanent cookies</strong> expire at a specific date (<code>Expires</code>) or after a specific length of time (<code>Max-Age</code>).</p> + +<pre class="notranslate">Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT +</pre> + +<pre class="notranslate">Set-Cookie: id=a3fWa; Max-Age=2592000</pre> + +<h3 id="Invalid_domains">Invalid domains</h3> + +<p>A cookie for a domain that does not include the server that set it <a href="https://tools.ietf.org/html/rfc6265#section-4.1.2.3">should be rejected by the user agent</a>.</p> + +<p>The following cookie will be rejected if set by a server hosted on <code>originalcompany.com</code>:</p> + +<pre class="notranslate">Set-Cookie: qwerty=219ffwef9w0f; Domain=somecompany.co.uk</pre> + +<p>A cookie for a sub domain of the serving domain will be rejected.</p> + +<p>The following cookie will be rejected if set by a server hosted on <code>example.com</code>:</p> + +<pre class="notranslate">Set-Cookie: sessionId=e8bb43229de9; Domain=foo.example.com</pre> + +<h3 id="Cookie_prefixes">Cookie prefixes</h3> + +<p>Cookies names prefixed with <code>__Secure-</code> or <code>__Host-</code> can be used only if they are set with the <code>secure</code> attribute from a secure (HTTPS) origin.</p> + +<p>In addition, cookies with the <code>__Host-</code> prefix must have a path of <code>/</code> (meaning any path at the host) and must not have a <code>Domain</code> attribute.</p> + +<div class="blockIndicator warning"> +<p>For clients that don't implement cookie prefixes, you cannot count on these additional assurances, and prefixed cookies will always be accepted.</p> +</div> + +<pre class="notranslate">// Both accepted when from a secure origin (HTTPS) +Set-Cookie: __Secure-ID=123; Secure; Domain=example.com +Set-Cookie: __Host-ID=123; Secure; Path=/ + +// Rejected due to missing Secure attribute +Set-Cookie: __Secure-id=1 + +// Rejected due to the missing Path=/ attribute +Set-Cookie: __Host-id=1; Secure + +// Rejected due to setting a Domain +Set-Cookie: __Host-id=1; Secure; Path=/; Domain=example.com +</pre> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Title</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{RFC("6265", "Set-Cookie", "4.1")}}</td> + <td>HTTP State Management Mechanism</td> + </tr> + <tr> + <td><a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-05">draft-ietf-httpbis-rfc6265bis-05</a></td> + <td>Cookie Prefixes, Same-Site Cookies, and Strict Secure Cookies</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("http.headers.Set-Cookie", 5)}}</p> + +<h2 id="Compatibility_notes">Compatibility notes</h2> + +<ul> + <li>Starting with Chrome 52 and Firefox 52, insecure sites (<code>http:</code>) can't set cookies with the <code>Secure</code> attribute anymore.</li> +</ul> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/HTTP/Cookies">HTTP cookies</a></li> + <li>{{HTTPHeader("Cookie")}}</li> + <li>{{domxref("Document.cookie")}}</li> + <li><a href="/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite">SameSite cookies</a></li> +</ul> |