8331008: Implement JEP 478: Key Derivation Function API (Preview)

src/java.base/share/classes/javax/crypto/KDF.java

@@ -208,6 +208,14 @@ public KDFParameters getParameters() {
     /**
      * Returns a {@code KDF} object that implements the specified algorithm.
      *
+     * @implNote The JDK Reference Implementation additionally uses the
+     *         {@code jdk.security.provider.preferred}
+     *         {@link Security#getProperty(String) Security} property to
+     *         determine the preferred provider order for the specified
+     *         algorithm. This may be different than the order of providers
+     *         returned by
+     *         {@link Security#getProviders() Security.getProviders()}.
+     *
      * @param algorithm
      *         the key derivation algorithm to use. See the {@code KDF} section
      *         in the <a href="{@docRoot}/../specs/security/standard-names.html#kdf-algorithms">
@@ -221,13 +229,6 @@ public KDFParameters getParameters() {
      *         the specified algorithm
      * @throws NullPointerException
      *         if {@code algorithm} is {@code null}
-     * @implNote The JDK Reference Implementation additionally uses the
-     *         {@code jdk.security.provider.preferred}
-     *         {@link Security#getProperty(String) Security} property to
-     *         determine the preferred provider order for the specified
-     *         algorithm. This may be different than the order of providers
-     *         returned by
-     *         {@link Security#getProviders() Security.getProviders()}.
      * @see <a href="#DelayedProviderSelection">Delayed Provider
      *         Selection</a>
      */
@@ -314,6 +315,14 @@ public static KDF getInstance(String algorithm, Provider provider)
      * Returns a {@code KDF} object that implements the specified algorithm and
      * is initialized with the specified parameters.
      *
+     * @implNote The JDK Reference Implementation additionally uses the
+     *         {@code jdk.security.provider.preferred}
+     *         {@link Security#getProperty(String) Security} property to
+     *         determine the preferred provider order for the specified
+     *         algorithm. This may be different than the order of providers
+     *         returned by
+     *         {@link Security#getProviders() Security.getProviders()}.
+     *
      * @param algorithm
      *         the key derivation algorithm to use. See the {@code KDF} section
      *         in the <a href="{@docRoot}/../specs/security/standard-names.html#kdf-algorithms">
@@ -334,13 +343,6 @@ public static KDF getInstance(String algorithm, Provider provider)
      *         support the specified parameters
      * @throws NullPointerException
      *         if {@code algorithm} is {@code null}
-     * @implNote The JDK Reference Implementation additionally uses the
-     *         {@code jdk.security.provider.preferred}
-     *         {@link Security#getProperty(String) Security} property to
-     *         determine the preferred provider order for the specified
-     *         algorithm. This may be different than the order of providers
-     *         returned by
-     *         {@link Security#getProviders() Security.getProviders()}.
      * @see <a href="#DelayedProviderSelection">Delayed Provider
      *         Selection</a>
      */

src/java.base/share/classes/javax/crypto/KDFSpi.java

@@ -37,7 +37,7 @@
  * <p>
  * All the abstract methods in this class must be implemented by each
  * cryptographic service provider who wishes to supply the implementation of a
- * particular key derivation algorithm.
+ * particular key derivation function algorithm.
  * <p>
  * Implementations must provide a public constructor which accepts a {@code
  * KDFParameters} object if they depend on the default implementation of
@@ -110,6 +110,10 @@ protected KDFSpi(KDFParameters kdfParameters)
     /**
      * Derives a key, returned as a {@code SecretKey} object.
      *
+     * @implNote If the resultant key is extractable, then its
+     *         {@code getEncoded} value should have the same content as the
+     *         result of {@code deriveData}.
+     *
      * @param alg
      *         the algorithm of the resultant {@code SecretKey} object
      * @param derivationSpec
@@ -125,9 +129,6 @@ protected KDFSpi(KDFParameters kdfParameters)
      *         if {@code alg} is empty or invalid
      * @throws NullPointerException
      *         if {@code alg} or {@code derivationSpec} is null
-     * @implNote If the resultant key is extractable, then its
-     *         {@code getEncoded} value should have the same content as the
-     *         result of {@code deriveData}.
      */
     protected abstract SecretKey engineDeriveKey(String alg,
                                                  AlgorithmParameterSpec derivationSpec)

src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java

@@ -112,6 +112,11 @@ public Extract extractOnly() {
          * Builds an {@code ExtractThenExpand} object from the current state of
          * the {@code Builder}.
          *
+         * @implNote HKDF implementations will enforce that the length
+         *         is not greater than 255 * HMAC length. HKDF implementations
+         *         will also enforce that a {code null} info value is treated as
+         *         zero-length byte array.
+         *
          * @param info
          *         the optional context and application specific information
          *         (may be {@code null}); the byte array is cloned to prevent
@@ -120,14 +125,10 @@ public Extract extractOnly() {
          *         the length of the output keying material (must be greater
          *         than 0)
          *
-         * @return an {@code ExtractThenExpand} object
+         * @return an immutable {@code ExtractThenExpand} object
          *
          * @throws IllegalArgumentException
          *         if {@code length} is not greater than 0
-         * @implNote HKDF implementations will enforce that the length
-         *         is not greater than 255 * HMAC length. HKDF implementations
-         *         will also enforce that a {code null} info value is treated as
-         *         zero-length byte array.
          */
         public ExtractThenExpand thenExpand(byte[] info, int length) {
             return new ExtractThenExpand(
@@ -259,6 +260,12 @@ static Builder ofExtract() {
     /**
      * Creates an {@code Expand} object.
      *
+     * @implNote HKDF implementations will enforce that the length is
+     *         not greater than 255 * HMAC length. Implementations will also
+     *         enforce that the prk argument is at least as many bytes as the
+     *         HMAC length. Implementations will also enforce that a {code null}
+     *         info value is treated as zero-length byte array.
+     *
      * @param prk
      *         the pseudorandom key (PRK); must not be {@code null}
      * @param info
@@ -275,11 +282,6 @@ static Builder ofExtract() {
      *         if the {@code prk} argument is {@code null}
      * @throws IllegalArgumentException
      *         if {@code length} is not greater than 0
-     * @implNote HKDF implementations will enforce that the length is
-     *         not greater than 255 * HMAC length. Implementations will also
-     *         enforce that the prk argument is at least as many bytes as the
-     *         HMAC length. Implementations will also enforce that a {code null}
-     *         info value is treated as zero-length byte array.
      */
     static Expand expandOnly(SecretKey prk, byte[] info, int length) {
         if (prk == null) {
@@ -313,12 +315,12 @@ private Extract(List<SecretKey> ikms, List<SecretKey> salts) {
          * are converted to a {@code SecretKeySpec} object. Empty arrays are
          * discarded.
          *
-         * @return the unmodifiable {@code List} of input keying material
-         *         values
-         *
          * @implNote An HKDF implementation should concatenate the input
          *         keying materials into a single value to be used in
          *         HKDF-Extract.
+         *
+         * @return the unmodifiable {@code List} of input keying material
+         *         values
          */
         public List<SecretKey> ikms() {
             return ikms;
@@ -331,10 +333,10 @@ public List<SecretKey> ikms() {
          * Salt values added by {@link Builder#addSalt(byte[])} are converted to
          * a {@code SecretKeySpec} object. Empty arrays are discarded.
          *
-         * @return the unmodifiable {@code List} of salt values
-         *
-         * @implNote An HKDF implementation should concatenate the salt
+         * @implNote An HKDF implementation should concatenate the salts
          *         into a single value to be used in HKDF-Extract.
+         *
+         * @return the unmodifiable {@code List} of salt values
          */
         public List<SecretKey> salts() {
             return salts;
@@ -412,8 +414,8 @@ public int length() {
     }
 
     /**
-     * Defines the input parameters of an ExtractThenExpand operation as defined
-     * in <a href="http://tools.ietf.org/html/rfc5869">RFC 5869</a>.
+     * Defines the input parameters of an Extract-then-Expand operation as
+     * defined in <a href="http://tools.ietf.org/html/rfc5869">RFC 5869</a>.
      */
     @PreviewFeature(feature = PreviewFeature.Feature.KEY_DERIVATION)
     final class ExtractThenExpand implements HKDFParameterSpec {
@@ -454,12 +456,12 @@ private ExtractThenExpand(Extract ext, byte[] info, int length) {
          * are converted to a {@code SecretKeySpec} object. Empty arrays are
          * discarded.
          *
-         * @return the unmodifiable {@code List} of input keying material
-         *         values
-         *
          * @implNote An HKDF implementation should concatenate the input
          *         keying materials into a single value to be used in the
          *         HKDF-Extract phase.
+         *
+         * @return the unmodifiable {@code List} of input keying material
+         *         values
          */
         public List<SecretKey> ikms() {
             return ext.ikms();
@@ -472,10 +474,11 @@ public List<SecretKey> ikms() {
          * Salt values added by {@link Builder#addSalt(byte[])} are converted to
          * a {@code SecretKeySpec} object. Empty arrays are discarded.
          *
+         * @implNote An HKDF implementation should concatenate the salts
+         *         into a single value to be used in the HKDF-Extract phase.
+         *
          * @return the unmodifiable {@code List} of salt values
          *
-         * @implNote An HKDF implementation should concatenate the salt
-         *         into a single value to be used in the HKDF-Extract phase.
          */
         public List<SecretKey> salts() {
             return ext.salts();