Merge pull request ESAPI#487 from kwwall/master

Master branch updates for ESAPI-2.2.0.0-RC2

Author: xeno6696

CONTRIBUTING-TO-ESAPI.txt

@@ -69,7 +69,8 @@ Steps to work with ESAPI:
        forked repo created in previous step)
     3. Create a new branch to work on an issue. I usually name the branch
        'issue-#' where '#' is the GitHub issue # is will be working on, but
-       you can call it whatever.
+       you can call it whatever. E.g.,
+            git checkout -b issue-#
     4. Work on the GitHub issue on this newly created issue-# branch.
     5. Make sure everything builds correctly and all the JUnit tests pass
        ('mvn test'). [Note: On occasion, there may be a failure in

README.md

@@ -42,7 +42,7 @@ When reporting an issue, please be clear and try to ensure that the ESAPI develo
 ### Find an Issue?
 If you have found a bug, then create an issue on the esapi-legacy-java repo: https://github.com/ESAPI/esapi-java-legacy/issues
 
-NOTE: Please do NOT use GitHub issues to ask questions about ESAPI. If you wish to do this, post to either of the 2 mailing lists found at the bottom of this page. If we find questions as GitHub issues, we simply will close them and direct you to do this anyhow.
+NOTE: Please do NOT use GitHub issues to ask questions about ESAPI. If you wish to do this, post to either of the 2 mailing lists (now on Google Groups) found at the bottom of this page. If we find questions as GitHub issues, we simply will close them and direct you to do this anyhow.
 
 ### Find a Vulnerability?
 If you have found a vulnerability in ESAPI legacy, first search the issues list (see above) to see if it has already been reported. If it has not, then please contact both Kevin W. Wall (kevin.w.wall at gmail.com) and Matt Seil (matt.seil at owasp.org) directly. Please do not report vulnerabilities via GitHub issues or via the ESAPI mailing lists as we wish to keep our users secure while a patch is implemented and deployed. If you wish to be acknowledged for finding the vulnerability, then please follow this process. (Eventually, we would like to have BugCrowd handle this, but that's still a ways off.) Also, when you post the email describing the vulnerability, please do so from an email address that you usually monitor.
@@ -64,5 +64,12 @@ Channel: #esapi<br/>
 Webchat http://webchat.freenode.net/
 
 *Mailing lists:*
-[ESAPI-Users mailing list](https://lists.owasp.org/mailman/listinfo/esapi-user/) and
-[ESAPI-Developers mailing list](https://lists.owasp.org/mailman/listinfo/esapi-dev/)
+As of 2019-03-25, ESAPI's 2 mailing lists were officially moved OFF of their Mailman mailing lists to a new home on Google Groups.
+
+The names of the 2 Google Groups are "[esapi-project-users](mailto:[email protected])" and "[esapi-project-dev](mailto:[email protected])", which you may POST to after you subscribe to them via "[Subscribe to ESAPI Users list](https://groups.google.com/forum/#!forum/esapi-project-users/join)" and "[Subscribe to ESAPI Developers list](https://groups.google.com/forum/#!forum/esapi-project-dev/join)" respectively.
+
+Old archives for the old Mailman mailing lists for ESAPI-Users and ESAPI-Dev are still available at https://lists.owasp.org/pipermail/esapi-users/ and https://lists.owasp.org/pipermail/esapi-dev/ respectively.
+
+For a general overview of Google Groups and its web interface, see https://groups.google.com/forum/#!overview
+
+For assistance subscribing and unsubscribing to Google Groups, see https://webapps.stackexchange.com/questions/13508/how-can-i-subscribe-to-a-google-mailing-list-with-a-non-google-e-mail-address/15593#15593

configuration/esapi/ESAPI.properties

@@ -32,14 +32,6 @@
 # file-based implementations, that some files may need to be read-write as they
 # get updated dynamically.
 #
-# Before using, be sure to update the MasterKey and MasterSalt as described below.
-# N.B.: If you had stored data that you have previously encrypted with ESAPI 1.4,
-#		you *must* FIRST decrypt it using ESAPI 1.4 and then (if so desired)
-#		re-encrypt it with ESAPI 2.0. If you fail to do this, you will NOT be
-#		able to decrypt your data with ESAPI 2.0.
-#
-#		YOU HAVE BEEN WARNED!!! More details are in the ESAPI 2.0 Release Notes.
-#
 #===========================================================================
 # ESAPI Configuration
 #
@@ -133,21 +125,6 @@ Encoder.DefaultCodecList=HTMLEntityCodec,PercentCodec,JavaScriptCodec
 # unlimited strength policy files and install in the lib directory of your JRE/JDK.
 # See http://java.sun.com/javase/downloads/index.jsp for more information.
 #
-# Backward compatibility with ESAPI Java 1.4 is supported by the two deprecated API
-# methods, Encryptor.encrypt(String) and Encryptor.decrypt(String). However, whenever
-# possible, these methods should be avoided as they use ECB cipher mode, which in almost
-# all circumstances a poor choice because of it's weakness. CBC cipher mode is the default
-# for the new Encryptor encrypt / decrypt methods for ESAPI Java 2.0.  In general, you
-# should only use this compatibility setting if you have persistent data encrypted with
-# version 1.4 and even then, you should ONLY set this compatibility mode UNTIL
-# you have decrypted all of your old encrypted data and then re-encrypted it with
-# ESAPI 2.0 using CBC mode. If you have some reason to mix the deprecated 1.4 mode
-# with the new 2.0 methods, make sure that you use the same cipher algorithm for both
-# (256-bit AES was the default for 1.4; 128-bit is the default for 2.0; see below for
-# more details.) Otherwise, you will have to use the new 2.0 encrypt / decrypt methods
-# where you can specify a SecretKey. (Note that if you are using the 256-bit AES,
-# that requires downloading the special jurisdiction policy files mentioned above.)
-#
 #		***** IMPORTANT: Do NOT forget to replace these with your own values! *****
 # To calculate these values, you can run:
 #		java -classpath esapi.jar org.owasp.esapi.reference.crypto.JavaEncryptor
@@ -185,12 +162,6 @@ Encryptor.PreferredJCEProvider=
 
 # AES is the most widely used and strongest encryption algorithm. This
 # should agree with your Encryptor.CipherTransformation property.
-# By default, ESAPI Java 1.4 uses "PBEWithMD5AndDES" and which is
-# very weak. It is essentially a password-based encryption key, hashed
-# with MD5 around 1K times and then encrypted with the weak DES algorithm
-# (56-bits) using ECB mode and an unspecified padding (it is
-# JCE provider specific, but most likely "NoPadding"). However, 2.0 uses
-# "AES/CBC/PKCSPadding". If you want to change these, change them here.
 # Warning: This property does not control the default reference implementation for
 #		   ESAPI 2.0 using JavaEncryptor. Also, this property will be dropped
 #		   in the future.
@@ -228,17 +199,29 @@ Encryptor.cipher_modes.combined_modes=GCM,CCM,IAPM,EAX,OCB,CWC
 # DISCUSS: Better name?
 Encryptor.cipher_modes.additional_allowed=CBC
 
-# 128-bit is almost always sufficient and appears to be more resistant to
-# related key attacks than is 256-bit AES. Use '_' to use default key size
-# for cipher algorithms (where it makes sense because the algorithm supports
-# a variable key size). Key length must agree to what's provided as the
-# cipher transformation, otherwise this will be ignored after logging a
-# warning.
+# Default key size to use for cipher specified by Encryptor.EncryptionAlgorithm.
+# Note that this MUST be a valid key size for the algorithm being used
+# (as specified by Encryptor.EncryptionAlgorithm). So for example, if AES is used,
+# it must be 128, 192, or 256. If DESede is chosen, then it must be either 112 or 168.
+#
+# Note that 128-bits is almost always sufficient and for AES it appears to be more
+# somewhat more resistant to related key attacks than is 256-bit AES.)
+#
+# Defaults to 128-bits if left blank.
+#
+# NOTE: If you use a key size > 128-bits, then you MUST have the JCE Unlimited
+#       Strength Jurisdiction Policy files installed!!!
 #
-# NOTE: This is what applies BOTH ESAPI 1.4 and 2.0. See warning above about mixing!
 Encryptor.EncryptionKeyLength=128
 
-# Because 2.0 uses CBC mode by default, it requires an initialization vector (IV).
+# This is the _minimum_ key size (in bits) that we allow with ANY symmetric
+# cipher for doing encryption. (There is no minimum for decryption.)
+#
+# Generally, if you only use one algorithm, this should be set the same as
+# the Encryptor.EncryptionKeyLength property.
+Encryptor.MinEncryptionKeyLength=128
+
+# Because 2.x uses CBC mode by default, it requires an initialization vector (IV).
 # (All cipher modes except ECB require an IV.) There are two choices: we can either
 # use a fixed IV known to both parties or allow ESAPI to choose a random IV. While
 # the IV does not need to be hidden from adversaries, it is important that the
@@ -249,8 +232,12 @@ Encryptor.EncryptionKeyLength=128
 # IVs. If you wish to use 'fixed' IVs, set 'Encryptor.ChooseIVMethod=fixed' and
 # uncomment the Encryptor.fixedIV.
 #
-# Valid values:		random|fixed|specified		'specified' not yet implemented; planned for 2.1
+# Valid values:		random|fixed|specified		'specified' not yet implemented; planned for 2.3
+#                                               'fixed' is deprecated as of 2.2
+#                                               and will be removed in 2.3.
 Encryptor.ChooseIVMethod=random
+
+
 # If you choose to use a fixed IV, then you must place a fixed IV here that
 # is known to all others who are sharing your secret key. The format should
 # be a hex string that is the same length as the cipher block size for the
@@ -260,6 +247,10 @@ Encryptor.ChooseIVMethod=random
 # "Recommendation for Block Cipher Modes of Operation".
 # (Note that the block size for AES is 16 bytes == 128 bits.)
 #
+#   @Deprecated -- fixed IVs are deprecated as of the 2.2 release and support
+#                  will be removed in the next release (tentatively, 2.3).
+#                  If you MUST use this, at least replace this IV with one
+#                  that your legacy application was using.
 Encryptor.fixedIV=0x000102030405060708090a0b0c0d0e0f
 
 # Whether or not CipherText should use a message authentication code (MAC) with it.
@@ -270,7 +261,15 @@ Encryptor.fixedIV=0x000102030405060708090a0b0c0d0e0f
 # "combined mode" cipher mode.
 #
 # If you are using ESAPI with a FIPS 140-2 cryptographic module, you *must* also
-# set this property to false.
+# set this property to false. That is because ESAPI takes the master key and
+# derives 2 keys from it--a key for the MAC and a key for encryption--and
+# because ESAPI is not itself FIPS 140-2 verified such intermediary aterations
+# to keys from FIPS approved sources would have the effect of making your FIPS
+# approved key generation and thus your FIPS approved JCE provider unapproved!
+# More details in
+#       documentation/esapi4java-core-2.0-readme-crypto-changes.html
+#       documentation/esapi4java-core-2.0-symmetric-crypto-user-guide.html
+# You have been warned.
 Encryptor.CipherText.useMAC=true
 
 # Whether or not the PlainText object may be overwritten and then marked
@@ -279,12 +278,14 @@ Encryptor.PlainText.overwrite=true
 
 # Do not use DES except in a legacy situations. 56-bit is way too small key size.
 #Encryptor.EncryptionKeyLength=56
+#Encryptor.MinEncryptionKeyLength=56
 #Encryptor.EncryptionAlgorithm=DES
 
 # TripleDES is considered strong enough for most purposes.
 #	Note:	There is also a 112-bit version of DESede. Using the 168-bit version
 #			requires downloading the special jurisdiction policy from Sun.
 #Encryptor.EncryptionKeyLength=168
+#Encryptor.MinEncryptionKeyLength=112
 #Encryptor.EncryptionAlgorithm=DESede
 
 Encryptor.HashAlgorithm=SHA-512

documentation/esapi4java-core-2.0-symmetric-crypto-user-guide.html

@@ -2,7 +2,7 @@
 <HTML>
 <HEAD>
 	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
-	<TITLE>ESAPI 2.0 Symmetric Encryption User Guide</TITLE>
+	<TITLE>ESAPI 2.x Symmetric Encryption User Guide</TITLE>
 	<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0  (Linux)">
 	<META NAME="CREATED" CONTENT="20100214;0">
 	<META NAME="CHANGEDBY" CONTENT="Kevin W. Wall">
@@ -12,17 +12,9 @@
 <TABLE BORDER="0" BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: auto; page-break-after: auto; page-break-inside: auto">
 <TR>
 <TD>
-<OBJECT TYPE="audio/x-mpeg" data="http://www.catonmat.net/download/crypt-o.mp3"
-WIDTH="500" HEIGHT="64" AUTOPLAY="false">
-    <PARAM NAME="src" VALUE="http://www.catonmat.net/download/crypt-o.mp3" />
-    <PARAM NAME="controller" VALUE="true" />
-    <PARAM NAME="autoplay" VALUE="false" />
-    <PARAM NAME="autostart" VALUE="0" />
-</OBJECT>
-</TD>
-<TD>
 <FONT COLOR="#00a444" SIZE="+2">
-<I>Crypto song. Take a listen and enjoy! Harry Belafonte never sounded this good. ;-)</I>
+    <A HREF="http://www.catonmat.net/download/crypt-o.mp3" TARGET="_blank"i
+        REL="noopener noreferrer nofollow">Crypto song</A>: <I>Take a listen and enjoy! Harry Belafonte never sounded this good. ;-)</I>
 </FONT>
 </TD>
 </TABLE>
@@ -121,10 +113,29 @@ <H2>ESAPI.properties Properties Relevant to Symmetric Encryption</H2>
 			<PRE><FONT COLOR="#ff0000"><FONT SIZE=2>128</FONT></FONT></PRE>
 		</TD>
 		<TD WIDTH=226>
-			<P><FONT SIZE=2>Key size, in bits. Required for cipher algorithms
+			<P><FONT SIZE=2>Default key size, in bits. Required for cipher algorithms
 			that support multiple key sizes.</FONT></P>
 		</TD>
 	</TR>
+	<TR VALIGN=TOP>
+		<TD WIDTH=249>
+			<PRE><FONT COLOR="#ff0000"><FONT SIZE=2>Encryptor.MinEncryptionKeyLength</FONT></FONT></PRE>
+		</TD>
+		<TD WIDTH=202>
+			<PRE><FONT COLOR="#ff0000"><FONT SIZE=2>128</FONT></FONT></PRE>
+		</TD>
+		<TD WIDTH=226>
+			<P><FONT SIZE=2>Minimum key size, in bits, that ESAPI will support
+                for <I>encryption</I>. (Note that any legitimate size is
+                accepted for <I>decryption</I>.) So, for example, if you needed
+                to be able to do encryption for 2-key Triple DES (aka, 2TDEA),
+                then you would have to change this to '112'. Note that for a
+                minimum key size of <U>larger</U> than 128-bits, you will need
+                to have the JCE Unlimited Strength Jurisdiction Policy files
+                installed on your runtime system.
+			</FONT></P>
+		</TD>
+	</TR>
 	<TR VALIGN=TOP>
 		<TD WIDTH=249>
 			<PRE><FONT COLOR="#ff0000"><FONT SIZE=2>Encryptor.ChooseIVMethod</FONT></FONT></PRE>
@@ -138,6 +149,8 @@ <H2>ESAPI.properties Properties Relevant to Symmetric Encryption</H2>
 			compatibility with legacy or third party software. If set to
 			“fixed”, then the property Encryptor.fixedIV must also be
 			set to hex-encoded specific IV that you need to use.
+            <B>NOTE:</B> "fixed" is deprecated and will be removed by
+            release 2.3.
             </FONT></P><P><FONT SIZE=2>
             <B>CAUTION:</B> While it is not required that the IV be kept
             secret, encryption relying on fixed IVs can lead to a known
@@ -788,7 +801,7 @@ <H2>Acknowledgments</H2>
 KDF more in line with NIST's recommendations for KDFs as described in
 NIST Special Publication 800-108 (and specifically section 5.1). You can
 read about Jeff's review at
-<a href="http://owasp-esapi-java.googlecode.com/svn/trunk/documentation/Analysis-of-ESAPI-2.0-KDF.pdf">
+<a href="https://github.com/ESAPI/esapi-java-legacy/blob/master/documentation/Analysis-of-ESAPI-2.0-KDF.pdf">
 Analysis of ESAPI 2.0's Key Derivation Function
 </a>
 </p>