Skip to content

Commit 7d4dd5a

Browse files
authored
Preparation for ESAPI 2.5.3.0 release (#809)
* Add 'noopenerAndNoreferrerAnchors' AntiSamy directive for anchor tags. * Change ESAPI's defaults for digital signature from 1024-bit SHA1withDSA to 2048-bit SHA256withDSA. * Change ESAPI's default key size for digital signature from 1024-bits to 2048-bits. * Extensive Javadoc improvements. * Changes to update to AntiSamy 1.7.4 and other minor changes. * Revise ESAPI's deprecation policy. * Deprecate both isValidSafeHTML methods and note they will be removed 1 year after the official ESAPI 2.5.3.0 release. * Revise JUnit tests using Validator.isValidSafeHTML. * Fix Javadoc tag. * Another Javadoc tag fix. * Last Javadoc fix. It would be nice if 'mvn site' reported all the errors at once. * Delete obsolete script. Replaced with 'newReleaseNotes.sh' and Maven. * Remove obsolete script 'esapi-release.sh'. * Update 2.5.2.0 to 2.5.3.0 * Add some comments regarding building dependency tree. * Add new file for 2.5.3.0 release. * DRAFT of ESAPI 2.5.3.0 release notes.
1 parent 245587a commit 7d4dd5a

17 files changed

+700
-325
lines changed

README.md

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Development for the "next generation" of ESAPI (starting with ESAPI 3.0), will b
4545
GitHub repository at [https://github.com/ESAPI/esapi-java](https://github.com/ESAPI/esapi-java).
4646

4747
**IMPORTANT NOTES:**
48-
* The default branch for ESAPI legacy is the 'develop' branch (rather than the 'main' (formerly 'master') branch), where future development, bug fixes, etc. are now being done. The 'main' branch is now marked as "protected"; it reflects the latest stable ESAPI release (2.5.2.0 as of this date). Note that this change of making the 'develop' branch the default may affect any pull requests that you were intending to make.
48+
* The default branch for ESAPI legacy is the 'develop' branch (rather than the 'main' (formerly 'master') branch), where future development, bug fixes, etc. are now being done. The 'main' branch is now marked as "protected"; it reflects the latest stable ESAPI release (2.5.3.0 as of this date). Note that this change of making the 'develop' branch the default may affect any pull requests that you were intending to make.
4949
* Also, the *minimal* baseline Java version to use ESAPI is now Java 8. (This was changed from Java 7 during the 2.4.0.0 release.)
5050
* Support was dropped for Log4J 1 during ESAPI 2.5.0.0 release. If you need it, configure it via SLF4J. See the
5151
[2.5.0.0 release notes](https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.5.0.0-release-notes.txt)
@@ -79,7 +79,7 @@ link to the specific release notes.
7979
Starting with release 2.4.0.0, Java 8 or later is required.
8080

8181
# Locating ESAPI Jar files
82-
The [latest ESAPI release](https://github.com/ESAPI/esapi-java-legacy/releases/latest) is 2.5.2.0.
82+
The [latest ESAPI release](https://github.com/ESAPI/esapi-java-legacy/releases/latest) is 2.5.3.0.
8383
All the *regular* ESAPI jars, with the exception of the ESAPI configuration
8484
jar (i.e., esapi-2.#.#.#-configuration.jar) and its associated detached
8585
GPG signature, are available from Maven Central. The ESAPI configuration
@@ -101,6 +101,15 @@ to be using such classes directly in your code. At the ESAPI team's discretion,
101101
it will also not apply for any known exploitable vulnerabilities for which
102102
no available workaround exists.
103103

104+
## Exceptions to Deprecation Policy
105+
We will make some exceptions to the normal 2 year period. In particular, in the
106+
cases were we believe that keeping a specific deprecated class or method around
107+
can introduce security issues (generally because many of you have a habit of
108+
completely ignoring deprecation warnings), we sometimes will shorten that 2 year
109+
period. When we decide to do that, we will announce that as part of the
110+
deprecation message.
111+
112+
## Log4J 1.x Removal
104113
**IMPORTANT NOTES:** As of ESAPI 2.5.0.0, all the Log4J 1.x related code
105114
has been removed from the ESAPI code base (with the exception of some
106115
references in documentation). If you must, you still should be able to

configuration/esapi/ESAPI.properties

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#
22
# OWASP Enterprise Security API (ESAPI) Properties file -- PRODUCTION Version
33
#
4-
# This file is part of the Open Web Application Security Project (OWASP)
4+
# This file is part of the Open Worldwide Application Security Project (OWASP)
55
# Enterprise Security API (ESAPI) project. For details, please see
66
# https://owasp.org/www-project-enterprise-security-api/
77
#
@@ -275,8 +275,14 @@ Encryptor.PlainText.overwrite=true
275275

276276
Encryptor.HashAlgorithm=SHA-512
277277
Encryptor.HashIterations=1024
278-
Encryptor.DigitalSignatureAlgorithm=SHA1withDSA
279-
Encryptor.DigitalSignatureKeyLength=1024
278+
279+
# Was 'SHA1withDSA', but that won't support 2048 key sizes. Change back for
280+
# backward compatibility.
281+
Encryptor.DigitalSignatureAlgorithm=SHA256withDSA
282+
283+
# Was 1024. Change this back if you require backward compatibility.
284+
Encryptor.DigitalSignatureKeyLength=2048
285+
# SHA1 is fine as a CSRNG; no need to use anything else.
280286
Encryptor.RandomAlgorithm=SHA1PRNG
281287
Encryptor.CharacterEncoding=UTF-8
282288

configuration/esapi/antisamy-esapi.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Slashdot allowed tags taken from "Reply" page:
1818
<directive name="omitDoctypeDeclaration" value="true"/>
1919
<directive name="maxInputSize" value="500000"/>
2020
<directive name="embedStyleSheets" value="false"/>
21+
<directive name="noopenerAndNoreferrerAnchors" value="true" />
2122
</directives>
2223

2324

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
@@@@ IMPORTANT: Be sure to 1) save in DOS text format, and 2) Delete this line and others starting with @@@@
2+
@@@@ Edit this file in vim with :set tw=0
3+
@@@@ Meant to be used with scripts/newReleaseNotes.sh and the 'vars.*' scripts there.
4+
@@@@ There are specific references to ESAPI 2.5.0.0 and other old releases in this file. Do NOT change the version #s. They are there for a reason.
5+
Release notes for ESAPI 2.5.3.0
6+
Release date: 2023-11-22
7+
Project leaders:
8+
-Kevin W. Wall <[email protected]>
9+
-Matt Seil <[email protected]>
10+
11+
Previous release: ESAPI 2.5.2.0, 2023-04-12
12+
13+
14+
Executive Summary: Important Things to Note for this Release
15+
------------------------------------------------------------
16+
@@@@ View previous release notes to see examples of what to put here. This is typical. YMMV.
17+
@@@@ Obviously, you should summarize any major changes / new features here.
18+
This is a patch release with the primary intent of updating some dependencies, some with known vulnerabilities. Details follow.
19+
@@@@ Provide a sentence or to
20+
* This is a patch release, with the primary intent of updating ESAPI's AntiSamy dependency from 1.7.3 to 1.7.4. AntiSamy 1.7.4 was released to address an XSS vulnerability in AntiSamy (CVE-2023-43643). Testing ESAPI's use of AntiSamy along with ESAPI's default antsamy-esapi.xml AntiSamy policy file, shows there is no exploitable path of this CVE via ESAPI. This is because ESAPI's AntiSamy policy file is ultra-strict. (Of course, YMMV if you are not using the default AntiSamy policy file or are customized it to disable the 'preserveComments' directive.)
21+
* We have deprecated both of ESAPI's Validator.isValidSafeHTML interfaces, as we discovered that they cannot be guaranteed safe. Note that we intend to REMOVE both of these interfaces one year after the ESAPI 2.5.3.0 release. For more details, see GitHub Security Advisory https://github.com/ESAPI/esapi-java-legacy/security/advisories/GHSA-r68h-jhhj-9jvm. There is also an accompanying "ESAPI Security Bulletin 12" (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin12.pdf). The Security Bulletin explains why we did not submit this as a CVE as well as explains some potential workarounds that may work for you.
22+
* Changed ESAPI so that the default RSA modulus length (sometimes referred to as the key size) from 1024-bits to 2048-bits. Note that if you are using an old version of ESAPI.properties file prior to 2.5.3.0 and are using any of the Encryptor interfaces that directly or indirectly use digital signatures (i.e., sign, verifySignature, seal, unseal, verifySeal), you may wish to consider updating properties:
23+
Encryptor.DigitalSignatureAlgorithm=SHA256withDSA # The old SHA1withDSA doesn't support 2048-bit RSA modulus length
24+
Encryptor.DigitalSignatureKeyLength=2048
25+
Note that if you have persisted previous digital signatures that you must continue to verify, you will have to regenerate them.
26+
@@@@ NOTE: This might be reserved for a 2.6.0.0 release, in which case the next line should be removed.
27+
* Thanks to a PR by @jcputney (PR #799), I have attempted to upload additional artifacts to Maven Central that will be a transformed jar suitable for use with the new 'jakarata.servlet' changes for Jakarata EE 9 and later. (Previously, 'javax.servlet' was the name space). Because we are still supporting JDK 8 at this point, we still need to support the 'javax.servlet' namespace as well. In addition to the standard jar artifacts, there should be a new esapi-<release>-jakarta.jar (which uses 'jakarta.servlet' instead of 'javax.servlet' namespace) as well as corresponding *-javadoc.jar and *-sources.jar files. I am not sure it will work as we have no tests for it, but looing at the binaries, it seems like it should.
28+
For additional details, see:
29+
https://github.com/ESAPI/esapi-java-legacy/pull/799
30+
https://github.com/ESAPI/esapi-java-legacy/discussions/768
31+
32+
Notes if you are not updating from the immediate previous release. release 2.5.2.0:
33+
* You need to read through the series of release notes FIRST, going in order.
34+
* For example, if you were updating from an older ESAPI release (say, 2.3.0.0), you should go back and FIRST read all the subsequent release notes in turn. For instance, if you are currently on release 2.3.0.0 and upgrading to (say) release 2.x.y.z, you should MINIMALLY read the sections "Changes Requiring Special Attention" in each of the subsequent release notes. So, going from release 2.3.0.0 to 2.x.y.z, you should in turn, read:
35+
36+
esapi4java-core-2.4.0.0-release-notes.txt
37+
esapi4java-core-2.5.0.0-release-notes.txt
38+
esapi4java-core-2.5.1.0-release-notes.txt
39+
esapi4java-core-2.5.2.0-release-notes.txt
40+
...etc., up through the current set of release notes...
41+
esapi4java-core-2.x.y.z-release-notes.txt
42+
43+
in that order. YOU HAVE BEEN WARNED!!! (These release notes are too large to put all this in a given document; very few read them thoroughly as it is.)
44+
45+
If your SCA tool is reporting any CVE from a direct or transitive dependency in ESAPI, before reporting it as an GitHub issue, please make sure that you review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md. Please email us or contact us in our GitHub Discussions page if you have questions about this. See also the SECURITY.md file to report any security issues with ESAPI.
46+
47+
You are encouraged to review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md and email us or contact us in our GitHub Discussions page if you have questions.
48+
49+
50+
=================================================================================================================
51+
52+
Basic ESAPI facts
53+
-----------------
54+
55+
ESAPI 2.5.2.0 release:
56+
207 Java source files
57+
4293 JUnit tests in 131 Java source files (0 tests skipped, 1 commented out)
58+
59+
ESAPI 2.5.3.0 release:
60+
207 Java source files
61+
4293 JUnit tests in 131 Java source files (0 failures, 0 errors, 0 tests skipped)
62+
63+
8 GitHub Issues closed in this release, including those we've decided not to fix (marked 'wontfix' and 'falsepositive').
64+
(Reference: https://github.com/ESAPI/esapi-java-legacy/issues?q=is%3Aissue+state%3Aclosed+updated%3A%3E%3D2023-04-12)
65+
66+
Issue # GitHub Issue Title
67+
----------------------------------------------------------------------------------------------
68+
@@@@ Capture issue #s and 1 line desription from above GitHub url
69+
@@@@ Insert here and massage until it looks pretty. Recommend alignment with spaces instead of tabs.
70+
560 Could not initialize class org.owasp.esapi.logging.java.JavaLogFactory (ESAPI 2.2.1.0)
71+
760 Could not initialize class org. Owasp. Esapi. Reference. DefaultValidator
72+
775 Add documenttion to CONTRIBUTING-TO-ESAPI.txt to mention signed commits are now required.
73+
792 хз
74+
796 Logs printed using println() are always printed and no option to disable them.
75+
798 Insecure default signature key length
76+
805 Does esapi-java-legacy support jDK17
77+
808 Fix typo in comment in validation.properties files
78+
812 Fix Encoder.encodeForLDAP and Encoder.encodeForDN so they are strictly conformant with Section 3 of RFC 4515
79+
80+
-----------------------------------------------------------------------------
81+
82+
Changes Requiring Special Attention
83+
84+
-----------------------------------------------------------------------------
85+
@@@@ NOTE any special notes here. Probably leave this one, but I would suggest noting additions BEFORE this.
86+
87+
Important JDK Support Announcement
88+
* ESAPI 2.3.0.0 was the last Java release to support Java 7. ESAPI 2.4.0 requires using Java 8 or later. See the ESAPI 2.4.0.0 release notes (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.4.0.0-release-notes.txt) for details as to the reason.
89+
- This means if your project requires Java 7, you must use ESAPI 2.3.0.0 or earlier.
90+
91+
Important ESAPI Logging Changes
92+
93+
* Since ESAPI 2.5.0.0, support for logging directly via Log4J 1 has been removed. (This was two years after it haveing first been deprecated.) Thus, you only choice of ESAPI logging are
94+
- java.util.logging (JUL), which as been the default since ESAPI 2.2.1.0.
95+
* Set ESAPI.Logger=org.owasp.esapi.logging.java.JavaLogFactory in your ESAPI.properties file.
96+
- SLF4J (which your choice of supported SLF4J logging implemmentation)
97+
* Set ESAPI.Logger=org.owasp.esapi.logging.slf4j.Slf4JLogFactory in your ESAPI.properties file.
98+
* Logger configuration notes - If you are migrating from prior to ESAPI 2.2.1.1, you will need to update your ESAPI.properties file as logging-related configuration as per the ESAPI 2.2.1.1 release notes, which may be found at:
99+
https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.2.1.1-release-notes.txt#L39-L78
100+
101+
If you use ESAPI 2.5.0.0 or later, you will get an ClassNotFoundException as the root cause if you still have your ESAPI.Logger property set to use Log4J because the org.owasp.esapi.logger.log4j.Log4JFactory class has been completely removed from the ESAPI jar. If you are dead set on continuing to use Log4J 1, you ought to be able to do so via SLF4J. The set up for Log4J 1 (which has not be tested), should be similar to configure ESAPI to use SLF4J with Log4J 2 as described here:
102+
https://github.com/ESAPI/esapi-java-legacy/wiki/Using-ESAPI-with-SLF4J#slf4j-using-log4j-2x
103+
104+
-----------------------------------------------------------------------------
105+
106+
Remaining Known Issues / Problems
107+
108+
-----------------------------------------------------------------------------
109+
The effect of upgrade to AntiSamy 1.7.4 in ESAPI 2.5.3.0 can result in ESAPI's Validator.getValidSafeHTML returning a different cleansed (i.e., sanitized) string than previous versions of ESAPI which used earlier versions of AntiSamy did. There presently is no concern for alarm as all these observed different sanitized strings returned by AntiSamy 1.7.4 still all appear to be "safe"; they are just different than before. However, as a result, this could break any regression tests that you previously had that involved ESAPI's Validator.getValidSafeHTML. See https://github.com/nahsra/antisamy/issues/389 and https://github.com/nahsra/antisamy/pull/388 for additional details.
110+
111+
-----------------------------------------------------------------------------
112+
113+
Other changes in this release, some of which not tracked via GitHub issues
114+
115+
-----------------------------------------------------------------------------
116+
117+
* Minor updates to README.md file with respect to version information.
118+
119+
-----------------------------------------------------------------------------
120+
121+
Developer Activity Report (Changes between release 2.5.2.0 and 2.5.3.0, i.e., between 2023-04-12 and 2023-11-22)
122+
Generated manually (this time) -- all errors are the fault of kwwall and his inability to do simple arithmetic.
123+
124+
@@@@
125+
@@@@ This section needs to be manually updated.
126+
@@@@ See file:///home/wallk/work/esapi-work/kww-2.5.3.0-prep/target/site/dev-activity.html for assistance.
127+
@@@@
128+
Developer Total Total Number # Merged
129+
(GitHub ID) commits of Files Changed PRs
130+
========================================================
131+
kwwall 36 37 2
132+
noloader 6 12 3
133+
preetgami 1 1 1
134+
robstoll 2 2 1
135+
jcputney 1 1 1
136+
========================================================
137+
Total PRs: 8
138+
139+
-----------------------------------------------------------------------------
140+
141+
CHANGELOG: Create your own. May I suggest:
142+
143+
git log --stat --since=2023-04-12 --reverse --pretty=medium
144+
145+
which will show all the commits since just after the previous (2.5.2.0) release.
146+
147+
Alternately, you can download the most recent ESAPI source and run
148+
149+
mvn site
150+
151+
which will create a CHANGELOG file named 'target/site/changelog.html'
152+
153+
154+
-----------------------------------------------------------------------------
155+
156+
Direct and Transitive Runtime and Test Dependencies:
157+
158+
$ mvn -B dependency:tree
159+
@@@@ Include output from 'mvn -B dependency:tree' here
160+
@@@@ TODO _after_ running:
161+
@@@@ mvn -U versions:display-plugin-updates
162+
@@@@ mvn -U versions:display-dependency-updates
163+
@@@@ mvn -U versions:display-property-updates
164+
165+
-----------------------------------------------------------------------------
166+
167+
@@@@ Review these notes, especially the reference to the AntiSamy version information.
168+
Acknowledgments:
169+
Thanks to @noloader, @preetgami, and @jcputney for submitting PRs to help move ESAPI forward. And thanks to Matt Seil, Jeremiah Stacey, and all the ESAPI users who make this worthwhile. This is for you.
170+
171+
A special thanks to the ESAPI community from the ESAPI project co-leaders:
172+
Kevin W. Wall (kwwall) <== The irresponsible party for these release notes!
173+
Matt Seil (xeno6696)

0 commit comments

Comments
 (0)