"); +Encode.forHtmlContent(out, userText); // Writer overload; no intermediate String +out.write("
"); ``` -To validate that the Jakarta JSP tags and EL functions work correctly, run the integration test: - -```shell -./mvnw verify -PtestJakarta +The equivalent String call is `Encode.forHtmlContent(userText)`. Callers supply +trusted surrounding syntax and attribute quotes. Encode raw data once, at the +output boundary; account for any escaping your template engine already performs. + +## Choose the output context + +| Destination | API and limits | +| --- | --- | +| HTML text, including textarea content | `forHtmlContent`; `forHtml` also covers quoted ordinary text attributes | +| Quoted HTML text attribute | `forHtmlAttribute`; not an event-handler expression or URL validator | +| One raw URL component | `forUriComponent`; assemble with trusted delimiters, validate the URL, then encode for the enclosing HTML attribute | +| JavaScript string | `forJavaScript`; supply single/double quotes. Ordinary untagged template literal text requires **1.5**. Never use in tagged templates, expression bodies, JSON or script URLs | +| JSON string content | `forJson` (**1.5**); supply double quotes. Prefer a serializer for a complete document | +| Quoted CSS string / CSS `url(...)` value | `forCssString` / `forCssUrl`; validate URLs and obey the method's surrounding-context rules | +| XML 1.0 text / quoted attribute | `forXmlContent` / `forXmlAttribute`; `forXml` covers both | +| XML 1.1 text / quoted attribute | `forXml11Content` / `forXml11Attribute` (core **1.4+**); requires an XML 1.1 document/parser, not HTML | +| XML CDATA / comment | `forCDATA` / `forXmlComment`; not HTML comments | +| Java source string literal | `forJava`; caller supplies quotes; unpaired surrogates may not compile | + +Every listed facade method has String and Writer overloads. The +[context guide](docs/contexts.md) explains nesting, null/Unicode behavior, +JavaScript variants, template boundaries, JSON and unsafe contexts. The +[Java/JSP examples](docs/usage.md) show complete surrounding syntax. + +Encoding does not sanitize HTML, validate input/URLs, serialize JSON documents, +perform SQL parameterization, or decode/canonicalize data. Use an HTML sanitizer +when markup must be allowed; use parameterized queries for SQL. See the +[OWASP Java security-library guide][java-libraries] for these distinct roles. + +## Taglib + +Taglib URIs are **identifiers**, not URLs that must open in a browser: + +| Adapter | Basic identifier | Advanced identifier | +| --- | --- | --- | +| Jakarta | `owasp.encoder.jakarta` | `owasp.encoder.jakarta.advanced` | +| javax JSP | `https://www.owasp.org/index.php/OWASP_Java_Encoder_Project` | Same identifier with `#advanced` appended | + +```jsp +<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %> +<%@ taglib prefix="e" uri="owasp.encoder.jakarta" %> +${e:forHtmlContent(param.message)}
``` -The integration test requires a running Docker-compatible container runtime. - -Java 9+ Module Names --------------------- - -| JAR | Explicit JPMS Module | Automatic-Module-Name | -|---------------------|-----------------------|--------------------------| -| encoder | owasp.encoder | org.owasp.encoder | -| encoder-jakarta-jsp | owasp.encoder.jakarta | org.owasp.encoder.jakarta | -| encoder-jsp | owasp.encoder.jsp | org.owasp.encoder.jsp | -| encoder-esapi | owasp.encoder.esapi | org.owasp.encoder.esapi | - -The multi-release descriptors define the explicit Java 9+ module names. The -manifest names intentionally retain their historical values for consumers that -disable multi-release support or otherwise use automatic-module discovery. - -The adapter modules also require their public API dependency on the module path: - -| Adapter module | Required dependency module | Supported Maven artifact | -|---------------------------|----------------------------|-------------------------------------------------------| -| `owasp.encoder.jsp` | `javax.servlet.jsp.api` | `javax.servlet.jsp:javax.servlet.jsp-api:2.2.1` | -| `owasp.encoder.jakarta` | `jakarta.servlet.jsp` | `jakarta.servlet.jsp:jakarta.servlet.jsp-api:3.0.0` | -| `owasp.encoder.esapi` | `esapi` | `org.owasp.esapi:esapi:2.7.0.0` | - -These dependencies are transitive in the module descriptors because their types -appear in the adapters' public APIs. The JSP and ESAPI dependencies are automatic -modules; use the original Maven artifact filenames so Java derives the module -names shown above. Servlet containers continue to provide the JSP APIs at runtime, -and classpath-based applications are unaffected. - -The ESAPI adapter's fixed dependency and tested compatibility policy are -documented in [esapi/README.md](esapi/README.md). - - -OSGi Bundles ------------- - -| JAR | Bundle-SymbolicName | Export-Package | Imports `org.owasp.encoder` | Imports API packages | -|---------------------|---------------------------------|--------------------------|-----------------------------|-------------------------------------------------------------| -| encoder | `org.owasp.encoder` | `org.owasp.encoder` | (none) | (none) | -| encoder-jsp | `org.owasp.encoder.jsp` | `org.owasp.encoder.tag` | `[1.5,2)` | `javax.servlet.jsp`, `javax.servlet.jsp.tagext`: `[2.0,3)` | -| encoder-jakarta-jsp | `org.owasp.encoder.jakarta-jsp` | `org.owasp.encoder.tag` | `[1.5,2)` | `jakarta.servlet.jsp`, `jakarta.servlet.jsp.tagext`: `[3.0,4)` | -| encoder-esapi | `org.owasp.encoder.esapi` | `org.owasp.encoder.esapi`| `[1.4.1,2)` | `org.owasp.esapi.*`: unversioned | - -The symbolic names are fixed; note that the Jakarta bundle's differs from its -`Automatic-Module-Name`. Core exports `org.owasp.encoder` at its release version. -The JSP and Jakarta tags require core 1.5 because they call `Encode.forJson`; the -ESAPI adapter only calls older methods, so its floor is the oldest supported core, -the 1.4.1 security release. Jakarta Pages 4 is not in the accepted range until -compatibility with it has been verified. ESAPI publishes no OSGi metadata: OSGi -users must wrap ESAPI and its dependencies as bundles themselves. The project's -tests supply the ESAPI packages from the framework host, which is not a statement -that upstream ESAPI supports OSGi. - -TagLib --------------------- - -| Lib | TagLib | -|---------------------|-----------------------------------------------------------------------------------------------| -| encoder-jakarta-jsp | <%@taglib prefix="e" uri="owasp.encoder.jakarta"%> | -| encoder-jsp | <%@taglib prefix="e" uri="https://www.owasp.org/index.php/OWASP_Java_Encoder_Project"%> | - -Every `Encode.forX(String)` context has a tag and an EL function in the advanced -taglib, except `forJava`: Java source generation is not a JSP output context. - -Migrating from forUri ---------------------- - -`Encode.forUri`, the `uri` context (`Encoders.URI`), `ForUriTag`, and the `forUri` -tag and EL function are deprecated. Percent-encoding a complete URI does not make an -untrusted URI safe: `forUri("javascript:alert(1)")` is returned unchanged. It also -always encodes `%`, so an already percent-encoded URI is double-encoded. - -- For an untrusted value inserted into a URL (a path segment, a query parameter name - or value, or a fragment), use `forUriComponent`: - - ```jsp - - ``` - -- For an entire untrusted URL, parse it with `java.net.URI`, allow-list its scheme - (for example `http` and `https`, rejecting a missing scheme unless relative URLs are - intended), enforce application-specific restrictions on its destination and - path, and then encode the whole value for the enclosing context. Parsing alone - does not establish safety: - - ```jsp - - ``` - -`forUri` is retained for compatibility in all 1.x releases. Whether 2.0 removes it is -tracked in [#142](https://github.com/OWASP/owasp-java-encoder/issues/142). - -The ESAPI adapter's `encodeForURL` changes separately in unreleased 1.5: it now -uses `forUriComponent`, escaping URL delimiters while retaining `%20` for spaces. -Pass raw component data, not a complete or already encoded URL. See the -[adapter migration and context contracts](esapi/README.md#url-encoding-migration-in-15-unreleased) -for differences from earlier adapter releases and ESAPI's reference form encoder. - -Development ------------ - -The OWASP Java Encoder project is a multi-module Maven project: - -```bash -$ ./mvnw verify +Use the javax identifier for a javax container. Tags use an empty body and a +required `value` attribute, for example `