|
| 1 | +Release notes for ESAPI 2.2.1.1 |
| 2 | + Release date: 2020-July-26 |
| 3 | + Project leaders: |
| 4 | + -Kevin W. Wall < [email protected]> |
| 5 | + |
| 6 | + |
| 7 | +Previous release: ESAPI 2.2.1.0, 2020-July-12 |
| 8 | + |
| 9 | + |
| 10 | +Executive Summary: Important Things to Note for this Release |
| 11 | +------------------------------------------------------------ |
| 12 | + |
| 13 | +This is a patch release to address GitHub issue #560. See that GitHub issue and |
| 14 | + |
| 15 | +Also special props to Bill Sempf for stepping up and volunteering to prepare the initial cut of these release notes. Had he not done so, this release either would not have release notes or it would have been delayed another 6 months while I procrastinated further with various distractions. (Squirrel!) |
| 16 | + |
| 17 | +================================================================================================================= |
| 18 | + |
| 19 | +Basic ESAPI facts |
| 20 | +----------------- |
| 21 | + |
| 22 | +ESAPI 2.2.1.0 release: |
| 23 | + 211 Java source files |
| 24 | + 4309 JUnit tests in 134 Java source files |
| 25 | + |
| 26 | +ESAPI 2.2.1.1 release: |
| 27 | + 211 Java source files |
| 28 | + 4312 JUnit tests in 134 Java source files |
| 29 | + |
| 30 | +39 GitHub Issues closed in this release |
| 31 | + |
| 32 | +Issue # GitHub Issue Title |
| 33 | +---------------------------------------------------------------------------------------------- |
| 34 | + |
| 35 | +560 - Could not initialize class org.owasp.esapi.logging.java.JavaLogFactory (ESAPI 2.2.1.0) |
| 36 | +561 - Update ESAPI-release-steps.odt to note how to do 'Release' on GitHub |
| 37 | +564 - Create release notes for 2.2.1.1 patch release |
| 38 | + |
| 39 | +----------------------------------------------------------------------------- |
| 40 | + |
| 41 | + Changes Requiring Special Attention |
| 42 | + |
| 43 | +----------------------------------------------------------------------------- |
| 44 | +As of ESAPI 2.2.1.0 (the previous release), the new default ESAPI logger is JUL (java.util.logging packages) and we have deprecated the use of Log4J 1.x because we now support SLF4J and Log4J 1.x is way past its end-of-life. We did not want to make SLF4J the default logger (at least not yet) as we did not want to have the default ESAPI use require additional dependencies. However, SLF4J is likely to be the future choice, at least once we start on ESAPI 3.0. A special shout-out to Jeremiah Stacey for making this possible by re-factoring much of the ESAPI logger code. Note, the straw that broke the proverbial camel's back was the announcement of CVE-2019-17571 (rated Critical), for which there is no fix available and likely will never be. |
| 45 | + |
| 46 | +However, if you try to juse the new ESAPI 2.2.1.0 logging you will notice that you need to change ESAPI.Logger and also possibly provide some other properties as well to get the logging behavior that you desire. |
| 47 | + |
| 48 | +To use ESAPI logging in ESAPI 2.2.1.0 (and later), you will need to set the ESAPI.Logger property to |
| 49 | + |
| 50 | + org.owasp.esapi.logging.java.JavaLogFactory - To use the new default, java.util.logging (JUL) |
| 51 | + org.owasp.esapi.logging.log4j.Log4JLogFactory - To use the end-of-life Log4J 1.x logger |
| 52 | + org.owasp.esapi.logging.slf4j.Slf4JLogFactory - To use the new (to release 2.2.0.0) SLF4J logger |
| 53 | + |
| 54 | +In addition, if you wish to use JUL for logging, you *MUST* supply an "esapi-java-logging.properties" file in your classpath. This file is included in the 'esapi-2.2.1.1-configuration.jar' file provided under the 'Assets' section of the GitHub Release at |
| 55 | + https://github.com/ESAPI/esapi-java-legacy/releases/esapi-2.2.1.1 |
| 56 | + |
| 57 | +Unfortunately, there was a logic error in the static initializer of JavaLogFactory (now fixed in this release) that caused a NullPointerException to be thrown so that the message about the missing "esapi-java-logging.properties" file was never seen. |
| 58 | + |
| 59 | +If you are using JavaLogFactory, you will also want to ensure that you have the following ESAPI logging properties set: |
| 60 | + # Set the application name if these logs are combined with other applications |
| 61 | + Logger.ApplicationName=ExampleApplication |
| 62 | + # If you use an HTML log viewer that does not properly HTML escape log data, you can set LogEncodingRequired to true |
| 63 | + Logger.LogEncodingRequired=false |
| 64 | + # Determines whether ESAPI should log the application name. This might be clutter in some single-server/single-app environments. |
| 65 | + Logger.LogApplicationName=true |
| 66 | + # Determines whether ESAPI should log the server IP and port. This might be clutter in some single-server environments. |
| 67 | + Logger.LogServerIP=true |
| 68 | + # LogFileName, the name of the logging file. Provide a full directory path (e.g., C:\\ESAPI\\ESAPI_logging_file) if you |
| 69 | + # want to place it in a specific directory. |
| 70 | + Logger.LogFileName=ESAPI_logging_file |
| 71 | + # MaxLogFileSize, the max size (in bytes) of a single log file before it cuts over to a new one (default is 10,000,000) |
| 72 | + Logger.MaxLogFileSize=10000000 |
| 73 | + # Determines whether ESAPI should log the user info. |
| 74 | + Logger.UserInfo=true |
| 75 | + # Determines whether ESAPI should log the session id and client IP. |
| 76 | + Logger.ClientInfo=true |
| 77 | + |
| 78 | +See GitHub issue #560 for additional details. |
| 79 | + |
| 80 | + |
| 81 | +Related to that aforemented Log4J 1.x CVE and how it affects ESAPI, be sure to read |
| 82 | + https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin2.pdf |
| 83 | +which describes CVE-2019-17571, a deserialization vulnerability in Log4J 1.2.17. ESAPI is *NOT* affected by this (even if you chose to use Log4J 1 as you default ESAPI logger). This security bulletin describes why this CVE is not exploitable as used by ESAPI. |
| 84 | + |
| 85 | + |
| 86 | +Finally, while ESAPI still supports JDK 7 (even though that too is way past end-of-life), the next ESAPI release will move to JDK 8 as the minimal baseline. (We already use Java 8 for development but still to Java 7 source and runtime compatibility.) |
| 87 | + |
| 88 | +----------------------------------------------------------------------------- |
| 89 | + |
| 90 | + Known Issues / Problems |
| 91 | + |
| 92 | +----------------------------------------------------------------------------- |
| 93 | +If you use Java 7 (the minimal Java baseline supported by ESAPI) and try to run 'mvn test' there is one test that fails. This test passes with Java 8. The failing test is: |
| 94 | + |
| 95 | + [ERROR] Tests run: 5, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.203 s |
| 96 | + <<< FAILURE! - in org.owasp.esapi.crypto.SecurityProviderLoaderTest |
| 97 | + [ERROR] org.owasp.esapi.crypto.SecurityProviderLoaderTest.testWithBouncyCastle |
| 98 | + Time elapsed: 0.116 s <<< FAILURE! |
| 99 | + java.lang.AssertionError: Encryption w/ Bouncy Castle failed with |
| 100 | + EncryptionException for preferred cipher transformation; exception was: |
| 101 | + org.owasp.esapi.errors.EncryptionException: Encryption failure (unavailable |
| 102 | + cipher requested) |
| 103 | + at |
| 104 | + org.owasp.esapi.crypto.SecurityProviderLoaderTest.testWithBouncyCastle(Security |
| 105 | + ProviderLoaderTest.java:133) |
| 106 | + |
| 107 | +I will spare you all the details and tell you that this has to do with Java 7 not being able to correctly parse the signed Bouncy Castle JCE provider jar. More details are available at: |
| 108 | + https://www.bouncycastle.org/latest_releases.html |
| 109 | +and |
| 110 | + https://github.com/bcgit/bc-java/issues/477 |
| 111 | +I am sure that there are ways of making Bouncy Castle work with Java 7, but since ESAPI does not rely on Bouncy Castle (it can use any compliant JCE provider), this should not be a problem. (It works fine with the default SunJCE provider.) If it is important to get the BC provider working with the ESAPI Encryptor and Java 7, then open a GitHub issue and we will take a deeper look at it and see if we can suggest something. |
| 112 | + |
| 113 | + |
| 114 | + |
| 115 | +Another problem is if you run 'mvn test' from the 'cmd' prompt (and possibly PowerShell as well), you will get intermittent failures (generally between 10-25% of the time) at arbitrary spots. If you run it again without any changes it will work fine without any failures. We have discovered that it doesn't seem to fail if you run the tests from an IDE like Eclipse or if you redirect both stdout and stderr to a file; e.g., |
| 116 | + |
| 117 | + C:\code\esapi-java-legacy> mvn test >testoutput.txt 2>&1 |
| 118 | + |
| 119 | +We do not know the reason for these failures, but only that we have observed them on Windows 10. If you see this error, please do NOT report it as a GitHub issue unless you know a fix for it. |
| 120 | + |
| 121 | +----------------------------------------------------------------------------- |
| 122 | + |
| 123 | + Other changes in this release, some of which not tracked via GitHub issues |
| 124 | + |
| 125 | +----------------------------------------------------------------------------- |
| 126 | + |
| 127 | +* Updates to README.md fileg |
| 128 | +* Minor Javadoc fixes to org.owasp.esapi.Encoder |
| 129 | +* Fixes / cleanup to 2.2.1.0 release notes (documentation/esapi4java-core-2.2.1.0-release-notes.txt) |
| 130 | + |
| 131 | +----------------------------------------------------------------------------- |
| 132 | + |
| 133 | +Developer Activity Report (Changes between release 2.2.1.0 and 2.2.1.1, i.e., between 2020-07-12 and 2020-07-26) |
| 134 | +Generated manually (this time) -- all errors are the fault of kwwall and his inability to do simple arithmetic. |
| 135 | + |
| 136 | +Developer Total Total Number # Merged |
| 137 | +(GitHub ID) commits of Files Changed PRs |
| 138 | +======================================================== |
| 139 | +jeremiahjstacey 5 5 1 |
| 140 | +kwwall 67 64 8 |
| 141 | +======================================================== |
| 142 | + Total: 21 |
| 143 | + |
| 144 | + |
| 145 | +----------------------------------------------------------------------------- |
| 146 | + |
| 147 | + |
| 148 | +2 Closed PRs merged since 2.2.1.0 release (those rejected not listed) |
| 149 | +====================================================================== |
| 150 | +PR# GitHub ID Description |
| 151 | +---------------------------------------------------------------------- |
| 152 | +559 -- synk-bot -- Upgrade com.github.spotbugs:spotbugs-annotations from 4.0.4 to 4.0.5 |
| 153 | +562 -- jeremiahjstacey -- Issue #560 JUL fixes |
| 154 | + |
| 155 | +CHANGELOG: Create your own. May I suggest: |
| 156 | + |
| 157 | + git log --since=2020-07-13 --reverse --pretty=medium |
| 158 | + |
| 159 | + which will show all the commits since just after the last (2.2.1.0) release. |
| 160 | + |
| 161 | +----------------------------------------------------------------------------- |
| 162 | + |
| 163 | +Direct and Transitive Runtime and Test Dependencies: |
| 164 | + |
| 165 | + $ mvn dependency:tree |
| 166 | + [INFO] Scanning for projects... |
| 167 | + [INFO] |
| 168 | + [INFO] -----------------------< org.owasp.esapi:esapi >------------------------ |
| 169 | + [INFO] Building ESAPI 2.2.1.1 |
| 170 | + [INFO] --------------------------------[ jar ]--------------------------------- |
| 171 | + [INFO] |
| 172 | + [INFO] --- maven-dependency-plugin:3.1.2:tree (default-cli) @ esapi --- |
| 173 | + [INFO] org.owasp.esapi:esapi:jar:2.2.1.1 |
| 174 | + [INFO] +- javax.servlet:javax.servlet-api:jar:3.0.1:provided |
| 175 | + [INFO] +- javax.servlet.jsp:javax.servlet.jsp-api:jar:2.3.3:provided |
| 176 | + [INFO] +- com.io7m.xom:xom:jar:1.2.10:compile |
| 177 | + [INFO] +- commons-beanutils:commons-beanutils:jar:1.9.4:compile |
| 178 | + [INFO] | +- commons-logging:commons-logging:jar:1.2:compile |
| 179 | + [INFO] | \- commons-collections:commons-collections:jar:3.2.2:compile |
| 180 | + [INFO] +- commons-configuration:commons-configuration:jar:1.10:compile |
| 181 | + [INFO] +- commons-lang:commons-lang:jar:2.6:compile |
| 182 | + [INFO] +- commons-fileupload:commons-fileupload:jar:1.3.3:compile |
| 183 | + [INFO] +- log4j:log4j:jar:1.2.17:compile |
| 184 | + [INFO] +- org.apache.commons:commons-collections4:jar:4.2:compile |
| 185 | + [INFO] +- org.apache-extras.beanshell:bsh:jar:2.0b6:compile |
| 186 | + [INFO] +- org.owasp.antisamy:antisamy:jar:1.5.10:compile |
| 187 | + [INFO] | +- net.sourceforge.nekohtml:nekohtml:jar:1.9.22:compile |
| 188 | + [INFO] | +- org.apache.httpcomponents:httpclient:jar:4.5.12:compile |
| 189 | + [INFO] | | \- org.apache.httpcomponents:httpcore:jar:4.4.13:compile |
| 190 | + [INFO] | \- commons-codec:commons-codec:jar:1.14:compile |
| 191 | + [INFO] +- org.slf4j:slf4j-api:jar:1.7.30:compile |
| 192 | + [INFO] +- commons-io:commons-io:jar:2.6:compile |
| 193 | + [INFO] +- org.apache.xmlgraphics:batik-css:jar:1.13:compile |
| 194 | + [INFO] | +- org.apache.xmlgraphics:batik-shared-resources:jar:1.13:compile |
| 195 | + [INFO] | +- org.apache.xmlgraphics:batik-util:jar:1.13:compile |
| 196 | + [INFO] | | +- org.apache.xmlgraphics:batik-constants:jar:1.13:compile |
| 197 | + [INFO] | | \- org.apache.xmlgraphics:batik-i18n:jar:1.13:compile |
| 198 | + [INFO] | +- org.apache.xmlgraphics:xmlgraphics-commons:jar:2.4:compile |
| 199 | + [INFO] | \- xml-apis:xml-apis-ext:jar:1.3.04:compile |
| 200 | + [INFO] +- xalan:xalan:jar:2.7.2:compile |
| 201 | + [INFO] | \- xalan:serializer:jar:2.7.2:compile |
| 202 | + [INFO] +- xerces:xercesImpl:jar:2.12.0:compile |
| 203 | + [INFO] +- xml-apis:xml-apis:jar:1.4.01:compile |
| 204 | + [INFO] +- com.github.spotbugs:spotbugs-annotations:jar:4.0.5:compile (optional) |
| 205 | + [INFO] | \- com.google.code.findbugs:jsr305:jar:3.0.2:compile (optional) |
| 206 | + [INFO] +- net.jcip:jcip-annotations:jar:1.0:compile (optional) |
| 207 | + [INFO] +- junit:junit:jar:4.13:test |
| 208 | + [INFO] | \- org.hamcrest:hamcrest-core:jar:1.3:test |
| 209 | + [INFO] +- org.bouncycastle:bcprov-jdk15on:jar:1.65.01:test |
| 210 | + [INFO] +- org.powermock:powermock-api-mockito2:jar:2.0.7:test |
| 211 | + [INFO] | \- org.powermock:powermock-api-support:jar:2.0.7:test |
| 212 | + [INFO] | \- org.powermock:powermock-core:jar:2.0.7:test |
| 213 | + [INFO] +- org.javassist:javassist:jar:3.25.0-GA:test |
| 214 | + [INFO] +- org.mockito:mockito-core:jar:2.28.2:test |
| 215 | + [INFO] | +- net.bytebuddy:byte-buddy:jar:1.9.10:test |
| 216 | + [INFO] | +- net.bytebuddy:byte-buddy-agent:jar:1.9.10:test |
| 217 | + [INFO] | \- org.objenesis:objenesis:jar:2.6:test |
| 218 | + [INFO] +- org.powermock:powermock-module-junit4:jar:2.0.7:test |
| 219 | + [INFO] | \- org.powermock:powermock-module-junit4-common:jar:2.0.7:test |
| 220 | + [INFO] +- org.powermock:powermock-reflect:jar:2.0.7:test |
| 221 | + [INFO] +- org.openjdk.jmh:jmh-core:jar:1.23:test |
| 222 | + [INFO] | +- net.sf.jopt-simple:jopt-simple:jar:4.6:test |
| 223 | + [INFO] | \- org.apache.commons:commons-math3:jar:3.2:test |
| 224 | + [INFO] \- org.openjdk.jmh:jmh-generator-annprocess:jar:1.23:test |
| 225 | + [INFO] ------------------------------------------------------------------------ |
| 226 | + [INFO] BUILD SUCCESS |
| 227 | + [INFO] ------------------------------------------------------------------------ |
| 228 | + |
| 229 | +----------------------------------------------------------------------------- |
| 230 | + |
| 231 | +Acknowledgments: |
| 232 | + |
| 233 | +elangoravi for bringing GitHub issue #560 to our attention. This is one where we thought the workaround instructions was harder than just trying to fix it and thus we were encouraged to release a patch. |
| 234 | + |
| 235 | +A special thanks to the ESAPI community from the ESAPI project co-leaders: |
| 236 | + Kevin W. Wall (kwwall) <== The irresponsible party for these release notes! |
| 237 | + Matt Seil (xeno6696) |
0 commit comments