Update to JEP draft: Key Encapsulation Mechanism API

Wei-Jun Wang weijun.wang at oracle.com
Fri Mar 3 17:29:53 UTC 2023

Hi All,

The JEP draft was just updated again.

The major change is that there is no more DerivedKeyParameterSpec class. Maybe it's because of the name, but we found many people treating it as a place to configure the KDF used inside a KEM. Actually the only usage of it is to give caller a chance to wrap (possibly a portion of) the shared secret into a SecretKey.

Therefore we drop the class and directly put the fields in the argument list of the encapsulate method, i.e.

  encapsulate(int from, int to, String algorithm);

We also noticed that unlike traditional KEM algorithms (like RSA-KEM and ECIES) that allow a user to choose an arbitrary KDF output length so the generated shared secret can be directly used as a cipher key, modern KEM algorithms have a constant shared secret size, and the output of the KEM is usually passed into a KDF to generate more keys. Therefore we are now providing a shorter method


that simply returns a SecretKey containing the full shared secret with algorithm name "Generic".

We hope this shorter method will be mostly used, and the longer one that takes from, to, and algorithm as arguments is only used for the traditional use case where the shared secret is directly used as a cipher key. This longer method might not always be supported by every implementation. For example, in PKCS #11 only a recognized algorithm can be mapped into a valid key type, and the key length must match the key type. In fact, if you want to derive an AES key but the size of the shared secret is bigger than your preferred key size, it's always the leading bytes of the shared secret that are removed. This means you can call encapsulate(secretSize() - 32, secretSize(), "AES") but calling encapsulate(0, 32, "AES") will throw an UnsupportedOperationException.

> Please take a look. The updated JEP is still at https://openjdk.org/jeps/8301034.


More information about the security-dev mailing list