Dancer...:Cookie(3pm)

💖 Dancer::Session::Cookie — the manual, but make it slay 💖

okay bestie, so this is the Dancer::Session::Cookie page, straight outta the User Contributed Perl Documentation collection, and I am so ready to walk you through it. it's giving "sessions but they live in cookies" and honestly? iconic. let's go 🫶

---

✨ VERSION ✨

version 0.30 — that's the one, no cap.

---

🌸 SYNOPSIS 🌸

your config.yml should be looking like this, bestie:

session: "cookie"
session_cookie_key: "this random key IS NOT very random"

not me putting an actual warning in the example key 💀 that string is literally telling you it is not random. do better than the example, please.

---

💅 DESCRIPTION 💅

so this module implements a session engine where the sessions are stored entirely in cookies. normally the tea is: only the session id goes in the cookie and the actual session data gets yeeted off to some external storage like a database. this module? it lets you avoid external storage completely. no database, no problem. ✨

now, here's the thing — a server cannot trust any data that clients send back in cookies. so instead of just vibing and trusting everyone, this module uses cryptography to guarantee both integrity and secrecy. the data your app stores in sessions is completely protected from both tampering and analysis on the client side. nobody's peeking, nobody's editing. periodt. 🔥

⚠️ but do be aware, bestie: browsers limit the size of individual cookies, so this method is not suitable if you wanna store a large amount of data. browsers typically cap a cookie at 4KB — and that includes the space for the cookie's name, expiration, and other attributes, not just its content. so like... budget accordingly. 😭

---

🎀 CONFIGURATION 🎀

the settings, one by one

• the setting session should be set to "cookie" if you wanna use this session engine in a Dancer application. go see Dancer::Config for the deets.
• another setting is also required: session_cookie_key. it should contain a random string of at least 16 characters. and no, shorter keys are not cryptographically strong using AES in CBC mode — that's not me being dramatic, that's just facts. 💀
• the optional setting session_expires can also be passed in, and it provides the duration time of the cookie. if it's not present, the cookie just won't have an expiration value. she simply has no expiry date. 💁

example config, served fresh

here's an example configuration to use in your config.yml:

session: "cookie"
session_cookie_key: "kjsdf07234hjf0sdkflj12*&(@*jk"
session_expires: 1 hour

the security talk (important, bestie)

🚨 compromising session_cookie_key will disclose session data to clients and proxies or eavesdroppers, and it will also allow tampering — for example, session theft. so your config.yml should be kept at least as secure as your database passwords, or even more. fr fr.

also! changing session_cookie_key has the effect of immediate invalidation of all sessions issued with the old value of the key. so like, rotate responsibly. 🦋

the extra knobs

• session_cookie_path can be used to control the path of the session cookie. the default is "/".
• the global session_secure setting is honored, and a secure (https only) cookie will be used if it's set. 🔒

---

🧚 DEPENDENCY 🧚

this module depends on Session::Storage::Secure.

legacy support is provided using Crypt::CBC, Crypt::Rijndael, String::CRC32, Storable and MIME::Base64. vintage but valid. 👑

---

🌈 SEE ALSO 🌈

• see Dancer::Session for details about session usage in route handlers.
• see Plack::Middleware::Session::Cookie, Catalyst::Plugin::CookiedSession, and "session" in Mojolicious::Controller for alternative implementations of this mechanism. the girls are all doing the same thing in different fonts, and that's beautiful. 💖

---

👑 AUTHORS 👑

• Alex Kapranoff <kappa@cpan.org>
• Alex Sukria <sukria@cpan.org>
• David Golden <dagolden@cpan.org>
• Yanick Champoux <yanick@cpan.org>

absolute legends, all four of them. 🫶

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2018, 2015, 2014, 2011 by Alex Kapranoff.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie! this beauty ships with perl v5.36.0 and the docs are dated 2023-01-05 — so go forth, encrypt those cookies, keep your session_cookie_key secret, and remember: 4KB is the limit, and the limit is real. mwah 💅✨