Review 7031343: Provide API changes to support future GCM AEAD ciphers

[Brad Wetmore]

Hi Xuelei/Valerie,

Our JDK 7 freeze window is fast closing and I'd like to get this in for 
b140, so will need a quick turnaround to make this happen.

7031343: Provide API changes to support future GCM AEAD ciphers

As we talked about, as part of the National Security Agency's Suite B 
effort [1] (modernization of the national crypto infrastructure), the 
JDK will soon need to support the Galois Counter Mode (GCM) cipher mode 
[2] for ciphers like AES.  (e.g. GCM is also being used in some new TLS 
ciphersuites [3][4]).

We will not be able to provide a full implementation of GCM in JDK 7 
FCS, but we would like to be able to add this as a potential enhancement 
in a future JDK 7 Update Release (UR).  Adding GCM in an JDK 7 UR will 
require API changes in JDK 7 now.

The changes are fairly small, low risk, and localized.  There are some
minor changes to Cipher/CipherSpi, and two new classes for an AEAD
Exception and a GCMParameterSpec.

http://cr.openjdk.java.net/~wetmore/7031343/javadocs.00/
http://cr.openjdk.java.net/~wetmore/7031343/webrev.00/

A few points worth calling out:

1)  The API's were designed with an eye to both CCM and GCM.  GCM is the
important one now from the Suite B perspective.  We'll probably add 
similar CCM Parameters in JDK 8.

2)  If algorithm parameters are not derivable from the supplied inputs, 
Cipher.init() will normally trigger the generation of algorithm 
parameters based on provider-specific default values.  But note that XML 
GCM is using 128 bit tags, and TLS 1.2 is using 96 bit tags, so there 
really isn't a completely clear-cut default.  And in GCM for IV, that 
would push IV generation down into the CSP provider, which means the 
provider must keep track of all previously used IV's, which could be 
perceived as a 128-bit memory leak for each GCM operation on reused 
Cipher objects. Language was added to allow providers to select IV if 
they really want to, but in most cases and for interoperability, the 
caller really should be specifying the tagLen/IV in a GCMParameterSpec.

3)  AEAD (GCM/CCM) tags are appended to the ciphertext on encryption, 
and verified/removed during decryption, as is done in RFC 5116[5], and 
is reflected in other GCM APIs.  Because Ciphers are reset after each 
doFinal(), we would have had to create an intermediate state/getTag(), 
or add some kind of outbound data structure.  Appending was far cleaner.

4)  AEADBadTagException is a subclass of BadPaddingException, which is a 
checked exception currently thrown by the doFinal methods.   While it's 
not exactly BadPadding in the true sense of padding, it is close and was 
the best option for a checked Exception.  A RunTimeException really 
should be reserved for programming mistakes, not normal operations.

5)  AAD can be supplied to the cipher in chunks, and is not restricted 
to a single shot as in PKCS11.  This will allow applications with huge 
AADs the flexibility to not have to store everything in memory (media 
files).  Also, the underlying GCM/CCM algorithms process all AAD before 
the plain/ciphertext, so we require updateAAD() to be called before 
plain/ciphertext is handled.

6)  As usual for adding new methods to these engine classes, for 
backwards source and binary compatibility with older providers, the new 
updateAAD() methods in CipherSpi will throw 
UnsupportedOperationExceptions unless the provider overrides the method.

Thanks,

Brad

[1]: http://www.nsa.gov/ia/programs/suiteb_cryptography/
[2]: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf
[3]: http://www.rfc-editor.org/info/rfc5288
[4]: http://www.rfc-editor.org/info/rfc5289
[5]: http://www.rfc-editor.org/info/rfc5116