8341346: Add support for exporting TLS Keying Material

src/java.base/share/classes/com/sun/crypto/provider/TlsPrfGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -147,7 +147,7 @@ protected void engineInit(int keysize, SecureRandom random) {
         throw new InvalidParameterException(MSG);
     }
 
-    SecretKey engineGenerateKey0(boolean tls12) {
+    protected SecretKey engineGenerateKey0(boolean tls12) {
         if (spec == null) {
             throw new IllegalStateException(
                 "TlsPrfGenerator must be initialized");
@@ -163,7 +163,7 @@ SecretKey engineGenerateKey0(boolean tls12) {
                     spec.getPRFBlockSize()) :
                 doTLS10PRF(secret, labelBytes, spec.getSeed(), n));
             try {
-                return new SecretKeySpec(prfBytes, "TlsPrf");
+                return new SecretKeySpec(prfBytes, spec.getKeyAlg());
             } finally {
                 Arrays.fill(prfBytes, (byte)0);
             }

src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package javax.net.ssl;
 
 import java.util.List;
+import javax.crypto.SecretKey;
 
 /**
  * Extends the {@code SSLSession} interface to support additional
@@ -163,4 +164,113 @@ public List<SNIServerName> getRequestedServerNames() {
     public List<byte[]> getStatusResponses() {
         throw new UnsupportedOperationException();
     }
+
+    /**
+     * Generates Exported Keying Material (EKM) calculated according to the
+     * algorithms defined in RFCs 5705/8446.
+     * <P>
+     * RFC 5705 (for (D)TLSv1.2 and earlier) calculates different EKM
+     * values depending on whether {@code context} is null or non-null/empty.
+     * RFC 8446 (TLSv1.3) treats a null context as non-null/empty.
+     * <P>
+     * {@code label} will be converted to bytes using
+     * the {@link java.nio.charset.StandardCharsets#UTF_8}
+     * character encoding.
+     *
+     * @spec https://www.rfc-editor.org/info/rfc5705
+     *     RFC 5705: Keying Material Exporters for Transport Layer
+     *     Security (TLS)
+     * @spec https://www.rfc-editor.org/info/rfc8446
+     *     RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
+     *
+     * @implSpec The default implementation throws
+     *           {@code UnsupportedOperationException}.
+     *
+     * @param keyAlg  the algorithm of the resultant {@code SecretKey} object.
+     *                See the SecretKey Algorithms section in the
+     *                <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+     *                Java Security Standard Algorithm Names Specification</a>
+     *                for information about standard secret key algorithm
+     *                names.
+     * @param label   the label bytes used in the EKM calculation.
+     *                {@code label} will be converted to a {@code byte[]}
+     *                before the operation begins.
+     * @param context the context bytes used in the EKM calculation, or null
+     * @param length  the number of bytes of EKM material needed
+     *
+     * @throws SSLKeyException if the key cannot be generated
+     * @throws IllegalArgumentException if {@code keyAlg} is empty,
+     *         {@code length} is non-positive, or if the {@code label} or
+     *         {@code context} length can not be accommodated
+     * @throws NullPointerException if {@code keyAlg} or {@code label} is null
+     * @throws IllegalStateException if this session does not have the
+     *         necessary key generation material (for example, a session
+     *         under construction during handshaking)
+     * @throws UnsupportedOperationException if the underlying provider
+     *         does not implement the operation
+     *
+     * @return a {@code SecretKey} that contains {@code length} bytes of the
+     *         EKM material
+     *
+     * @since 25
+     */
+    public SecretKey exportKeyingMaterialKey(String keyAlg,
+            String label, byte[] context, int length) throws SSLKeyException {
+        throw new UnsupportedOperationException(
+                "Underlying provider does not implement the method");
+    }
+
+    /**
+     * Generates Exported Keying Material (EKM) calculated according to the
+     * algorithms defined in RFCs 5705/8446.
+     * <P>
+     * RFC 5705 (for (D)TLSv1.2 and earlier) calculates different EKM
+     * values depending on whether {@code context} is null or non-null/empty.
+     * RFC 8446 (TLSv1.3) treats a null context as non-null/empty.
+     * <P>
+     * {@code label} will be converted to bytes using
+     * the {@link java.nio.charset.StandardCharsets#UTF_8}
+     * character encoding.
+     * <P>
+     * Depending on the chosen underlying key derivation mechanism, the
+     * raw bytes might not be extractable/exportable.  In such cases, the
+     * {@link #exportKeyingMaterialKey(String, String, byte[], int)} method
+     * should be used instead to access the generated key material.
+     *
+     * @spec https://www.rfc-editor.org/info/rfc5705
+     *     RFC 5705: Keying Material Exporters for Transport Layer
+     *     Security (TLS)
+     * @spec https://www.rfc-editor.org/info/rfc8446
+     *     RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
+     *
+     * @implSpec The default implementation throws
+     *           {@code UnsupportedOperationException}.
+     *
+     * @param label   the label bytes used in the EKM calculation.
+     *                {@code label} will be converted to a {@code byte[]}
+     *                before the operation begins.
+     * @param context the context bytes used in the EKM calculation, or null
+     * @param length  the number of bytes of EKM material needed
+     *
+     * @throws SSLKeyException if the key cannot be generated
+     * @throws IllegalArgumentException if {@code length} is non-positive,
+     *         or if the {@code label} or {@code context} length can
+     *         not be accommodated
+     * @throws NullPointerException if {@code label} is null
+     * @throws IllegalStateException if this session does not have the
+     *         necessary key generation material (for example, a session
+     *         under construction during handshaking)
+     * @throws UnsupportedOperationException if the underlying provider
+     *         does not implement the operation, or if the derived
+     *         keying material is not extractable
+     *
+     * @return a byte array of size {@code length} that contains the EKM
+     *         material
+     * @since 25
+     */
+    public byte[] exportKeyingMaterialData(
+            String label, byte[] context, int length) throws SSLKeyException {
+        throw new UnsupportedOperationException(
+                "Underlying provider does not implement the method");
+    }
 }

src/java.base/share/classes/sun/security/internal/spec/TlsPrfParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -45,6 +45,7 @@
 public class TlsPrfParameterSpec implements AlgorithmParameterSpec {
 
     private final SecretKey secret;
+    private final String keyAlg;
     private final String label;
     private final byte[] seed;
     private final int outputLength;
@@ -72,13 +73,45 @@ public class TlsPrfParameterSpec implements AlgorithmParameterSpec {
     public TlsPrfParameterSpec(SecretKey secret, String label,
             byte[] seed, int outputLength,
             String prfHashAlg, int prfHashLength, int prfBlockSize) {
-        if ((label == null) || (seed == null)) {
-            throw new NullPointerException("label and seed must not be null");
+        this(secret, "TlsPrf", label, seed, outputLength, prfHashAlg,
+                prfHashLength, prfBlockSize);
+    }
+
+    /**
+     * Constructs a new TlsPrfParameterSpec.
+     *
+     * @param secret the secret to use in the calculation (or null)
+     * @param keyAlg the algorithm name for the generated {@code SecretKey}
+     * @param label the label to use in the calculation
+     * @param seed the random seed to use in the calculation
+     * @param outputLength the length in bytes of the output key to be produced
+     * @param prfHashAlg the name of the TLS PRF hash algorithm to use.
+     *        Used only for TLS 1.2+.  TLS1.1 and earlier use a fixed PRF.
+     * @param prfHashLength the output length of the TLS PRF hash algorithm.
+     *        Used only for TLS 1.2+.
+     * @param prfBlockSize the input block size of the TLS PRF hash algorithm.
+     *        Used only for TLS 1.2+.
+     *
+     * @throws NullPointerException if keyAlg, label or seed is null
+     * @throws IllegalArgumentException if outputLength is negative or
+     *         keyAlg is empty
+     */
+    public TlsPrfParameterSpec(SecretKey secret, String keyAlg,
+            String label, byte[] seed, int outputLength,
+            String prfHashAlg, int prfHashLength, int prfBlockSize) {
+
+        if ((keyAlg == null) || (label == null) || (seed == null)) {
+            throw new NullPointerException(
+                    "keyAlg, label or seed must not be null");
+        }
+        if (keyAlg.isEmpty()) {
+            throw new IllegalArgumentException("keyAlg can not be empty");
         }
         if (outputLength <= 0) {
             throw new IllegalArgumentException("outputLength must be positive");
         }
         this.secret = secret;
+        this.keyAlg = keyAlg;
         this.label = label;
         this.seed = seed.clone();
         this.outputLength = outputLength;
@@ -87,6 +120,15 @@ public TlsPrfParameterSpec(SecretKey secret, String label,
         this.prfBlockSize = prfBlockSize;
     }
 
+    /**
+     * Returns the key algorithm name to use when generating the SecretKey.
+     *
+     * @return the key algorithm name
+     */
+    public String getKeyAlg() {
+        return keyAlg;
+    }
+
     /**
      * Returns the secret to use in the PRF calculation, or null if there is no
      * secret.

src/java.base/share/classes/sun/security/ssl/Finished.java

@@ -745,6 +745,12 @@ private byte[] onProduceFinished(ClientHandshakeContext chc,
                         "Failure to derive application secrets", gse);
             }
 
+            // Calculate/save the exporter_master_secret.  It uses
+            // the same handshakeHash as the client/server app traffic.
+            SecretKey exporterSecret = kd.deriveKey(
+                    "TlsExporterMasterSecret");
+            chc.handshakeSession.setExporterMasterSecret(exporterSecret);
+
             // The resumption master secret is stored in the session so
             // it can be used after the handshake is completed.
             SSLSecretDerivation sd = ((SSLSecretDerivation) kd).forContext(chc);
@@ -1099,6 +1105,12 @@ private void onConsumeFinished(ServerHandshakeContext shc,
                 shc.baseReadSecret = readSecret;
                 shc.conContext.inputRecord.changeReadCiphers(readCipher);
 
+                // Calculate/save the exporter_master_secret.  It uses
+                // the same handshakeHash as the client/server app traffic.
+                SecretKey exporterSecret = kd.deriveKey(
+                        "TlsExporterMasterSecret");
+                shc.handshakeSession.setExporterMasterSecret(exporterSecret);
+
                 // The resumption master secret is stored in the session so
                 // it can be used after the handshake is completed.
                 shc.handshakeHash.update();