
Le OWASP Java Encoder est une classe d'encodeur Java 1.5+ haute performance, simple à utiliser et prête à l'emploi, sans dépendances et peu encombrante. Ce projet aidera les développeurs web Java à se défendre contre le Cross Site Scripting (XSS) !
Encodage contextuel de sortie pour Java 8+. Choisissez un encodeur adapté au contexte du parseur qui reçoit du texte non fiable : HTML, JavaScript, CSS, XML ou un composant d'URL. Le cœur n'a aucune dépendance d'exécution ; des adaptateurs optionnels JSP et Jakarta fournissent des liaisons pour la couche de vue. L'encodage n'est qu'un élément de la [prévention des XSS][xss], aux côtés de modèles sûrs, de la validation d'URL et d'autres contrôles applicatifs.
La version 1.6.0 est disponible sur Maven Central. Cette version mineure réduit l'échappement inutile des lettres en JavaScript tout en préservant la protection reconnue des jetons HTML à travers les fragments de confiance. Les octets encodés et le comportement de streaming changent ; consultez les notes de version et la vérification de publication.
Les correctifs de sécurité aux frontières du parseur introduits dans la 1.5.0 restent en vigueur ; les versions jusqu'à la 1.4.1 ne contiennent pas ces correctifs. Consultez l'avis de sécurité et VERIFYING.md.
Sélectionnez la dépendance dont vous avez besoin.
Les trois artefacts pris en charge utilisent l'identifiant de groupe org.owasp.encoder :
| Artifact ID | Purpose and runtime dependencies |
|---|---|
encoder | API String/Writer de base ; aucune dépendance d'exécution |
encoder-jsp | Balises JSP/EL javax héritées ; cœur plus API JSP fournie par le conteneur |
encoder-jakarta-jsp | Balises JSP/EL Jakarta ; cœur plus API JSP Jakarta fournie par le conteneur |
<dependency>
<groupId>org.owasp.encoder</groupId>
<artifactId>encoder</artifactId>
<version>1.6.0</version>
</dependency>
Remplacez encoder par l'ID d'artefact d'un adaptateur de balise lorsque nécessaire ; chaque adaptateur intègre le core. Maintenez alignées les versions core/adaptateur gérées séparément. Utilisez un seul des JARs taglib javax ou Jakarta : ils partagent org.owasp.encoder.tag et ne doivent pas coexister sur le même classpath ou module path. Consultez la matrice d'exécution et l'inventaire des dépendances/licences.
encoder-esapi a été retiré après la version 1.4.1 et n'est ni inclus ni pris en charge dans les versions 1.5.x ou 1.6.0. Les applications qui l'utilisent doivent migrer hors de l'adaptateur.
Documentation de l'API 1.6.0 publiée (l'indexation hébergée peut être en retard sur la publication) : core, javax JSP et Jakarta JSP.
import org.owasp.encoder.Encode;
out.write("<p>");
Encode.forHtmlContent(out, userText); // Writer overload; no intermediate String
out.write("</p>");
L'appel String équivalent est Encode.forHtmlContent(userText). Les appelants fournissent la syntaxe environnante de confiance et les guillemets d'attribut. Encodez les données brutes une seule fois, à la frontière de sortie ; tenez compte de tout échappement déjà effectué par votre moteur de template.
| Destination | API et limites |
|---|---|
| Texte HTML, y compris le contenu de textarea | forHtmlContent ; forHtml couvre également les attributs de texte ordinaires entre guillemets |
| Attribut de texte HTML entre guillemets | forHtmlAttribute ; ce n'est pas un validateur d'expression de gestionnaire d'événements ni d'URL |
| Un composant d'URL brut | forUriComponent ; assemblez avec des délimiteurs de confiance, validez l'URL, puis encodez pour l'attribut HTML englobant |
| Chaîne JavaScript | forJavaScript ; fournissez les guillemets simples/doubles. Le texte ordinaire d'un template literal non étiqueté nécessite la 1.5. À ne jamais utiliser dans des templates étiquetés, des corps d'expression, du JSON ou des URL de script |
| Contenu de chaîne JSON | forJson (1.5) ; fournissez les guillemets doubles. Préférez un sérialiseur pour un document complet |
Chaîne CSS entre guillemets / valeur CSS url(...) | forCssString / forCssUrl ; validez les URL et respectez les règles de contexte environnant de la méthode |
| Texte XML 1.0 / attribut entre guillemets | forXmlContent / forXmlAttribute ; forXml couvre les deux |
| Texte XML 1.1 / attribut entre guillemets | forXml11Content / forXml11Attribute (cœur 1.4+) ; nécessite un document/analyseur XML 1.1, pas HTML |
| CDATA XML / commentaire | forCDATA / forXmlComment ; pas les commentaires HTML |
| Littéral de chaîne source Java | forJava ; l'appelant fournit les guillemets ; les surrogates non appariés peuvent ne pas compiler |
Chaque méthode de façade listée possède des surcharges String et Writer. Le guide des contextes explique l'imbrication, le comportement null/Unicode, les variantes JavaScript, les frontières de template, JSON et les contextes non sûrs. Les exemples Java/JSP montrent la syntaxe environnante complète.
L'encodage n'assainit pas le HTML, ne valide pas les entrées/URL, ne sérialise pas les documents JSON, n'effectue pas de paramétrage SQL, et ne décode ni ne canonicalise les données. Utilisez un assainisseur HTML lorsque le balisage doit être autorisé ; utilisez des requêtes paramétrées pour SQL. Consultez le [guide de la bibliothèque de sécurité Java OWASP][java-libraries] pour ces rôles distincts.
Les URI de taglib sont des identifiants, et non des URL qui doivent s'ouvrir dans un navigateur :
| Adaptateur | Identifiant de base | Identifiant avancé |
|---|---|---|
| Jakarta | owasp.encoder.jakarta | owasp.encoder.jakarta.advanced |
| javax JSP | https://www.owasp.org/index.php/OWASP_Java_Encoder_Project | Même identifiant avec #advanced ajouté |
<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="e" uri="owasp.encoder.jakarta" %>
<p>${e:forHtmlContent(param.message)}</p>
Utilisez l'identifiant javax pour un conteneur javax. Les balises utilisent un corps vide et un attribut value obligatoire, par exemple <e:forHtmlContent value="${param.message}" />.
Consultez bindings and EL evaluation pour
les méthodes basiques et avancées ainsi que les paramètres de déploiement sensibles à la version. Dans la version 1.5,
les taglibs avancées exposent chaque contexte Encode.forX(String) sauf forJava ;
la génération de code source Java n'est pas un contexte JSP. Les bindings XML 1.1 sont nouveaux dans la version 1.5.