trusted-types
trusted-types
trusted-types
The trusted-types directive helps prevent XSS attacks by requiring special security-checked values (called 'trusted types') instead of raw strings when modifying sensitive parts of a webpage.
Tips & Tricks
This directive is experimental and may not be supported in all browsers.
Together with require-trusted-types-for directive, this allows authors to define rules guarding writing values to the DOM and thus reducing the DOM XSS attack surface to small, isolated parts of the web application codebase, facilitating their monitoring and code review. This directive declares an allowlist of trusted type policy names created with trustedTypes.createPolicy from Trusted Types API.
Available Values
<policyName>
A valid policy name that can contain alphanumeric characters and -#=_/@.%. Using * allows any unique policy name.
A valid policy name that can contain alphanumeric characters and -#=_/@.%. Using * allows any unique policy name.
'none'
A valid policy name that can contain alphanumeric characters and -#=_/@.%. Using * allows any unique policy name.
A valid policy name that can contain alphanumeric characters and -#=_/@.%. Using * allows any unique policy name.
'allow-duplicates'
Allows duplicate policy names
Allows duplicate policy names
Examples
Allows trusted types from the same origin
Content-Security-Policy: trusted-types mypolicy1 mypolicy2 'allow-duplicates';Allowed
<!-- allowed by mypolicy1 mypolicy2 'allow-duplicates' --> <script> const policyFoo = trustedTypes.createPolicy('mypolicy1'', {}); const policyFoo = trustedTypes.createPolicy('mypolicy1', {}); const policyFoo = trustedTypes.createPolicy('mypolicy2', {}); </script>Blocked
<!-- blocked as the policy name is not allowed --> <script> const policyFoo = trustedTypes.createPolicy(''mypolicy3'', {}); </script>
Frequently Asked Questions
What is trusted-types and why should I use it?
trusted-types is a security feature that helps prevent DOM-based XSS attacks by requiring all scripts that manipulate DOM sinks to use pre-defined policies. It enforces type checking for potentially dangerous DOM operations like innerHTML, outerHTML, document.write(), and eval().
Browser Support
trusted-types is currently supported in Chrome and Edge. Other browsers will ignore this directive.
How do I implement trusted-types?
To implement trusted-types, you need to: 1) Define trusted type policies using trustedTypes.createPolicy(), 2) Add the trusted-types directive to your CSP header listing allowed policy names, and 3) Use the created policies to sanitize dynamic content before inserting it into DOM sinks.
Important
Always use require-trusted-types-for 'script' alongside trusted-types to enforce the policies.
What is the relationship between trusted-types and require-trusted-types-for?
trusted-types and require-trusted-types-for work together as a pair. While trusted-types defines which policies are allowed, require-trusted-types-for 'script' enforces that these policies must be used. Without require-trusted-types-for, the trusted-types directive only reports violations but doesn't block unsafe operations.
Security Note
Always use both directives together. Using trusted-types alone provides reporting but no enforcement.
What are common trusted-types policies?
Common trusted type policies include: HTML sanitization policies for user content, URL validation policies for dynamic sources, and script validation policies for evaluated code. Each policy should be carefully designed to handle specific use cases while maintaining security.
Best Practice
Create separate policies for different types of content and operations rather than using a single generic policy.
Need to monitor CSP violations and maintain it easily?
Set up a reporting endpoint to monitor Content Security Policy violations in real-time to build and maintain your CSP easily.
Set up your endpoint now