-
Notifications
You must be signed in to change notification settings - Fork 364
/
esapi4java-core-2.0-readme-crypto-changes.html
440 lines (440 loc) · 21.6 KB
/
esapi4java-core-2.0-readme-crypto-changes.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>Why Is OWASP Changing ESAPI Encryption?</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Linux)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGED" CONTENT="20100228;21125900">
<META NAME="CHANGEDBY" CONTENT="Kevin W. Wall">
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1 ALIGN=CENTER>Why Is OWASP Changing ESAPI Encryption?</H1>
<H2>Reasons for Change</H2>
<H3>Symmetric Encryption in ESAPI 1.4</H3>
<P STYLE="margin-bottom: 0in">The as-delivered, default ESAPI 1.4
encryption mechanism uses "PBEWithMD5AndDES", a "Password
Based Encryption" algorithm. As implemented in ESAPI 1.4,
password (or pass phrase), taken from the property MasterPassword, is
concatenated with the salt as specified by the property MasterSalt,
and then repeated hashed 20 times using the MD5 message digest
algorithm. The intent of the salt and repetitive hashing is to slow
down dictionary attacks on the password. The result after the 20
iterations of hashing is used as the DES encryption key. The
encryption uses Cipher Block Chaining (CBC) cipher mode.</P>
<H3>Problems with Symmetric Encryption in ESAPI 1.4</H3>
<P>The problems with symmetric encryption in ESAPI 1.4 are many. Here
are some of the main issues:</P>
<OL>
<LI><P>The implementation only supported a single encryption key.
While this may be sufficient for some uses, clearly there are cases
where multiple recipients are involved when you would like to use
unique encryption keys for each recipient.</P>
<LI><P>ESAPI 1.4 came with a default setting for MasterPassword and
MasterSalt, thus not requiring that it be changed. How many of you
forgot to change these?</P>
<LI><P>Password based encryption is likely to be much weaker
randomly choosing a secret key. For instance, if you restrict
yourself to printable ASCII characters (which most people will), it
would require a pass phrase of roughly 45 characters to be the
equivalent of a randomly chosen 128-bit secret key.</P>
<LI><P>The default algorithm, DES, only has an effective key length
of 56-bits. This key size is too short and is in the realm of brute
forcing within a short amount of time for most medium to large
companies. (Fortunately, this could be addressed in part by changing
the EncryptionAlgorithm property from "PBEWithMD5AndDES"
to either "PBEWithHmacSHA1AndDESede" [if you are using JDK
1.5 or later] or to "PBEWithMD5AndTripleDES" [if you are
still using JDK 1.4]. Unfortunately, because of the implementation
of <CODE>JavaEncryptor</CODE>, only "password based encryption"
algorithms can be used in ESAPI 1.4.)</P>
<LI><P>The symmetric encryption does not provide for any means of
confirming message authenticity. Cryptographers consider ensuring
message authenticity an important feature of modern cryptosystems.</P>
</OL>
<H3>Symmetric Encryption in ESAPI 2.0rc1 and 2.0rc2</H3>
<P STYLE="margin-bottom: 0in">By default, release candidates ESAPI
2.0-rc1 and 2.0-rc2 used the 256-bit AES cipher with the cipher mode
Electronic Code Book (ECB) for encryption with <CODE>Encryptor</CODE>
via the ESAPI reference implementation, <CODE>JavaEncryptor</CODE>.
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
always encrypt to the same ciphertext block, thus revealing patterns
in the plaintext input. For example, these images from Wikipedia's
<A HREF="http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation">Block
cipher modes of operation</A> illustrate this point well:
</P>
<TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
<TR>
<TD>
<P ALIGN=CENTER><FONT COLOR="#000080"><A HREF="http://en.wikipedia.org/wiki/File:Tux.jpg"><FONT COLOR="#000080"><IMG SRC="http://upload.wikimedia.org/wikipedia/commons/5/56/Tux.jpg" NAME="graphics1" ALT="Original Tux image" ALIGN=BOTTOM WIDTH=196 HEIGHT=216 BORDER=1></FONT></A></FONT></P>
</TD>
<TD>
<P ALIGN=CENTER><FONT COLOR="#000080"><A HREF="http://en.wikipedia.org/wiki/File:Tux_ecb.jpg"><FONT COLOR="#000080"><IMG SRC="http://upload.wikimedia.org/wikipedia/commons/f/f0/Tux_ecb.jpg" NAME="graphics2" ALT="Tux image encrypted using ECB mode" ALIGN=BOTTOM WIDTH=196 HEIGHT=216 BORDER=1></FONT></A></FONT></P>
</TD>
<TD>
<P ALIGN=CENTER><FONT COLOR="#000080"><A HREF="http://en.wikipedia.org/wiki/File:Tux_secure.jpg"><FONT COLOR="#000080"><IMG SRC="http://upload.wikimedia.org/wikipedia/commons/a/a0/Tux_secure.jpg" NAME="graphics3" ALT="Tux image encrypted with other modessuch as CBC" ALIGN=BOTTOM WIDTH=196 HEIGHT=216 BORDER=1></FONT></A></FONT></P>
</TD>
</TR>
<TR>
<TD>
<P ALIGN=CENTER><I>Original Tux image</I></P>
</TD>
<TD>
<P ALIGN=CENTER><I>Image encrypted using ECB mode</I></P>
</TD>
<TD>
<P ALIGN=CENTER><I>Image encrypted using modes other than ECB</I></P>
</TD>
</TR>
</TABLE>
<P>Ciphertext encrypted with ECB cipher mode are also subject to
"block replay attacks". See Bruce Schneier's <A HREF="http://www.google.com/url?sa=t&source=web&ct=res&cd=2&url=http%3A%2F%2Fbooks.google.com%2Fbooks%3Fid%3DA6ZO2D6ayNwC%26pg%3DPT216%26lpg%3DPT216%26dq%3Decb%2B%2522block%2Breplay%2522%26source%3Dbl%26ots%3DiEbAWQpu0e%26sig%3D8xiUva4XKaAOfPJEPsULPAJPk88%26hl%3Den%26ei%3Da6yISoLQPJOuMI-Z_OkE%26sa%3DX%26oi%3Dbook_result%26ct%3Dresult%26resnum%3D2&ei=a6yISoLQPJOuMI-Z_OkE&rct=j&q=ecb+%22block+replay%22&usg=AFQjCNF-IjrE4dL7M2LELh48hYPP6A_bpQ"><I>Applied
Cryptography: protocols, algorithms, and source code</I> </A>for
details.
</P>
<P>In both ESAPI 2.0-rc1 and 2.0-rc2, one can choose other block
ciphers (e.g. Blowfish) or other key sizes (e.g., 512-bit AES), but
encryption in ESAPI 2.0-rc1 and 2.0-rc2 <I>only</I> support ECB
cipher mode with no padding; it cannot be used to decrypt data
encrypted with anything other than an algorithm using ECB cipher mode
and no padding. Most encryption (outside of ESAPI) uses some other
cipher mode (e.g., Cipher Block Chaining (CBC) mode) and some sort of
padding scheme, such as PKCS#5 padding, meaning that they are many
situations where ESAPI encryption would not be suitable.</P>
<H3>Problems with Symmetric Encryption in ESAPI 2.0-rc1 and 2.0-rc2</H3>
<P>The problems with symmetric encryption in ESAPI 2.0-rc1 and 2.0rc2
are many. Here are some of the main issues:</P>
<OL>
<LI VALUE=1><P>The implementation only supported a single encryption
key. While this may be sufficient for some uses, clearly there are
cases where multiple recipients are involved when you would like to
use unique encryption keys for each recipient.</P>
<LI><P>ESAPI 2.0-rc1 and 2.0-rc2 came with a default settings for
Encryptor.MasterKey and Encryptor.MasterSalt, thus not requiring
that these be changed. How many of you forgot to change these?</P>
<LI><P>Because the reference implementation in <CODE>JavaEncryptor</CODE>
allows no means to specify an Initialization Vector (IV), only the
weak ECB cipher mode can be used.</P>
<LI><P>The symmetric encryption does not provide for any means of
confirming message authenticity. Cryptographers consider ensuring
message authenticity an important feature of modern cryptosystems.</P>
</OL>
<H2>The Encryption Changes in ESAPI 2.0-rc3 and Later</H2>
<P>Briefly speaking, the changes being implemented for ESAPI Java 2.0
are:
</P>
<OL>
<LI><P STYLE="margin-bottom: 0in">Starting in ESAPI Java 2.0-rc3,
the <I>default</I> cipher transformation is changing to
"AES-128/CBC/PKCS5Padding" (i.e., 128-bit AES in CBC
cipher mode and PKCS#5 padding) with a random IV. The main reason
that 128-bit AES was chosen over 256-bit AES for the default is that
128-bit AES is slightly faster than 256-bit AES, and it does not
require you downloading the Unlimited Strength Jurisdiction Policy
files from Sun Microsystems. For those believing that 128-bit AES is
not sufficiently strong--bruting forcing it (except perhaps with a
reasonable quantum computer) is still not feasible--and certain key
related attacks (see Biryukov, Dunkelman, Keller, Khovratovich, and
Shamir's <A HREF="http://eprint.iacr.org/2009/374">Cryptology ePrint
Archive: Report 2009/374 -- Key Recovery Attacks of Practical
Complexity on AES Variants With Up To 10 Rounds </A>for further
details) show that longer key sizes in AES may not always be the
best.</P>
<LI><P STYLE="margin-bottom: 0in">Because cipher modes other than
ECB require an Initialization Vector (IV), a mechanism to handle
both fixed and random IVs has been added. The use of the “fixed”
IV should only be considered if there is a need to be compatible
with some legacy software or third party software package. Those
cases should be rare.</P>
<LI><P STYLE="margin-bottom: 0in">The original attempt to preserve
backward compatibility with ESAPI Java 1.4 (via
<CODE>org.owasp.esapi.reference.crypto.LegacyJavaEncryptor</CODE>)
has been removed. This was put to a vote on Jan 31, 2010 before both
the ESAPI Users and ESAPI Developers mailing lists and the lack of
response was deafening. There literally was but a single response
and that was to kill off <CODE>LegacyJavaEncryptor</CODE><CODE><FONT FACE="Thorndale AMT, serif">.</FONT></CODE>
(By this time, the two symmetric encryption interfaces in <CODE>Encryptor</CODE>
had already been deprecated.)
</P>
<LI><P>The byte-encoding has been changed from native byte encoding
to UTF-8 byte-encoding throughout ESAPI 2.0 and not just for
encryption. This was needed so that one could (say) encrypt on a
Sparc running Solaris and then move the encrypted data to an Intel
host running Windows and still be able to decrypt the data. Without
this change to use uniform encoding throughout, this could not be
guaranteed.</P>
</OL>
<H2>The Good, the Bad, and the Ugly</H2>
<P>Or put another way, there are always trade-offs to be made...
</P>
<H3>The Good</H3>
<P>We get improved security by encouraging the use of stronger cipher
modes (and ESAPI is all about "enterprise security",
right?). Furthermore, it is possible to choose a preferred JCE
provider for ESAPI and ESAPI will attempt to use that provider. For
example, if you wish to use Bouncy Castle rather than the SunJCE, you
can do so. One place where this might be a significant advantage is
if you need to use a FIPS 140-2 compliant JCE implementation. Whereas
in production environments, you ultimately will want to ensure this
by editing your <FONT FACE="DejaVu Sans Mono, sans-serif">$JAVA_HOME/jre/lib/security/java.security</FONT>
file, this is often inconvenient for developers who simply wish to
test because this file often requires super-user access to alter. In
such cases, setting the new ESAPI property
<FONT FACE="DejaVu Sans Mono, sans-serif">Encryptor.PreferredJCEProvider</FONT>
to the fully qualified class name of your FIPS 140-2 JCE provider in
your <FONT FACE="Thorndale AMT, serif"><B>ESAPI.properties</B></FONT>
file and you can test without any other changes to your code or you
environment.</P>
<P>We also get message authenticity as long as we don't use any of
the deprecated encryption methods or intentionally disable it. (The
only <I>sane</I> reason for intentionally disabling the MAC
calculation is for FIPS 140-2 compliance. This MAC calculation
requires deriving two new <FONT FACE="DejaVu Sans Mono, sans-serif">SecretKey</FONT>s
from the original key—one to use for message authenticity and a
second one to use for message confidentiality. While we believe that
this mechanism is secure [it was originally suggested by professional
cryptographers], this key derivation would not be using FIPS 140-2
approved code. Therefore if you require FIPS 140-2 compliance, you
should set “<FONT FACE="DejaVu Sans Mono, sans-serif">Encryptor.CipherText.useMAC=false</FONT>”
in your <FONT FACE="Thorndale AMT, serif"><B>ESAPI.properties</B></FONT>
file.)</P>
<H3>The Bad</H3>
<P>With cipher modes that require an IV, the same IV must be used
both to encrypt and decrypt. While it is not required that the IV be
kept secret from adversaries, there are some attacks that are
possible if the adversary is permitted to alter the IV at will and
observe the results of the ensuing decryption attempt.
</P>
<P>So that leaves two choices for the IV:
</P>
<UL>
<LI><P STYLE="margin-bottom: 0in">Using a <I><B>fixed IV</B></I>:
The IV can be agreed upon out-of-band by the parties exchanging
encrypted messages. In this way, the encrypted data that is stored
and/or transmitted can be limited to only the <I>raw</I> ciphertext.
(<U><B>WARNING</B></U><SPAN STYLE="text-decoration: none"><SPAN STYLE="font-weight: normal">:
This case should be reserved for situations requiring compatibility
with legacy or third party software packages.)</SPAN></SPAN></P>
<LI><P>Using a <I><B>random IV</B></I>: Most cryptographers prefer
to use a random IV, typically a different one with each message to
be encrypted. However, doing so on encrypted data that will be
persisted (e.g., to a database) or transmitted to the recipient this
random IV must be stored / made known. Therefore, the raw ciphertext
can no longer suffice; whatever random IV that was chosen must be
communicated.
</P>
</UL>
<P>Likewise, the use of padding is going to add some overhead to the
length of the ciphertext.</P>
<P STYLE="margin-bottom: 0in">For example, a short plaintext of 0-15
bytes, this overhead can be around 200% of the total plaintext size.
This overhead diminishes (as a percent of the total plaintext size)
as the plaintext size increases. Here is a table that illustrates
this:</P>
<A NAME="encryption-overhead">
<P STYLE="margin-bottom: 0in"><BR>
</P>
</A>
<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0>
<COL WIDTH=64*>
<COL WIDTH=64*>
<COL WIDTH=64*>
<COL WIDTH=64*>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=CENTER><B>Original input length of plaintext <BR>(#
bytes)</B></P>
</TD>
<TD WIDTH=25%>
<P ALIGN=CENTER><B>Base64-encoded length of ciphertext (with IV
and padding) encrypted with 128-bit AES in CBC mode, but no MAC<SUP>1</SUP></B></P>
</TD>
<TD WIDTH=25%>
<P ALIGN=CENTER><B>Length of raw portable serialized CipherText
byte array, containing IV, padding, and MAC, and encrypted with
128-bit AES in CBC mode</B></P>
</TD>
<TD WIDTH=25%>
<P ALIGN=CENTER><B>Length of raw portable serialized CipherText,
containing IV, padding, and MAC, and encrypted with 128-bit AES in
CBC mode as a Base64-encoded string</B></P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>0-15</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>44</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>102</P>
</TD>
<TD WIDTH=25% SDVAL="137" SDNUM="1033;">
<P>137</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>16-31</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>64</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>118</P>
</TD>
<TD WIDTH=25% SDVAL="162" SDNUM="1033;">
<P>162</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>32-47</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>88</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>134</P>
</TD>
<TD WIDTH=25% SDVAL="182" SDNUM="1033;">
<P>182</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>48-63</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>108</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>150</P>
</TD>
<TD WIDTH=25% SDVAL="202" SDNUM="1033;">
<P>202</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>64-79</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>128</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>166</P>
</TD>
<TD WIDTH=25% SDVAL="222" SDNUM="1033;">
<P>222</P>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=25%>
<P ALIGN=LEFT>… etc. Each additional 16 bytes of plaintext...</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>...adds ~20 additional bytes</P>
</TD>
<TD WIDTH=25%>
<P ALIGN=LEFT>...adds 16 additional bytes</P>
</TD>
<TD WIDTH=25%>
<P>...adds 20 additional bytes</P>
</TD>
</TR>
</TABLE>
<P>__________________________________</P>
<P>1. That is, the <FONT FACE="DejaVu Sans Mono, sans-serif">String</FONT>
that is returned by the deprecated <FONT FACE="DejaVu Sans Mono, sans-serif">Encryptor.decrypt(String)</FONT>
method.</P>
<P>As you can see, since the size of the IV and the amount of padding
bytes are fixed at a maximum, this overhead goes down as the length
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
between 1 to the cipher block size (in bits) / 8 bytes. For AES, the
cipher block size is 128-bits, but more typically, a cipher's block
size is 64-bits so the padding would be between 1 to 16 bytes for AES
and 1 to 8 bytes for a 64-bit block size cipher and the IV would be
IV would be 16 bytes for AES and 8 bytes for most other ciphers.
</P>
<H3>The Ugly</H3>
<P>Well, so far, this "bad" news may be bad for you but
good for your database and/or storage vendor, but you probably can
live with it, especially if you are willing to do a little bit of
recoding of your database table sizes.</P>
<P>But wait Skippy, don't go running off just quite yet. As Robert
Heinlein wrote in his 1966 novel <I>The Moon is a Harsh Mistress</I>
"There ain't no such thing as a free lunch". (Some of us
more hardened cynics know it more commonly as <I>TANSTAAFL</I>.)
</P>
<P>As mentioned earlier, backward compatibility with ESAPI 1.4
(originally planned via <CODE>LegacyJavaEncryptor</CODE>) has been
removed because of apparent lack of interest. What this means is if
you are one of the unlucky stuckeys who are using ESAPI 1.4 symmetric
encryption to encrypt data and you have persisted this data (and this
would <I>include </I><SPAN STYLE="font-style: normal">the use of the
</SPAN><FONT FACE="DejaVu Sans Mono, sans-serif"><SPAN STYLE="font-style: normal">org.owasp.esapi.EncryptedProperties</SPAN></FONT>
<SPAN STYLE="font-style: normal">class in ESAPI 1.4)</SPAN>, you will
first have to <I>decrypt </I><SPAN STYLE="font-style: normal">this
encrypted data using ESAPI 1.4 before using encryption with ESAPI
2.0. As they say, “we are sorry for the inconvenience”, but there
was an opportunity to make your voice heard so we refuse to take </SPAN><I>all
</I><SPAN STYLE="font-style: normal">the blame.</SPAN></P>
<P>In addition, all this backward compatibility and flexibility comes
at the extra cost of complexity, and not <I>merely</I> additional
complexity in the reference implementation. There is also some
additional complexity in the ESAPI <CODE>Encryptor</CODE> interfaces
as well.</P>
<P>In particular, there new classes for plaintext (<FONT FACE="DejaVu Sans Mono, sans-serif">PlainText</FONT>)
and ciphertext (<CODE>CipherText)</CODE> class to coalesce all this
complexity of handling the ciphertext result from encryption
operations. And then there are new encryption and decryption methods
for the <CODE>Encryptor</CODE> interface. Specifically, the encrypt
and decrypt methods have been generalized as:
</P>
<PRE STYLE="margin-left: 0.49in"><FONT COLOR="#000000"><FONT FACE="Monospace">CipherText encrypt(SecretKey key, PlainText plaintext)</FONT></FONT>
<FONT COLOR="#000000"> <FONT FACE="Monospace">throws EncryptionException;</FONT></FONT></PRE><P STYLE="margin-bottom: 0in">
and
</P>
<PRE STYLE="margin-left: 0.49in"><FONT COLOR="#000000"><FONT FACE="Monospace">PlainText decrypt(SecretKey key, CipherText ciphertext)</FONT></FONT>
<FONT COLOR="#000000"> <FONT FACE="Monospace">throws EncryptionException</FONT></FONT></PRE><P>
(There are also two corresponding encrypt / decrypt methods that omit
the initial <FONT FACE="DejaVu Sans Mono, sans-serif">SecretKey</FONT>
argument and instead use the <FONT FACE="DejaVu Sans Mono, sans-serif">SecretKey</FONT>
based on <FONT FACE="DejaVu Sans Mono, sans-serif">Encryptor.MasterKey</FONT>.)</P>
<P>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 STYLE="margin-bottom: 0in">
and
</P>
<PRE STYLE="margin-left: 0.49in; margin-bottom: 0.2in">String decrypt(String ciphertext) throws EncryptionException</PRE><P>
are still supported but have been <I>deprecated</I>, mainly because
they do not support integrity / authenticity checks which most
cryptographers consider essential. Also these older String-based
encrypt() / decrypt() interfaces have slightly different semantics
than do their ESAPI 1.4 counterparts in that these methods default to
CBC cipher mode, PKCS5Padding, and a random IV. This means that at a
minimum, the IV must be included as the resulting base64-encoded
“ciphertext”.</P>
<P>However, this difference in cipher mode means that if you have
data that was previously encrypted using ESAPI 1.4 or earlier, you
will not be able 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 may contact the
author, <a href="mailto:kevin.w.wall@gmail.com">Kevin W. Wall</a>,
for assistance.
</P>
<P>Note that while the new String-based encrypt() / decrypt() methods
use the stronger CBC cipher mode with a random IV, they still do not
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>
<H2>Further Details</H2>
<P>Further details are provided in the <CODE>Encryptor</CODE> Javadoc
and the “Symmetric Encryption” section of the ESAPI User Guide.</P>
</BODY>
</HTML>