Summary

Update the SunPKCS11 security provider to support the following HKDF (RFC 5869) algorithms as KDF services (implementation of JEP 478): HKDF-SHA256, HKDF-SHA384, and, HKDF-SHA512. The underlying PKCS #11 library must support either the CKM_HKDF_DATA or the CKM_HKDF_DERIVE mechanisms for this feature to be available.

Implement the Generic algorithm for SecretKeyFactory in the SunPKCS11 security provider according to the definition in CSR JDK-8346997.

Problem

The SunPKCS11 security provider does not support any HKDF algorithm for the KDF service type, even when the underlying PKCS #11 library supports the CKM_HKDF_DATA and CKM_HKDF_DERIVE mechanisms.

The lack of support hinders the possibility of deriving keys for TLS connections in hardware or software-based security modules, which is a requirement for FIPS-compliance.

As of JDK-8331009, SunPKCS11 is not at pair with SunJCE in terms of HKDF support. This detriments compatibility, exchange and cross-checking between the two providers.

Supporting HKDF in SunPKCS11 can bring actionable feedback for the KDF API (JEP 478) while in Preview mode.

The PKCS #11 standard defines Generic Secret as a symmetric key type that serves multiple purposes (HMAC authentication, HKDF Initial Key Material, HKDF Salt, etc.). See more information in section 6.8 Generic secret key of the PKCS #11 v3.1 standard. Contrary to other key types, Generic Secret keys generally offer more flexibility for key lengths. Keys of the Generic type are represented by the CKK_GENERIC_SECRET PKCS #11 native constant. CSR JDK-8346997 defined the Generic algorithm for the SecretKeyFactory JCA engine, but SunPKCS11 does not provide an implementation yet. JCA engines often receive SecretKeySpec instances and internally create keys in the PKCS #11 library, but this does not allow the Java application to fully control the key's life cycle as it is created for a specific purpose and its handle may never be returned. This problem is more visible with Hardware Security Modules in which keys are expected to be created once and re-used multiple times.

Solution

Enhance the SunPKCS11 provider to support the following HKDF algorithms in services of the KDF type:

• HKDF-SHA256
• HKDF-SHA384
• HKDF-SHA512

For HKDF algorithms to be available in SunPKCS11, the PKCS #11 library must support either the CKM_HKDF_DATA or the CKM_HKDF_DERIVE mechanisms. While not specified in the PKCS # 11 standard, it is reasonable to assume that the availability of each specific HKDF algorithm is related to its HMAC counterpart. For example, for HKDF-SHA512 to be available, the PKCS #11 library must support the CKM_SHA512_HMAC native mechanism. Thus, for HKDF-SHA256 SunPKCS11 will require CKM_SHA256_HMAC, for HKDF-SHA384 will require CKM_SHA384_HMAC and so on.

If the previous requirements are not met, SunPKCS11 will not register the algorithms, throw NoSuchAlgorithmException when KDF::getInstance(hkdf-algorithm, sunpkcs11-provider) is invoked and return null in Provider::getService.

The concatenation of key and data material for Input Key Material (IKM) and salts requires the CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_BASE_AND_KEY and CKM_CONCATENATE_DATA_AND_BASE native mechanisms. However, SunPKCS11 will not enforce this check until run time. The reason is because key and data material concatenation is not necessarily used by every application and PKCS #11 libraries that do not implement it should still be supported.

HKDF support in SunPKCS11 will be enabled in Preview mode only. When the KDF API stabilizes in a future JDK release, the SunPKCS11 implementation will be promoted from Preview.

Implement support in the SunPKCS11 security provider for the Generic algorithm in the SecretKeyFactory JCA engine. The underlying PKCS #11 key type for Generic should be CKK_GENERIC_SECRET.

Specification

Make the following changes to the PKCS#11 Reference Guide.

Update Table 5-3 Java Algorithms Supported by the SunPKCS11 Provider to add the following rows:

In order to clarify the expected behavior and facilitate troubleshooting, add two paragraphs below Table 5-3 Java Algorithms Supported by the SunPKCS11 Provider with the following text:

HKDF algorithms in SunPKCS11 require either the CKM_HKDF_DATA or CKM_HKDF_DERIVE native mechanisms to be registered. If the PKCS #11 library does not support one of them, a run time failure will occur upon invoking the corresponding JDK API: KDF::deriveData for CKM_HKDF_DATA or KDF::deriveKey for CKM_HKDF_DERIVE.

The CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_BASE_AND_KEY and CKM_CONCATENATE_DATA_AND_BASE native mechanisms for key material concatenation are not required for HKDF algorithms support in SunPKCS11. A PKCS #11 library that does not implement these algorithms may be used with SunPKCS11 but a run time error will occur if key concatenation of the forms key-data, key-key or data-key is attempted. See HKDFParameterSpec.Builder::addIKM and HKDFParameterSpec.Builder::addSalt methods on HKDFParameterSpec for more information about key concatenation.

The update to the SecretKeyFactory section of the Standard Names document was done in the context of CSR JDK-8346997.