Draft design for Key Derivation API

[Michael StJohns]

On 11/3/2017 4:59 PM, Jamil Nimeh wrote:
> Hello all,
>
> This is a review request for the draft of a new Key Derivation API.  
> The goal of this API will be to provide a framework for KDF algorithms 
> like HKDF, TLS-PRF, PBKDF2 and so forth to be publicly accessible.  We 
> also plan to provide an SPI that let 3rd parties create their own 
> implementations of KDFs in their providers, rather than trying to 
> force them into KeyGenerators, SecretKeyFactories and the like.
>
> Rather than stuff this email full of the specification text (since it 
> is likely to get quite a few iterations of comments and 
> comments-to-comments), I have placed the API both in simple text form 
> and as a Javadoc at the following locations:
>
> spec: http://cr.openjdk.java.net/~jnimeh/reviews/kdfspec/kdfspec.01.txt
>
> javadoc: http://cr.openjdk.java.net/~jnimeh/reviews/kdfspec/javadoc.01/
>
> They're both the same content, just use whichever is friendlier for 
> your eyes.
>
> In addition, I have opened up the JEP as well:
>
> https://bugs.openjdk.java.net/browse/JDK-8189808
>
> Thanks to those who have contributed to very early internal drafts of 
> this so far, and thanks in advance to those who will be contributing 
> comments going forward.
>
> --Jamil
>
>
Most of the following suggestions (and please take them as such 
regardless of any directive language) represent things I've had to do 
manually that I'd really prefer to do in a real key derivation API.  A 
few are related to how to keep things securely stored in an HSM.

Add a .reset() method to KeyDerivation.  Call this to clear the state of 
the KDF.

Add an .initialize(List<DerivationParameterSpec>, SecretKey 
masterSecret) method.  Remove the argument to deriveKey and deriveKeys.  
This plays with the stuff to follow, but basically, a KDF may need all 
of the per-key derivation input to calculate the total length of the 
output key stream as an internal input to the KDF before ever emitting a 
single key.   Also - how exactly were you planning on keying the KDF?  I 
guess you could pass that in in the KeyDerivation.getInstance() call or 
as part of the algorithmParameter but.... probably makes more sense to 
keep the KDF instance key-free to allow for reuse.

Rename DerivedKeyParameterSpec to DeriviationParameterSpec and provide 
an algorithm name for "IV" or "Cleartext".  See below for .deriveData()

deriveKey() emits the next key in the sequence using the data stream to 
key conversion rules.

deriveKeys() emits as many keys left in the stream to the next data 
derivation or the defined end of stream based on the input specs.  
deriveKeys(int num) derives the next num keys.

Add a .deriveData() with a return class of byte[].   This gets a portion 
of the derived data stream in the clear. E.g. an IV.

Add a .deriveObject() with a return class of Object.  The returned 
object may not be an instance of java.security.Key.  This takes the 
derived data stream and converts it into the object type specified by 
the derivation parameter.  In a hardware security module, this might be 
a reference to a secured set of data or even an confidential IV.

All of the derive methods throw an InvalidParameterSpecException if the 
next derivation parameter doesn't match the calling method (e.g. trying 
to deriveData when the parameter spec says emit a key).

In KeyDerivation, change the output class of the deriveKey to 
java.security.Key; similar for deriveKeys change the output to 
List<Key>.   Basically, its possible to use the output of a KDF stream 
to derive private keys and this should be supported. It's occasionally 
helpful (but not very often) for two devices to share a key pair that 
they create through a key agreement process (e.g. two HSMs acting as 
backup to each other).  Alternately, consider adding a "public KeyPair 
deriveKeyPair()" method.

Consider adding a marker interface  javax.crypto.MasterSecret (subclass 
of javax.crypto.SecretKey) and using that as class for the initialize 
call argument.

I'm happy to provide an edited .java file with these proposed changes - 
but not until at least next Monday; I'm on travel.

Mike