Document : méthode statique parseHTMLUnsafe()

Syntaxe

Document.parseHTMLUnsafe(input)
Document.parseHTMLUnsafe(input, options)

Paramètres

input

Une instance de TrustedHTML ou une chaîne de caractères définissant le HTML à analyser.

options Facultatif

Un objet d'options avec les paramètres optionnels suivants :

sanitizer Facultatif

Un objet Sanitizer ou SanitizerConfig qui définit quels éléments de l'entrée seront autorisés ou supprimés. Cela peut également être une chaîne de caractères avec la valeur "default", qui applique un Sanitizer avec la configuration par défaut (sécurisée contre les XSS). Si aucun n'est défini, aucun assainisseur n'est utilisé.

Notez qu'en général, un Sanitizer est attendu pour être plus efficace qu'un SanitizerConfig si la configuration doit être réutilisée.

Valeur de retour

Un objet Document.

Exceptions

TypeError

Ceci est levé si :

• html reçoit une chaîne de caractères lorsque Trusted Types sont appliqués par une CSP et qu'aucune politique par défaut n'est définie.
• options.sanitizer reçoit :
  • SanitizerConfig qui n'est pas valide. Par exemple, une configuration qui inclut à la fois les paramètres "allowed" et "removed".
  • une chaîne de caractères qui n'a pas la valeur "default".
  • une valeur qui n'est pas un Sanitizer, SanitizerConfig, ou une chaîne de caractères.

Description

La méthode statique parseHTMLUnsafe() peut être utilisée pour créer une nouvelle instance de Document, en filtrant éventuellement les éléments et attributs indésirables. Le Document résultant aura un type de contenu de "text/html", un encodage de caractères UTF-8 et une URL « about:blank ».

Le HTML d'entrée peut inclure des racines d'ombre déclaratives. Si la chaîne HTML définit plus d'une racine d'ombre déclarative dans un hôte d'ombre donné, seule la première ShadowRoot est créée — les déclarations suivantes sont analysées comme des éléments <template> à l'intérieur de cette racine d'ombre.

parseHTMLUnsafe() n'effectue aucun assainissement par défaut. Si aucun assainisseur n'est passé en paramètre, toutes les entités HTML de l'entrée seront injectées.

Considérations de sécurité

Le suffixe « Unsafe » dans le nom de la méthode indique qu'elle ne supprime pas toutes les entités HTML non sécurisées contre les XSS (contrairement à Document.parseHTML()). Elle peut le faire si elle est utilisée avec un assainisseur adapté, mais elle n'est pas obligée d'utiliser un assainisseur efficace, ni même d'en utiliser un ! La méthode constitue donc un vecteur possible pour des attaques de script inter-sites (XSS), où des chaînes potentiellement non sécurisées fournies par un·e utilisateur·ice sont injectées dans le DOM sans être assainies au préalable.

Vous pouvez atténuer ce risque en passant toujours des objets TrustedHTML au lieu de chaînes de caractères et en appliquant des types de confiance à l'aide de la directive CSP require-trusted-types-for. Cela garantit que l'entrée passe par une fonction de transformation, qui a la possibilité de assainir l'entrée pour supprimer les balises potentiellement dangereuses (comme les éléments <script> et les attributs de gestionnaire d'évènements), avant qu'elle ne soit injectée.

L'utilisation de TrustedHTML permet d'auditer et de vérifier que le code d'assainissement est efficace à quelques endroits seulement, plutôt que dispersé dans tous les points d'injection. Il n'est pas nécessaire de passer un assainisseur à la méthode lorsque vous utilisez TrustedHTML.

Si, pour une raison quelconque, vous ne pouvez pas utiliser TrustedHTML (ou mieux, setHTML()), l'option la plus sûre suivante consiste à utiliser setHTMLUnsafe() avec la configuration par défaut de Sanitizer sécurisée contre les XSS.

Spécifications

Compatibilité des navigateurs

Voir aussi

• La méthode statique Document.parseHTML()
• Les méthodes Element.setHTML() et Element.setHTMLUnsafe()
• Les méthodes ShadowRoot.setHTML() et ShadowRoot.setHTMLUnsafe()
• La méthode DOMParser.parseFromString() pour analyser HTML ou XML en un arbre DOM
• L'API HTML Sanitizer