CookieJar Class
A cookie store as specified by the user agent requirements of RFC 6265bis (https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-user-agent-requirements): the cookies of the Set-Cookie headers of the responses and of the scripts (document.cookie, cookieStore), sent in the Cookie header of the requests (see DocumentRequest.GetCookieHeader).
public sealed class CookieJarRemarks
The jar implements the storage model (the Domain, Path, Expires, Max-Age, Secure, HttpOnly, SameSite and Partitioned attributes, the __Secure-, __Host-, __Http- and __Host-Http- prefixes, the public suffixes and the size limits) and the retrieval model (the "same-site" and "cross-site" requests, schemefully). The cookies with the Partitioned attribute are keyed by the site of the top-level document (CHIPS); the other cookies are not partitioned. By default, the third-party cookies are not blocked: CookieJar.BlockThirdPartyCookies and CookieJar.SetThirdPartyCookieAccess block the unpartitioned cookies in the third-party contexts, which the Storage Access API (Document.RequestStorageAccess) can then unblock.
The names and the values of the cookies are byte sequences, represented as strings whose characters are the bytes (isomorphic strings, as the values of the HTTP headers): a script stores the UTF-8 bytes of its strings. The expiry times are measured by the clock given to the constructor (e.g. BrowsingContextOptions.TimeProvider). The jar is thread-safe: it can be shared by several browsing contexts.
The cookies are kept in memory, and the persistent cookies (the cookies with an expiry time) are persisted by the CookiePersistence given to the constructor, if any.
Constructors
| Name | Description |
|---|---|
| CookieJar() | Creates an empty cookie jar, whose expiry times are measured by the system clock. |
| CookieJar(CookiePersistence?, TimeProvider?) | Creates a cookie jar whose persistent cookies are persisted: the jar contains the cookies of CookiePersistence.LoadCookies that are not expired, and reports its changes to the persistence. |
| CookieJar(TimeProvider?) | Creates an empty cookie jar. |
CookieJar overloads
CookieJar()
CookieJar.csCreates an empty cookie jar, whose expiry times are measured by the system clock.
public CookieJar()CookieJar(CookiePersistence?, TimeProvider?)
CookieJar.csCreates a cookie jar whose persistent cookies are persisted: the jar contains the cookies of CookiePersistence.LoadCookies that are not expired, and reports its changes to the persistence.
public CookieJar(CookiePersistence? persistence, TimeProvider? timeProvider)Parameters
persistenceCookiePersistence?- The persistent storage of the cookies, or null to keep them in memory only.
timeProviderTimeProvider?- The clock that measures the creation and expiry times of the cookies, or null for
TimeProvider.System.
CookieJar(TimeProvider?)
CookieJar.csCreates an empty cookie jar.
public CookieJar(TimeProvider? timeProvider)Parameters
timeProviderTimeProvider?- The clock that measures the creation and expiry times of the cookies, or null for
TimeProvider.System.
Properties
| Name | Description |
|---|---|
| BlockThirdPartyCookies | Gets or sets whether the unpartitioned cookies are blocked in the third-party contexts (third-party cookie blocking): the documents and the requests whose site is not the site of their top-level document, or that have a cross-site ancestor, neither send nor store the cookies without the Partitioned attribute, unless they have storage access (https://privacycg.github.io/storage-access/, see Document.RequestStorageAccess). The rules of CookieJar.SetThirdPartyCookieAccess take precedence. The default value is false: as in the browsers that do not block the third-party cookies, the unpartitioned cookies are available in every context, so every document has storage access (Document.HasStorageAccess), and the cross-site requests have the active storage access status (the Sec-Fetch-Storage-Access header). |
| OriginBound | Gets whether the cookies are bound to the origin that set them (origin-bound cookies, https://github.com/explainers-by-googlers/origin-bound-cookies): a cookie is only sent to the URLs of the scheme that set it (secure or not), a cookie without Domain attribute only to the URLs of the port that set it, and the cookies of the same name set by another scheme or another port do not replace each other. The default value is false: as in the browsers that do not enable origin-bound cookies, the cookies of a host are shared by its schemes and ports. |
| Persistence | Gets the persistent storage of the cookies, or null when they are kept in memory only. |
BlockThirdPartyCookies
CookieJar.csGets or sets whether the unpartitioned cookies are blocked in the third-party contexts (third-party cookie blocking): the documents and the requests whose site is not the site of their top-level document, or that have a cross-site ancestor, neither send nor store the cookies without the Partitioned attribute, unless they have storage access (https://privacycg.github.io/storage-access/, see Document.RequestStorageAccess). The rules of CookieJar.SetThirdPartyCookieAccess take precedence. The default value is false: as in the browsers that do not block the third-party cookies, the unpartitioned cookies are available in every context, so every document has storage access (Document.HasStorageAccess), and the cross-site requests have the active storage access status (the Sec-Fetch-Storage-Access header).
public bool BlockThirdPartyCookies { get; set; }Property value
OriginBound
CookieJar.csGets whether the cookies are bound to the origin that set them (origin-bound cookies, https://github.com/explainers-by-googlers/origin-bound-cookies): a cookie is only sent to the URLs of the scheme that set it (secure or not), a cookie without Domain attribute only to the URLs of the port that set it, and the cookies of the same name set by another scheme or another port do not replace each other. The default value is false: as in the browsers that do not enable origin-bound cookies, the cookies of a host are shared by its schemes and ports.
public bool OriginBound { get; init; }Property value
Persistence
CookieJar.csGets the persistent storage of the cookies, or null when they are kept in memory only.
public CookiePersistence? Persistence { get; }Property value
Methods
| Name | Description |
|---|---|
| Clear() | Removes all the cookies, and the persisted cookies of CookieJar.Persistence. |
| GetCookies() | Returns the cookies of the jar that are not expired, in the order of their creation. |
| GetCookies(string) | Returns the cookies that would be sent to url by a request that is same-site with it, including the HttpOnly cookies (the associated cookies of WebDriver, https://w3c.github.io/webdriver/#dfn-associated-cookies), in the order of the Cookie header. The partitioned cookies are the ones of the site of the URL. |
| Remove(StoredCookie) | Removes a cookie (with the same name, domain, path, partition and origin binding). Returns false when the jar does not contain it. |
| SetCookie(string, string) | Stores the cookie of a Set-Cookie header received from url in a response to a same-site request (e.g. to restore cookies). Returns false when the cookie is ignored (an invalid cookie, or a cookie that the URL cannot set). |
| SetThirdPartyCookieAccess(string?, string?, bool) | Blocks or allows the unpartitioned cookies of a site in the third-party contexts of a top-level site (the settings of the user, and the Set Storage Access command of WebDriver, https://privacycg.github.io/storage-access/#set-storage-access-command). The rules override CookieJar.BlockThirdPartyCookies. The documents of a site whose cookies are allowed have storage access (Document.HasStorageAccess); the documents of a site whose cookies are blocked can request it (Document.RequestStorageAccess). |
Clear()
CookieJar.csRemoves all the cookies, and the persisted cookies of CookieJar.Persistence.
public void Clear()GetCookies overloads
GetCookies()
CookieJar.csReturns the cookies of the jar that are not expired, in the order of their creation.
public IReadOnlyList<StoredCookie> GetCookies()Returns
GetCookies(string)
CookieJar.csReturns the cookies that would be sent to url by a request that is same-site with it, including the HttpOnly cookies (the associated cookies of WebDriver, https://w3c.github.io/webdriver/#dfn-associated-cookies), in the order of the Cookie header. The partitioned cookies are the ones of the site of the URL.
public IReadOnlyList<StoredCookie> GetCookies(string url)Remove(StoredCookie)
CookieJar.csRemoves a cookie (with the same name, domain, path, partition and origin binding). Returns false when the jar does not contain it.
public bool Remove(StoredCookie cookie)SetCookie(string, string)
CookieJar.csStores the cookie of a Set-Cookie header received from url in a response to a same-site request (e.g. to restore cookies). Returns false when the cookie is ignored (an invalid cookie, or a cookie that the URL cannot set).
SetThirdPartyCookieAccess(string?, string?, bool)
CookieJar.csBlocks or allows the unpartitioned cookies of a site in the third-party contexts of a top-level site (the settings of the user, and the Set Storage Access command of WebDriver, https://privacycg.github.io/storage-access/#set-storage-access-command). The rules override CookieJar.BlockThirdPartyCookies. The documents of a site whose cookies are allowed have storage access (Document.HasStorageAccess); the documents of a site whose cookies are blocked can request it (Document.RequestStorageAccess).
Parameters
topLevelUrlstring?- A URL of the top-level site (e.g.
https://example.com/), or null for every top-level site. embeddedUrlstring?- A URL of the embedded site, or null for every site.
blockedbool- Whether the unpartitioned cookies are blocked.
Remarks
The rule of a specific pair of sites takes precedence over the rule of every embedded site, which takes precedence over the rules of every top-level site. A rule for every embedded site removes the rules of the specific embedded sites of its top-level sites.