OWASP Java Encoder Project

Contextual Output Encoding is a computer programming technique necessary to stop Cross-Site Scripting. This project is a Java 8+ simple-to-use drop-in high-performance encoder class with little baggage.

For more detailed documentation on the OWASP Java Encoder please visit https://owasp.org/www-project-java-encoder/.

Project Leaders

• Jim Manico
• Jeremy Long

See MAINTAINERS.md for responsibilities, signing-key custody, and recovery readiness.

Start using the OWASP Java Encoders

Maven Central publication is pending. Version 1.4.1 is available as signed artifacts from the GitHub security release. Until Central publication completes, download and verify those artifacts and install them in your local or organizational Maven repository; the dependency examples below require that installation. Maven Central 1.4.0 remains affected.

You can download the core library from Maven Central.

JSP tags and EL functions are also available from Maven Central:

• encoder-jakarta-jsp - Jakarta Servlet 5.0+
• encoder-jsp - legacy javax.servlet API

The jars are also available in Central:

<dependency>
    <groupId>org.owasp.encoder</groupId>
    <artifactId>encoder</artifactId>
    <version>1.4.1</version>
</dependency>

<!-- using Servlet Spec 5 in the jakarta.servlet package use: -->
<dependency>
    <groupId>org.owasp.encoder</groupId>
    <artifactId>encoder-jakarta-jsp</artifactId>
    <version>1.4.1</version>
</dependency>

<!-- using the Legacy Servlet Spec in the javax.servlet package use: -->
<dependency>
    <groupId>org.owasp.encoder</groupId>
    <artifactId>encoder-jsp</artifactId>
    <version>1.4.1</version>
</dependency>

Quick Overview

The OWASP Java Encoder library is intended for quick contextual encoding with very little overhead, either in performance or usage. To get started, add the encoder dependency shown above and import org.owasp.encoder.Encode.

Example usage:

PrintWriter out = ...;
out.println("<textarea>" + Encode.forHtml(userData) + "</textarea>");

Please look at the javadoc for Encode to see the variety of contexts for which you can encode.

Happy Encoding!

Security

Please report suspected vulnerabilities privately. See SECURITY.md for the reporting channels, supported versions, and scope.

Building

Use JDK 17 to build, package, and test the project. The 1.x libraries retain a Java 8 API and bytecode baseline (--release 8); test applications and servlet containers can require newer Java versions. Packaged consumers run in CI on Java 8, 11, 17, 21, and 25. See runtime support and compatibility checks for per-artifact requirements, fixture scope, and advisory newer-JDK builds. If a future javac removes --release 8, a runtime baseline change requires a future-major-version decision; it does not change the 1.x baseline. Simply run:

mvn package

To validate that the Jakarta JSP tags and EL functions work correctly, run the integration test:

mvn verify -PtestJakarta

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.

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"%>

Development

The OWASP Java Encoder project is a multi-module Maven project:

$ mvn package

See RELEASING.md for signing, Maven Central publication, and release verification.

When changing the version, update the root pom.xml, the <parent> version in each module POM, and encoder.version in jakarta-test/pom.xml. CI fails if jakarta-test would test a different encoder-jakarta-jsp version than the one being built. When publishing a release, also update the supported versions in SECURITY.md.

News

Unreleased - 1.5.0

Development builds use 1.5.0-SNAPSHOT; this is not a published release.

• feat: all four forJavaScript* methods encode dollar sign ($) as \x24, backtick as \x60, and opening brace ({) as \x7b #129. Escaping { prevents input after a trusted $ from completing ${...}. Encoded output now supports literal text in ordinary (untagged) template literals as well as single- and double-quoted strings. This changes the encoded output while preserving its decoded JavaScript string value. Tagged templates (including String.raw), ${...} expression bodies, JSON, and script URLs are unsupported; each method's HTML context restrictions still apply.
• fix: all four forJavaScript* methods escape unpaired UTF-16 surrogates as \uXXXX, preserving their JavaScript string values through UTF-8 serialization #135, and escape DEL/C1 controls (U+007F to U+009F) as \xNN #163. Valid surrogate pairs and other non-ASCII text remain unescaped except U+2028/U+2029. These are output-fidelity changes; NEL was already ordinary JavaScript string data.
• feat: add Encode.forJson String/Writer methods, the json encoder context, and forJson tags and EL functions in both JSP and Jakarta tag libraries #145. The caller supplies double quotes. Output uses RFC 8259 string escapes and also escapes HTML script delimiters. Java null becomes the text null (the JSON string "null" when quoted); unpaired surrogates use Unicode escapes and may not interoperate with every JSON consumer. Prefer a serializer for complete JSON documents. The ESAPI adapter retains its existing JSON delegation and null behavior.
• fix: forHtmlUnquotedAttribute now replaces U+0085 (NEL) with a hyphen like the other C1 control characters, instead of emitting …, which HTML5 parsers decode as U+2026 #136.
• fix: the XML 1.1 encoders (forXml11, forXml11Content, forXml11Attribute) now encode U+0085 (NEL) as … and U+2028 (line separator) as 
, so they are not normalized to a line feed #136.
• maintenance: clarify output-context contracts and expand XML 1.1 tests, fix clean reactor compilation, and remove the obsolete benchmark profile.

1.4.1 Security Release

Upgrade all OWASP Java Encoder dependencies to 1.4.1. This release fixes three security issues in CSS string encoding and EncodedWriter buffer handling. See the release notes for affected entry points, compatibility details, and verification instructions.

2025-11-17 - 1.4.0 Release

The team is happy to announce that version 1.4.0 has been released!

• feat: add XML 1.1 encoding support #88.

2024-08-20 - 1.3.1 Release

The team is happy to announce that version 1.3.1 has been released!

• fix: add OSGi related entries in the MANIFEST.MF file #82.
• fix: java.lang.NoSuchMethodError when running on Java 8 #80.

2024-08-02 - 1.3.0 Release

The team is happy to announce that version 1.3.0 has been released!

• Minimum JDK Requirement is now Java 8
  • Requires Java 17 to build due to test case dependencies.
• Adds Java 9 Module name via Multi-Release Jars #77.
• Fixed compilation errors with the ESAPI Thunk #76.
• Adds support for Servlet Spec 5 using the jakarta.servlet.* #75.
  • taglib : <%@taglib prefix="e" uri="owasp.encoder.jakarta"%>

2020-11-08 - 1.2.3 Release

The team is happy to announce that version 1.2.3 has been released!

• Update to make the manifest OSGi-compliant #39.
• Update to support ESAPI 2.2 and later #37.

2018-09-14 - 1.2.2 Release

The team is happy to announce that version 1.2.2 has been released!

• This is a minor release fixing documentation and licensing issues.

2017-02-19 - 1.2.1 Release

The team is happy to announce that version 1.2.1 has been released!

• The CDATA Encoder was modified so that it does not emit intermediate characters between adjacent CDATA sections.
• The documentation on gh-pages has been improved.

2015-04-12 - 1.2 Release on GitHub

OWASP Java Encoder has been moved to GitHub. Version 1.2 was also released!

2014-03-31 - Documentation updated

Please visit https://owasp.org/www-project-java-encoder/ to see detailed documentation and examples for each API.

2014-01-30 - Version 1.1.1 released

We're happy to announce that version 1.1.1 has been released. Along with an important bug fix, we added ESAPI integration to replace the legacy ESAPI encoders with the OWASP Java Encoder.

2013-02-14 - Version 1.1 released

We're happy to announce that version 1.1 has been released. Along with a few minor encoding enhancements, we improved performance, and added a JSP tag and function library.