The goal of this enhancement is to support an initial set of Password-Based Cryptography algorithms in the SunPKCS11 security provider. These algorithms provide derivation of a binary key for encryption -referred as Password-Based Encryption (PBE)-, integrity or authentication out of a password, by means of a chosen key derivation function that also takes a salt and an iteration count as input. The SunJCE security provider supports a set of PBE algorithms already (see JDK-6383200 [1] and JDK-8046111 [2] for example). For better interoperability with SunJCE, we require alignment in terms of algorithm names. As a result of this enhancement, SunPKCS11 will support underlying primitives for PKCS #12 key stores with privacy and integrity checks. We will verify this capability with the SUN security provider implementation.

For reference, the PKCS #11 standard v2.40 defines PBE mechanisms in its section "2.26 PKCS #5 and PKCS #5-style password-based encryption (PBE)" [3]. The PKCS #11 standard v3.0 defines PBE mechanisms in its section "2.37 PKCS #5 and PKCS #5-style password-based encryption (PBE)" [4]. The implementation must support both revisions of the standard. While there is high degree of compatibility between them, it might be necessary to implement different behavior based on the token's supported standard in some places. The PBE algorithms themselves are defined in 1) section "Appendix B. Deriving Keys and IVs from Passwords and Salt" of the "PKCS #12: Personal Information Exchange Syntax v1.1" RFC 7292 [5], and in 2) "PKCS #5: Password-Based Cryptography Specification Version 2.1" RFC 8018 [6].

The following PBE algorithms are under scope (grouped per service):

Cipher
========================

PBES2 (using PBKD2 underneath)
----------------------------------------------

 * PBEWithHmacSHA1AndAES_128
 * PBEWithHmacSHA224AndAES_128
 * PBEWithHmacSHA256AndAES_128
 * PBEWithHmacSHA384AndAES_128
 * PBEWithHmacSHA512AndAES_128
 * PBEWithHmacSHA1AndAES_256
 * PBEWithHmacSHA224AndAES_256
 * PBEWithHmacSHA256AndAES_256
 * PBEWithHmacSHA384AndAES_256
 * PBEWithHmacSHA512AndAES_256

Mac
========================

PKCS #12 General Method for Password Integrity
--------------------------------------------------------------------

 * HmacPBESHA1
 * HmacPBESHA224 (*)
 * HmacPBESHA256 (*)
 * HmacPBESHA384 (*)
 * HmacPBESHA512 (*)

SecretKeyFactory
========================

PBES2 (using PBKD2 underneath)
----------------------------------------------

 * PBEWithHmacSHA1AndAES_128
 * PBEWithHmacSHA224AndAES_128
 * PBEWithHmacSHA256AndAES_128
 * PBEWithHmacSHA384AndAES_128
 * PBEWithHmacSHA512AndAES_128
 * PBEWithHmacSHA1AndAES_256
 * PBEWithHmacSHA224AndAES_256
 * PBEWithHmacSHA256AndAES_256
 * PBEWithHmacSHA384AndAES_256
 * PBEWithHmacSHA512AndAES_256

PBKD2
------------------------

 * PBKDF2WithHmacSHA1
 * PBKDF2WithHmacSHA224
 * PBKDF2WithHmacSHA256
 * PBKDF2WithHmacSHA384
 * PBKDF2WithHmacSHA512

PKCS #12 General Method for Password Integrity
--------------------------------------------------------------------

 * HmacPBESHA1
 * HmacPBESHA224 (*)
 * HmacPBESHA256 (*)
 * HmacPBESHA384 (*)
 * HmacPBESHA512 (*)

(*) Note: neither the current PKCS #11 standard (v3.0) nor the previous one (v2.40) define mechanisms for these algorithms. Until a future revision of the standard introduces these mechanisms, NSS vendor-specific constants will be used. Thus, non-NSS tokens will probably not support these algorithms.

PBES1 and PBMAC1 algorithms (defined by RFC 8018), as well as PKCS #12 General Method for Password Privacy, are out of the scope of this enhancement. While we have prioritized newer algorithms or algorithms needed for PKCS #12 key stores at this time, extensions can be considered in the future and should not have a significant impact on the overall design.

Interoperability

The following interoperability goals are defined:

 * For SecretKeyFactory, Cipher and Mac services of PBE algorithms, SunPKCS11 must accept keys implementing the javax.crypto.interfaces.PBEKey interface. These keys contain all the information required for derivation. Also, in the interest of better interoperability with SunJCE, SecretKey keys whose algorithm name is "PBE" are also accepted for Cipher and Mac services. Notice that in the latter case, parameters with information for derivation must be passed as java.security.AlgorithmParameters or javax.crypto.spec.PBEParameterSpec instances because these keys contain a password only.

 * PBE keys derived with SecretKeyFactory services must be usable in their corresponding PBE and non-PBE Cipher and Mac services. As an example, a PBE key derived with a SecretKeyFactory of the PBEWithHmacSHA1AndAES_256 algorithm must be usable in: 1) a Cipher of the PBEWithHmacSHA1AndAES_256 algorithm and 2) a Cipher of the AES algorithm. Notice that if the implementation of the Cipher algorithm comes from a non-SunPKCS11 provider, the key will be converted first.

 * SunJCE and SunPKCS11 PBE keys must derive to the same value (given the same set of inputs) and be interoperable in the sense that 1) what is encrypted with one provider, must be decrypted with the other, and 2) a Mac calculated with one provider, must be verified with the other. The same holds true when comparing SunPKCS11 PBE results with external (non-OpenJDK) implementations.

 * The SUN PKCS #12 implementation must be able to use SunPKCS11 for underlying PBE primitives to read and write key stores generated by other security providers or external libraries, in the same way that it does with SunJCE.

 * SecretKeyFactory for PBKD2 algorithms in SunPKCS11 accepts unicode passwords and salts, in the same way than SunJCE. These passwords will be internally encoded as UTF-8, as required per the PKCS #5 v2.1 standard. SecretKeyFactory for PKCS #12 General Method in SunPKCS11 accepts unicode for passwords and salts, contrary to SunJCE where passwords must be ASCII. These passwords will be internally encoded as BMPString, as required per the PKCS #12 v1.1 standard.

 * Cipher and Mac services are subject to the same password encoding constraints than SunJCE, which allows ASCII only at the moment when the key is derived by these services. It's not in the scope of this enhancement to analyze the impact of lifting this contraint and allowing all unicode passwords for both security providers. Notice that in the SunPKCS11 case, it's possible to derive a unicode key with SecretKeyFactory and pass it to a Cipher or Mac service.

 * To keep compatibility with SunJCE in the Cipher service case, a non-P11 key implementing the javax.crypto.interfaces.PBEKey interface must return the password in its "getEncoded" method. It's not in the scope of this enhancement to consider a behavior change for both security providers.

By following the previous list of interoperatibility requirements, we aim to have an implementation that works well with SunJCE-based code and allows the transition between security providers to be smooth.

--
[1] - https://bugs.openjdk.org/browse/JDK-6383200
[2] - https://bugs.openjdk.org/browse/JDK-8046111
[3] - https://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/errata01/os/pkcs11-curr-v2.40-errata01-os-complete.html#_Toc441850587
[4] - https://docs.oasis-open.org/pkcs11/pkcs11-curr/v3.0/os/pkcs11-curr-v3.0-os.html#_Toc30061409
[5] - https://datatracker.ietf.org/doc/html/rfc7292#appendix-B
[6] - https://datatracker.ietf.org/doc/html/rfc8018