NAME

Plack::Middleware::SignedCookies - accept only server-minted cookies

VERSION

version 1.203

SYNOPSIS

 # in app.psgi
 use Plack::Builder;
 
 builder {
     enable 'SignedCookies', secret => 's333333333kr1t!!!!1!!';
     $app;
 };

DESCRIPTION

This middleware modifies Cookie headers in the request and Set-Cookie headers in the response. It appends a HMAC digest to outgoing cookies and removes and verifies it from incoming cookies. It rejects incoming cookies that were sent without a valid digest.

The incoming Cookie header value remains available in the signedcookies.orig key in the PSGI environment.

CONFIGURATION OPTIONS

secret

The secret to pass to the Digest::SHA HMAC function.

If not provided, a random secret will be generated using Perl’s built-in rand function.

secure

Whether to force the secure flag to be set on all cookies, which instructs the browser to only send them when using an encrypted connection.

Defaults to false. You should strongly consider overriding this default with a true value.

httponly

Whether to force the HttpOnly flag to be set on all cookies, which instructs the browser to not make them available to Javascript on the page.

Defaults to true. Provide a defined false value if you wish to override this.

A NOTE ON EXPIRATION

Several other modules that offer similar functionality will also handle server-side cookie expiration. This is obviously useful for centralising all cookie policy in one place.

However, expiration is quite likely to be a concern at the application level, if only just to tell a user that they timed out rather than just suddenly forgetting them. Communicating server-side expiration from the middleware to the application requires a protocol. No standard protocol exists for this purpose, so it would have to be specific to this middleware.

But middlewares are most useful when they can be added or removed without modifying the application. (Frameworks, in contrast, require tight coupling of the application by definition, thus making it a reasonable choice to include cookie expiration plus interface in a framework.) Therefore, it was an explicit design choice for this middleware to omit expiration handling.

SEE ALSO

• RFC 6265, HTTP State Management Mechanism, section 4.1.2.5., The Secure Attribute

• MSDN, Mitigating Cross-site Scripting With HTTP-only Cookies

AUTHOR

Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Aristotle Pagaltzis.

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