Summary
-------

Provide stronger Password-Based-Encryption (PBE) algorithm implementations in
the SunJCE provider.


Non-Goals
---------

In addition to the algorithms listed in the Description section below, PKCS#5
defines several other encryption schemes for PBES2, many of them legacy, i.e.,
DES-CBC-PAD, DES-EDE3-CBC-PAD, RC2-CBC-PAD and RC5-CBC-PAD.  Given the lack of
demand for using these legacy encryption schemes with the newer Password-Based
cryptography, e.g., PBES2, there is no plan to provide support for them.

Although the PKCS#11 spec defines some mechanisms for Password Based
Cryptography, the SunPKCS11 provider currently does not support any of them.
The support from the underlying PKCS11 library also seems minimal, e.g.,
Solaris softtoken impl supports only CKM_PBE_SHA1_RC4_128 and CKM_PKCS5_PBKD2.
Thus, this JEP does not include the SunPKCS11 provider in its scope.

PKCS#5 v2.0 Amendment 1: XML Schema for Password-Based Cryptography defines the
XML identifiers for the PBE algorithms defined in PKCS#5 v2.0, but this should
be handled separately in XML code rather than in the SunJCE provider.


Motivation
----------

The currently supported PBE algorithms from the SunJCE provider only cover
DESede, and RC2 (40-bit) with SHA1.  To remain competitive we should also
support PBE algorithm implementations with stronger cipher and message digest
algorithms, such as AES cipher and SHA-2 family message digests, as well as
those specified by PKCS#12.


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

PKCS#12 specifies the following PBE algorithms for its password-privacy mode:

  1. PBEwithSHA1AndRC4_128
  2. PBEwithSHA1AndRC4_40
  3. PBEwithSHA1AndDESede (3-key)
  4. PBEwithSHA1AndDESede (2-key)
  5. PBEwithSHA1AndRC2_128
  6. PBEwthSHA1AndRC2_40

We currently support only 3 and 6.  To fully support PKCS12 keystores, we
should add support for all the others.

There have also been demands for password-based cryptography algorithms using
stronger encryption and digest schemes such as AES and SHA-2 family digests.
Thus it we should add support for PBES2 and PBMAC1 (as defined in PKCS#5 v2.1)
as recommended in PKCS#5 for newer applications.

The SunJCE provider will be enhanced to support the following algorithms:

  - `PBEwithSHA1AndRC4_128` cipher
  - `PBEwithSHA1AndRC4_40` cipher
  - `PBEwithSHA1AndDESede` (2-key) cipher
  - `PBEwithSHA1AndRC2_128` cipher

and perhaps combinations of the PBES2 cipher algorithms registered using the
algorithm name pattern `PBEWith<prf>And<encryption>` where

  - `<prf>` is one of `HmacSHA1`, `HmacSHA224`, `HmacSHA256`, `HmacSHA384`, or
    `HmacSHA512`, and

  - `<encryption>` is AES (i.e., AES-CBC-PAD in PKCS#5 v2.1 draft, AES with CBC
    mode and PKCS5Padding).

and finally, if time permits, to support for one or more of the following
PBMAC1 mac algorithms:

  - `PBEWithHmacSHA1` mac
  - `PBEWithHmacSHA224` mac
  - `PBEWithHmacSHA256` mac
  - `PBEWithHmacSHA384` mac
  - `PBEWithHmacSHA512` mac


Testing
-------

There are no test vectors provided in the PKCS#5 standard specification; we
would have to check third-party providers and test against them to validate our
own implementation.


Impact
------

  - JCP: we should be able to support the new PBE algorithms without any API
    changes, however if any API changes are needed for PBMAC1 then they will be
    proposed for the Umbrella JSR.

  - Documentation: Need to update all relevant security whitepapers, the SunJCE
    provider documentation, and reference guides with the newly-supported PBE
    algorithms.