Summary
-------

Implement the SHA-224 message-digest algorithm and related algorithms.


Goals
-----

Enhance the JDK's existing cryptographic algorithms with the the SHA-224
variant of the SHA-2 family of message-digest implementations.  Ensure
interoperability with commonly-used third-party crypto providers or among the
providers that are bundled in JDK.


Motivation
----------

More and more applications and protocols are adopting SHA-2 message digests due
to known flaws with the SHA-1 message digest.  The JDK didn't initially support
SHA-224 since it isn't adopted as widely as the other SHA-2 variants, i.e.,
SHA-256, SHA-384, and SHA-512. In recent years some standards, e.g., PKCS11,
have been amended to support SHA-224, so we should support it as well.


Description
-----------

SHA-224 is defined in the exact same manner as SHA-256 (FIPS 180-3 Section
6.2), with the following two exceptions:

  1. The initial hash value, H, shall be set as specified in Sec. 5.3.2; i.e.,
     in eight 32-bit words H0--H7: H0 = c1059ed8, H1 = 367cd507, H2 = 3070dd17,
     H3 = f70e5939, H4 = ffc00b31, H5 = 68581511, H6 = 64f98fa7, H7 = befa4fa4.

  2. The 224-bit message digest is obtained by truncating the final hash value,
     H(N), to its left-most 224 bits: In addition to providing the SHA-224
     message digest implementation, other cryptographic algorithms using
     SHA-224 should also be implemented to provide a complete solution. Here is
     the list of cryptographic algorithms and their corresponding providers:

       - SHA224 message digest in SUN provider
       - SHA224withRSA signature in SunRsaSign provider
       - SHA224withECDSA signature in SunEC provider
       - HmacSHA224 mac in SunJCE provider
       - OAEPwithSHA-224AndMGF1Padding support in SunJCE provider
       - SHA224 message digest (CKM_SHA224), SHA224withRSA signature
         (CKM_SHA224_RSA_PKCS), HmacSHA224 mac (CKM_SHA224_HMAC) in SunPKCS11
         provider


Testing
-------

Known-Answer Test: Test vectors are available:

  - SHA224: <http://csrc.nist.gov/groups/ST/toolkit/documents/Examples/SHA224.pdf>

  - HmacSHA224: <http://csrc.nist.gov/groups/ST/toolkit/documents/Examples/HMAC_SHA224.pdf>

Interoperability Test: Can be performed when more than one of JDK crypto
providers support the same algorithms, e.g., SUN vs SunPKCS11 for SHA224,
SunRsaSign vs SunPKCS11 for SHA224withRSA, etc. Or, SQE can develop product
tests checking the interoperability against 3rd-party crypto providers such as
Bouncy Castle.


Risks and Assumptions
---------------------

The SunPKCS11 provider does not support all mechanisms defined by the PKCS11
standard. For example, PKCS11 defines mechanisms for key-derivation
functionality, i.e., given a secret key, it can derive another secret key with
parity-adjusted bits. The SunPKCS11 provider does not support any of the
key-derivation functionality using message digests, i.e., the
CKM_[MD5/SHA1/SHA256/SHA384/SHA512]_KEY_DERIVATION mechanisms, thus support for
CKM_SHA224_KEY_DERIVATION is omitted.  The same is true for the
CKM_SHA224_RSA_PKCS_PSS mechanism, the CKG_MGF1_SHA224 function, the
CKM_SHA224_HMAC_GENERAL mechanism, and the SunRsaSign provider with respect to
RSA PSS Signatures.


Impact
------

  - Doc: Several security documents will have to be updated with the newly
    supported algorithms, such as JCA Standard Algorithm Name Documentation as
    well as the reference guides for various providers.

  - Legal: Need to update the list of supported crypto algorithms for
    export-control paperwork.