Review 7031343: Provide API changes to support future GCM AEAD ciphers
bradford.wetmore at oracle.com
Wed Apr 6 21:46:48 PDT 2011
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  (modernization of the national crypto infrastructure), the
JDK will soon need to support the Galois Counter Mode (GCM) cipher mode
 for ciphers like AES. (e.g. GCM is also being used in some new TLS
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.
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, 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.
More information about the security-dev