Merge branch 'master' into 'develop' to catch 'develop' back up.

Author: kwwall

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>