MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Set-Cookie

响应首部 Set-Cookie 被用来由服务器端向客户端发送 cookie。

更多信息请查阅这篇指南: HTTP cookies.

Header type Response header
Forbidden header name no

语法

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

// Multiple directives are also possible, for example:
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly

指令

<cookie-name>=<cookie-value>
一个 cookie 开始于一个名称/值对:
  • <cookie-name> 可以是除了控制字符 (CTLs)、空格 (spaces) 或制表符 (tab)之外的任何 US-ASCII 字符。同时不能包含以下分隔字符: ( ) < > @ , ; : \ " /  [ ] ? = { }.
  • <cookie-value> 是可选的,如果存在的话,那么需要包含在双引号里面。支持除了控制字符(CTLs)、空格(whitespace)、双引号(double quotes)、逗号(comma)、分号(semicolon)以及反斜线(backslash)之外的任意 US-ASCII 字符。关于编码:许多应用会对 cookie 值按照URL编码(URL encoding)规则进行编码,但是按照 RFC 规范,这不是必须的。不过满足规范中对于 <cookie-value> 所允许使用的字符的要求是有用的。
  • __Secure- 前缀:以 __Secure- 为前缀的 cookie(其中连接符是前缀的一部分),必须与 secure 属性一同设置,同时必须应用于安全页面(即使用 HTTPS 访问的页面)。
  • __Host- 前缀: 以 __Host- 为前缀的 cookie,必须与 secure 属性一同设置,必须应用于安全页面(即使用 HTTPS 访问的页面),必须不能设置 domain 属性 (也就不会发送给子域),同时 path 属性的值必须为“/”。
Expires=<date> 可选

cookie 的最长有效时间,形式为符合 HTTP-date 规范的时间戳。参考 Date 可以获取详细信息。如果没有设置这个属性,那么表示这是一个会话期 cookie 。一个会话结束于客户端被关闭时,这意味着会话期 cookie 在彼时会被移除。然而,很多Web浏览器支持会话恢复功能,这个功能可以使浏览器保留所有的tab标签,然后在重新打开浏览器的时候将其还原。与此同时,cookie 也会恢复,就跟从来没有关闭浏览器一样。

Max-Age=<non-zero-digit> 可选
在 cookie 失效之前需要经过的秒数。一位或多位非零(1-9)数字。一些老的浏览器(ie6、ie7 和 ie8)不支持这个属性。对于其他浏览器来说,假如二者 (指 ExpiresMax-Age) 均存在,那么 Max-Age 优先级更高。
Domain=<domain-value> 可选
指定 cookie 可以送达的主机名。假如没有指定,那么默认值为当前文档访问地址中的主机部分(但是不包含子域名)。与之前的规范不同的是,域名之前的点号会被忽略。假如指定了域名,那么相当于各个子域名也包含在内了。
Path=<path-value> 可选
指定一个 URL 路径,这个路径必须出现在要请求的资源的路径中才可以发送 Cookie 首部。字符  %x2F ("/") 可以解释为文件目录分隔符,此目录的下级目录也满足匹配的条件(例如,如果 path=/docs,那么 "/docs", "/docs/Web/" 或者 "/docs/Web/HTTP" 都满足匹配的条件)。
Secure 可选
一个带有安全属性的 cookie 只有在请求使用SSL和HTTPS协议的时候才会被发送到服务器。然而,保密或敏感信息永远不要在 HTTP cookie 中存储或传输,因为整个机制从本质上来说都是不安全的,比如前述协议并不意味着所有的信息都是经过加密的。

注意:非安全站点(http:)已经不能再在 cookie 中设置 secure 指令了(在Chrome 52+ and Firefox 52+ 中新引入的限制)。

HttpOnly 可选
设置了 HttpOnly 属性的 cookie 不能使用 JavaScript 经由  Document.cookie 属性、XMLHttpRequest 和  Request APIs 进行访问,以防范跨站脚本攻击(XSS)。
SameSite=Strict
SameSite=Lax 可选 

允许服务器设定一则 cookie 不随着跨域请求一起发送,这样可以在一定程度上防范跨站请求伪造攻击(CSRF)。

示例

会话期 cookies 将会在客户端关闭时被移除。 会话期 cookie 不设置 Expires 或 Max-Age 指令。注意浏览器通常支持会话恢复功能。

Set-Cookie: sessionid=38afes7a8; HttpOnly; Path=/

持久化 Cookie 不会在客户端关闭时失效,而是在特定的日期(Expires)或者经过一段特定的时间之后(Max-Age)才会失效。

Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly

非法域

属于特定域的 cookie,假如域名不能涵盖原始服务器的域名,那么应该被用户代理拒绝。下面这个 cookie 假如是被域名为 originalcompany.com 的服务器设置的,那么将会遭到用户代理的拒绝:

Set-Cookie: qwerty=219ffwef9w0f; Domain=somecompany.co.uk; Path=/; Expires=Wed, 30 Aug 2019 00:00:00 GMT

名称中包含 __Secure- 或 __Host- 前缀的 cookie,只可以应用在使用了安全连接(HTTPS)的域中,需要同时设置 secure 指令。另外,假如 cookie 以 __Host- 为前缀,那么 path 属性的值必须为 "/" (表示整个站点),且不能含有 domain 属性。对于不支持 cookie 前缀的客户端,无法保证这些附加的条件成立,所以 cookie 总是被接受的。

// 当响应来自于一个安全域(HTTPS)的时候,二者都可以被客户端接受
Set-Cookie: __Secure-ID=123; Secure; Domain=example.com
Set-Cookie: __Host-ID=123; Secure; Path=/

// 缺少 Secure 指令,会被拒绝
Set-Cookie: __Secure-id=1

// 缺少 Path=/ 指令,会被拒绝
Set-Cookie: __Host-id=1; Secure

// 由于设置了 domain 属性,会被拒绝
Set-Cookie: __Host-id=1; Secure; Path=/; domain=example.com

规范

Specification Title
RFC 6265, section 4.1: Set-Cookie HTTP State Management Mechanism
RFC draft-ietf-httpbis-cookie-prefixes-00 Cookie Prefixes
RFC draft-ietf-httpbis-cookie-same-site-00 Same-Site Cookies
RFC draft-ietf-httpbis-cookie-alone-01 Strict Secure Cookies

浏览器兼容性

FeatureChromeFirefoxEdgeInternet ExplorerOperaSafari
Basic Support(Yes)(Yes)(Yes)(Yes)(Yes)(Yes)
Max-Age(Yes)(Yes)(Yes)8.0(Yes)(Yes)
HttpOnly1.03.0(Yes)9.0115.0
Cookie prefixes4950(Yes)?36(Yes)
SameSite51(No)1(No)(No)39(No)
FeatureAndroidChrome for AndroidEdge mobileFirefox for AndroidIE mobileOpera AndroidiOS Safari
Basic Support(Yes)(Yes)(Yes)(Yes)(Yes)(Yes)(Yes)
Max-Age(Yes)(Yes)(Yes)(Yes)(Yes)(Yes)(Yes)
HttpOnly?(Yes)(Yes)1.0(Yes)(Yes)iOS 4
Cookie prefixes?49(Yes)50?36(Yes)
SameSite5151(No)(No)1(No)39(No)

1. See bug 795346 on Bugzilla.

关于兼容性的注意事项

  • 从 Chrome 52 和 Firefox 52 开始,非安全站点(http:)已经不能再在 cookie 中设置 "secure"  指令了。

相关内容

文档标签和贡献者

 此页面的贡献者: WayneCui
 最后编辑者: WayneCui,