/kirby-sri

Subresource integrity hashing & cache-busting static assets for Kirby

Primary LanguagePHPMIT LicenseMIT

Kirby SRI

Release License Issues

This plugin generates base64-encoded cryptographic hashes for your css / js files based on their content and adds them to the integrity attribute of their corresponding <link> or <script> elements. It also applies cache-busting / fingerprinting.

Table of contents

What's SRI?

"Subresource Integrity (SRI) is a security feature that enables browsers to verify that files they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched file must match."

Source: Mozilla Developer Network

Enter kirby-sri: Kirby-side generated SRI hashes for safer CDN usage. Read more about CDN integration and Kirby in the docs) or over at Kirby's partner KeyCDN to get started.

screenshot of the kirby-sri plugin

This plugin only provides hash generation. For usage with CDNs, refer to Kirby's official cdn-plugin!

Getting started

Use one of the following methods to install & use kirby-sri:

Git submodule

If you know your way around Git, you can download this plugin as a submodule:

git submodule add https://github.com/S1SYPHOS/kirby-sri.git site/plugins/kirby-sri

Composer

composer require S1SYPHOS/kirby-sri

Clone or download

  1. Clone or download this repository.
  2. Unzip / Move the folder to site/plugins.

Make sure the folder name is kirby-sri.

Activate the plugin

Activate the plugin with the following line in your config.php:

c::set('plugin.kirby-sri', true);

Kirby's built-in helper functions css() and js() will now include an integrity attribute alongside the matching SRI hash. If you want to activate kirby-sri only on specific domains, read about multi-environment setups.

Configuration

Change kirby-sri options to suit your needs:

Option Type Default Description
plugin.kirby-sri.algorithm String sha512 Defines the cryptographic hash algorithm (currently the allowed prefixes are sha256, sha384 and sha512).
plugin.kirby-sri.crossorigin String anonymous Defines crossorigin attribute.
plugin.kirby-sri.fingerprinting Boolean true Optionally enables / disables fingerprinting.

Cache-busting / Fingerprinting

Same old, same old. If anyone comes up with a solution how subresource integrity and cache-busting / fingerprinting could be achieved by different plugins (as all of them modify Kirby's built-in helper functions css() and js()), feel free to open a PR! Otherwise, follow the next steps:

Apache

If you're using Apache as your webserver, add the following lines to your .htaccess (right after RewriteBase):

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.+)\.([0-9]{10})\.(js|css)$ $1.$3 [L]

NGINX

If you're using NGINX as your webserver, add the following lines to your virtual host setup:

location /assets {
  if (!-e $request_filename) {
    rewrite "^/(.+)\.([0-9]{10})\.(js|css)$" /$1.$3 break;
  }
}

Note: SRI hash generation & cache-busting are not applied to external URLs!

Be safe - use protection!

Always use https:// URLs when loading subresources from a CDN, otherwise they might get blocked:

Mixed content occurs when initial HTML is loaded over a secure HTTPS connection, but other resources (such as images, videos, stylesheets, scripts) are loaded over an insecure HTTP connection. This is called mixed content because both HTTP and HTTPS content are being loaded to display the same page, and the initial request was secure over HTTPS. Modern browsers display warnings about this type of content to indicate to the user that this page contains insecure resources. Google Developers

Credits / License

kirby-sri was inspired by Kirby plugins cachebuster (by Kirby team members Bastian Allgeier and Lukas Bestle) as well as fingerprint (by Iksi). It is licensed under the MIT License, but using Kirby in production requires you to buy a license. Are you ready for the next step?

Special Thanks

I'd like to thank everybody that's making great software - you people are awesome. Also I'm always thankful for feedback and bug reports :)