HTTP CSP trusted-types

Die trusted-types Direktive der Content Security Policy definiert erlaubte Namen für Trusted Type Policies mit Policy-Whitelisting.

Typ

CSP-Direktive zur Definition erlaubter Policy-Namen für Trusted Types, kontrolliert Sanitization-Policy-Erstellung und verhindert DOM-XSS durch strikte Policy-Whitelisting in API-getriebenen Anwendungen.

Syntax

Die Direktive akzeptiert eine whitespace-getrennte Liste erlaubter Policy-Namen plus optionale Schlüsselwörter.

http 
Content-Security-Policy: trusted-types <policy-names>

Direktiven

Die trusted-types Direktive definiert erlaubte Policy-Namen für granulare Kontrolle über Sanitization-Policies.

policy-name
Name einer erlaubten Trusted Type Policy. Nur Policies mit diesen exakten Namen können via trustedTypes.createPolicy() erstellt werden.
'allow-duplicates'
Erlaubt mehrere Policies mit demselben Namen. Ohne dieses Keyword würde die zweite createPolicy() mit identischem Namen fehlschlagen.

Beispiele

Praktische Szenarien für trusted-types in React SPAs Microservice-Dashboards und Security-kritischen Banking-APIs mit Policy-Whitelisting.

SPA mit Single-Policy-Setup

React-Applikationen nutzen eine zentrale Sanitization-Policy für alle DOM-Updates:

http 
HTTP/2 200 OK
Content-Type: text/html
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-sanitizer

<!DOCTYPE html>
<html>
<script>
  // Erlaubt
  const policy = trustedTypes.createPolicy('app-sanitizer', {
    createHTML: (input) => DOMPurify.sanitize(input),
    createScriptURL: (url) => url.startsWith('/') ? url : ''
  });

  // Blockiert (Policy-Name nicht erlaubt)
  const badPolicy = trustedTypes.createPolicy('different-name', {
    createHTML: (input) => input // Unsafe!
  }); // TypeError: Policy 'different-name' disallowed

  // API-Response sicher verarbeiten
  fetch('/api/content').then(r => r.json()).then(data => {
    document.getElementById('content').innerHTML = policy.createHTML(data.html);
  });
</script>
</html>

Nur die app-sanitizer Policy kann erstellt werden. Andere Policy-Namen werden blockiert.

Microservice-Dashboard mit Multi-Policy-Architecture

Komplexe Dashboards nutzen verschiedene Policies für unterschiedliche Content-Typen:

http 
HTTP/2 200 OK
Content-Type: text/html
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types html-sanitizer script-validator url-checker 'allow-duplicates'

<!DOCTYPE html>
<html>
<script>
  // HTML-Sanitization für User-Content
  const htmlPolicy = trustedTypes.createPolicy('html-sanitizer', {
    createHTML: (input) => sanitizeUserHTML(input)
  });

  // Script-URL-Validation für dynamische Imports
  const scriptPolicy = trustedTypes.createPolicy('script-validator', {
    createScriptURL: (url) => validateScriptSource(url) ? url : ''
  });

  // URL-Validation für iframes
  const urlPolicy = trustedTypes.createPolicy('url-checker', {
    createURL: (url) => allowedDomains.includes(new URL(url).hostname) ? url : ''
  });

  // Mit 'allow-duplicates': Module können eigene Policies mit gleichen Namen erstellen
  const modulePolicy = trustedTypes.createPolicy('html-sanitizer', {
    createHTML: (input) => moduleSpecificSanitization(input)
  });
</script>
</html>

Drei verschiedene Policy-Namen sind erlaubt. 'allow-duplicates' ermöglicht modulare Architekturen.

Security-kritische API mit Policy-Lockdown

Banking-APIs verbieten alle Trusted Type Policies, um jegliche DOM-Manipulation zu blockieren:

http 
HTTP/2 200 OK
Content-Type: application/json
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types 'none'
X-Content-Type-Options: nosniff

<!DOCTYPE html>
<html>
<script>
  // Blockiert (keine Policy-Erstellung erlaubt)
  const policy = trustedTypes.createPolicy('any-name', {
    createHTML: (input) => input
  }); // TypeError: Policy creation disallowed

  // Alle DOM-Sink-APIs blockiert
  document.getElementById('content').innerHTML = '<p>Text</p>'; // TypeError

  // Einziger Weg: Sichere DOM-APIs
  const p = document.createElement('p');
  p.textContent = 'Safe text'; // OK
  document.getElementById('content').appendChild(p); // OK
</script>
</html>

Kompletter DOM-XSS-Schutz durch Verbot aller Policy-Erstellungen und Enforcement der Trusted Types.

Policy-Whitelisting-Flow

Visualisierung des Trusted Types Policy-Whitelisting-Prozesses mit CSP-Enforcement und unauthorized Policy-Blocking.

plantuml 
@startuml
actor Developer
participant "Browser" as Browser
participant "API Server" as API
participant "Trusted Types Engine" as TT
participant "CSP Engine" as CSP

Developer -> Browser: Load application
Browser -> API: GET /app
API -> Browser: HTML + CSP: require-trusted-types-for 'script'\ntrusted-types app-policy default

Browser -> Browser: Initialize Trusted Types
Browser -> TT: Configure allowed policies
TT -> TT: Whitelist: ['app-policy', 'default']
note right: Nur diese Policy-Namen erlaubt

Browser -> Browser: Execute JavaScript
Browser -> TT: trustedTypes.createPolicy('app-policy', {...})
TT -> CSP: Check policy name against whitelist
CSP -> CSP: 'app-policy' in whitelist
CSP -> TT: Allow policy creation
TT -> Browser: Return policy object
note right: Policy erfolgreich erstellt

Browser -> Browser: API call + DOM update
Browser -> TT: policy.createHTML(apiData)
TT -> TT: Execute sanitization function
TT -> Browser: Return TrustedHTML object

Browser -> Browser: element.innerHTML = trustedHTML
Browser -> CSP: Check Trusted Types requirement
CSP -> CSP: TrustedHTML object provided
CSP -> Browser: Allow DOM update
note right: Sicheres DOM-Update

alt Blocked: Disallowed policy name
    Browser -> TT: trustedTypes.createPolicy('evil-policy', {...})
    TT -> CSP: Check 'evil-policy'
    CSP -> CSP: Not in whitelist
    CSP -> TT: Block policy creation
    TT -> Browser: TypeError thrown
    note right: Unauthorized Policy blockiert
end

alt Blocked: Raw string to innerHTML
    Browser -> Browser: element.innerHTML = rawString
    Browser -> CSP: Check Trusted Types requirement
    CSP -> CSP: String (not TrustedHTML) provided
    CSP -> Browser: TypeError thrown
    note right: DOM-XSS verhindert
end
@enduml

Vorteile für die Systemarchitektur

Policy-Whitelisting verhindert unauthorized Sanitization-Policies und ermöglicht modulare Security-Architekturen für Defense-in-Depth DOM-XSS-Prevention.

  • Policy-Whitelisting: Kontrolliert präzise welche Sanitization-Policies erstellt werden dürfen verhindert Bypass-Versuche durch unauthorized Policy-Erstellungen
  • Modulare Security-Architekturen: allow-duplicates ermöglicht verschiedene Module mit eigenen Policies ideal für Micro-Frontend-Architekturen mit API-Integration
  • Defense-in-Depth: Kombiniert mit require-trusted-types-for entsteht mehrschichtige DOM-XSS-Prevention durch Policy-Whitelisting plus Trusted-Types-Enforcement

Spezifikation

Die trusted-types Direktive ist Teil der Trusted Types Spezifikation:

Best Practice: Kombiniere trusted-types mit require-trusted-types-for 'script' für vollständigen DOM-XSS-Schutz. Nutze 'allow-duplicates' nur wenn modulare Architekturen es erfordern.

Weitere Spezifikationen

CSP require-trusted-types-for, Content-Security-Policy Header