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

[Bradford Wetmore]

Thanks for looking at this again.

On 4/7/2011 12:46 AM, Xuelei Fan wrote:
 > Looks fine to me.
 >
 > A few very minor suggestions:
 >
 > Cipher.java
 > ==========================================
 > C1:
 >
 > 98 * authenticity tag (checksum). This tag is appended to the ciphertext
 >
 >
 > I think "authentication tag" is more formal .

Ok.

 > I'm not sure whether the
 > "checksum" is a misleading comment to the readers. To me, checksum means
 > none-key-hash operations.

I debated putting that in thinking that it might help someone who knows 
JCE but is not familiar with GCM.  Mac would be a better choice.  I'll 
likely use that (or take it out completely).

 > C2:
 >
 > 112 * // If the GCMParameterSpec is needed again
 > 113 * cipher.getParameters().getParameterSpec(
 > 114 * GCMParameterSpec.class).getTLen(...);
 >
 > This block may be not necessary any more. There is no set-methods for
 > GCMParameterSpec. If you want to keep the block, I want suggest to
 > return the GCMParameterSpec rather than the Tag length.

Point taken.

 > GCMParameterSpec .java
 > ==========================================
 > C3:
 > I would suggest you use "authentication tag" rather than "tag" in the
 > spec, as would make it friendly to search engine.

Ok.  I'll wait to see if there are further comments, and will be 
submitting for internal review later today.

Thanks Andrew!

Brad

On 4/6/2011 9:46 PM, Brad Wetmore wrote:
> 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