<H1 ALIGN=CENTER>Why Is OWASP Changing ESAPI Encryption?</H1>

<H2>Reasons for Change</H2>

<P STYLE="margin-bottom: 0in">The existing ESAPI 1.4 uses the cipher

ECB cipher mode is the simplest cipher mode to use, but it is also

cryptographically very weak. If more than one block of plaintext is

encrypted with the same key, those identical blocks of ciphertext

</P>

<LI><P STYLE="margin-bottom: 0in">A mechanism to attempt to preserve

backward compatibility with ESAPI Java 1.4 (via

has been added, but because of the security implications of using

the ECB cipher mode, you are encouraged to stop using this as soon

as possible. (In fact, this backward compatibility mechanism should

<P>Likewise, the use of padding is going to add some overhead to the

length of the ciphertext.

<TABLE WIDTH=348 BORDER=1 CELLPADDING=4 CELLSPACING=0>

<COL WIDTH=126>

<P ALIGN=LEFT>0-15</P>

</TD>

<TD WIDTH=204>

</TD>

</TR>

<TR>

<TD WIDTH=126>

<P ALIGN=LEFT>16-31</P>

</TD>

<TD WIDTH=204>

</TD>

</TR>

<TR>

<TD WIDTH=126>

<P ALIGN=LEFT>32-47</P>

</TD>

<TD WIDTH=204>

</TD>

</TR>

<TR>

<TD WIDTH=126>

<P ALIGN=LEFT>48-63</P>

</TD>

<TD WIDTH=204>

</TD>

</TR>

<TR>

<TD WIDTH=126>

</TD>

<TD WIDTH=204>

</TD>

</TR>

of the plaintext message increases. The IV is always a fixed length

for a given cipher; it is always the same as the cipher block size.

The padding can vary, but for PKCS5 padding, the padding will be

<H3>The Ugly</H3>

<P>Well, so far, this &quot;bad&quot; news may be bad for you but

good for your database and/or storage vendor, but you probably can

<P>All this backward compatibility and flexibility comes at the

additional cost of complexity, and not <I>merely</I> additional

complexity in the reference implementation. There is also some

interfaces as well.

class to coalesce all this complexity of handling the ciphertext

result from encryption operations as well as a reference

for it as well. And then there is one new encryption and one new

interface. Specifically, the encrypt and decrypt methods have been

generalized as:

and

The two existing interfaces from ESAPI 1.4 and earlier</P>

<PRE STYLE="margin-left: 0.49in; margin-bottom: 0.2in">String encrypt(String plaintext) throws EncryptionException</PRE><P>

and

to decrypt it using the ESAPI 2.0</P>

<PRE STYLE="margin-left: 0.49in; margin-bottom: 0.2in">String decrypt(String ciphertext) throws EncryptionException</PRE><P>

method. If you require such compatibility, you should set

your <B>ESAPI.properties</B> file, this class likely will be removed

in a future ESAPI release. (This class is intended only to provide

backward compatibility so that you may decrypt previously encrypted

ensure authenticity and integrity so the more general encrypt() /

decrypt() methods should be preferred over the String-based ones.

(See below for examples of how to use these new methods.)</P>

Javadoc.</P>

<H2>Symmetric Encryption in ESAPI 2.0</H2>

<H3>ESAPI.properties Properties Relevant to Symmetric Encryption</H3>

<FONT COLOR="#ff0000">Encryptor.ChooseIVMethod=random</FONT>

# This is only used when Encryptor.ChooseIVMethod=fixed is set, otherwise a random IV is used.

<FONT COLOR="#ff0000">Encryptor.fixedIV=</FONT><FONT COLOR="#0000FF">0xdbd1a3636024b7b402da7d6fe3fb056e</FONT>

<FONT COLOR="#ff0000">Encryptor.CipherText.useMAC=true</FONT>

This code will still work, however if you are using the standard

the cipher transformation used with be that specified by the property

a key size (when the algorithm supports a variable key size) of that

This is opposed to the old ESAPI 1.4 default of 256-bit AES in ECB

mode with no padding (and obviously no IV). If you have no need to

decrypt data that was previously encrypted using ESAPI 1.4, this

which will cause these two String-based encrypt / decrypt methods to

use 256-bit AES with cipher transformation “AES/ECB/None”. Note

that the new encryption / decryption methods continue to work as they

class. Note that the legacy encryption can <I>only </I><SPAN STYLE="font-style: normal">use

the master encryption key, but that is all that is required for

compatibility with ESAPI 1.4.</SPAN></P>

<PRE> byte[] plaintextByteArray = { /* byte array to be encrypted */ };

String plaintext = new String(plaintextByteArray, &quot;UTF-8&quot;);</PRE><P>

For example, to handle this in ESAPI 1.4, one would have to write:</P>

<PRE> try {

byte[] plaintextByteArray = { /* byte array to be encrypted */ };

String decrypted = ESAPI.encryptor().decrypt(ciphertext);

byte[] recoveredBytes = decrypted.getBytes(“UFT-8”);

assert java.util.Arrays.equals( plaintextByteArray, recoveredBytes );

// Should not happen but need to catch and deal with it anyhow.

// Log error then return error designation however appropriate.

} catch(EncryptionException ex) {

encrypted. Instead, you should overwrite them after their value as

been used. However, when you are using immutable Strings, this is not

possible using native Java methods. But if you are able to pass in

objects (as shown above), the <I>default</I> is to overwrite this

after they are encrypted. If the default for

been overwritten with ASCII “*” characters.</P>

<H3>Encrypting / Decrypting with the New Methods -- Advanced Usage</H3>

ESAPI 1.4 and earlier only allowed you to use the master key

But encryption with a single key is not always sufficient. For

instance, lets say that your application has a need to encrypt both

bank account numbers and credit card numbers. The encrypted bank account

by our application, perhaps using something like ESAPI's

<code>EncryptedProperties</code> class, where they could later be

retrieved and used.

In the following code, we assume that the <code>SecretKey</code> values

have already been initialized elsewhere.

// Log error then return error designation however appropriate.

}