CSP hash

Why It Matters

For developers, CSP hashes are essential when working with legacy code or frameworks that rely on inline scripts or styles. Without proper handling, such inline code can break functionality while violating CSP rules, leading to runtime errors or security vulnerabilities.

Security-conscious developers use CSP hashes to avoid overly restrictive policies that would prevent legitimate inline code from executing. This is particularly relevant in environments where CSP enforcement is strict, such as in enterprise applications or high-security contexts. By using hashes, developers can maintain granular control over what inline code is allowed, rather than disabling CSP entirely.

How It Works

The CSP hash mechanism operates by computing a cryptographic hash of inline script or style content and including that hash in a CSP directive. The browser then compares the computed hash of the inline content with the allowed hashes in the policy. If there is a match, the inline content is permitted to execute.

• Hash algorithms supported include SHA-256, SHA-384, and SHA-512.
• Each hash must be base64-encoded and prefixed with the algorithm name.
• Hashes are computed over the exact content, including whitespace and formatting.
• Inline scripts or styles must match the hash exactly to be allowed.
• Multiple hashes can be included in a single directive to allow multiple inline elements.

Quick Reference

Basic Example

This example shows how to use a CSP hash to allow a specific inline script to execute while maintaining CSP enforcement.

<meta http-equiv="Content-Security-Policy"
  content="script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';">
<script>
  console.log('Hello, world!');
</script>

This example demonstrates a CSP policy that allows inline scripts and styles. In a production environment, this would be replaced with a hash-based approach to avoid using 'unsafe-inline'.

Production Example

This example shows how to compute a CSP hash and use it in a production policy to allow specific inline scripts.

<meta http-equiv="Content-Security-Policy"
  content="script-src 'self' 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=';">
<script>
  console.log('Hello, world!');
</script>

This version computes a hash of the inline script content and includes it in the CSP policy. This allows the script to execute while maintaining strict CSP enforcement, avoiding the use of 'unsafe-inline' which can introduce security vulnerabilities.

Common Mistakes

• Using 'unsafe-inline' in CSP directives instead of hashes, which undermines security.
• Forgetting to base64-encode the hash, causing CSP to ignore the directive.
• Modifying inline content without updating the hash, leading to policy violations.
• Using SHA-384 or SHA-512 without ensuring compatibility with all target browsers.
• Not testing CSP policies with hashes in development environments, leading to runtime errors.

Security And Production Notes

• Always use SHA-256 for compatibility with older browsers and tools.
• Ensure that inline content matches the hash exactly, including whitespace.
• Update hashes whenever inline script or style content changes.
• Hashes should be computed during build time to avoid runtime overhead.
• Test CSP policies thoroughly in staging environments before deploying to production.

Related Concepts

Content Security Policy (CSP) is a foundational concept that governs how resources are loaded and executed. CSP hashes are a specific feature within CSP that allows inline code to be permitted while maintaining overall policy enforcement. Related concepts include CSP directives such as script-src, style-src, and nonce, which also provide mechanisms for controlling inline code execution. Inline scripts and styles are a common source of CSP violations, making hash-based approaches essential for maintaining security while enabling necessary functionality. Finally, CSP reporting and violation logging help developers identify and resolve issues related to inline content and hash mismatches.

Further Reading

• MDN Web Docs
• WHATWG HTML Standard