Add support for keying material export (#6134)

## Description

Adds a new preview API, `ConnectionExportKeyingMaterial`, letting
applications export TLS keying material per RFC 5705 / RFC 8446 §7.5
(label + optional context). Requested by Azure SQL to authenticate
connections. Supported by the user-mode TLS providers (Schannel,
OpenSSL/quictls); kernel mode returns `QUIC_STATUS_NOT_SUPPORTED`. The
API runs inline when the calling thread is safe, otherwise queues a
connection operation, and exits early with `QUIC_STATUS_INVALID_STATE`
if the TLS context is gone.

## Testing

New tests: parameter/state validation (`ApiTest.cpp`), functional
cross-peer export over a live connection (`HandshakeTest.cpp`), and RFC
5705 exporter properties at the TLS layer (`TlsTest.cpp`). All run in UM
and KM (KM validates the `NOT_SUPPORTED` path).

## Documentation

Public API declared in `msquic.h` (preview) with a C++ wrapper in
`msquic.hpp`.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: guhetier

docs/api/ConnectionExportKeyingMaterial.md

@@ -0,0 +1,63 @@
+ConnectionExportKeyingMaterial function
+======
+
+Exports keying material derived from the connection's TLS session, as described in [RFC 5705](https://www.rfc-editor.org/rfc/rfc5705) and [RFC 8446 Section 7.5](https://www.rfc-editor.org/rfc/rfc8446#section-7.5).
+The exported material is bound to the TLS session and can be used by the app for its own purposes (for example, to authenticate the peer at the application layer).
+
+> **Note** - This API is in [preview](../PreviewFeatures.md). It should be considered unstable and can be subject to breaking changes.
+
+# Syntax
+
+```C
+typedef
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+(QUIC_API * QUIC_CONNECTION_EXPORT_KEYING_MATERIAL_FN)(
+    _In_ _Pre_defensive_ HQUIC Connection,
+    _In_ _Pre_defensive_ const QUIC_KEYING_MATERIAL_CONFIG* Config,
+    _Out_writes_bytes_(Config->OutputLength)
+        uint8_t* Output
+    );
+```
+
+# Parameters
+
+`Connection`
+
+The valid handle to an open and connected connection object.
+
+`Config`
+
+A pointer to a [QUIC_KEYING_MATERIAL_CONFIG](QUIC_KEYING_MATERIAL_CONFIG.md) that specifies the label, optional context, and the number of bytes to export.
+
+`Output`
+
+A caller-allocated buffer of at least `Config->OutputLength` bytes that receives the exported keying material on success. Its contents are undefined if the call fails.
+
+# Return Value
+
+The function returns a [QUIC_STATUS](QUIC_STATUS.md). The app may use `QUIC_FAILED` or `QUIC_SUCCEEDED` to determine if the function failed or succeeded.
+
+The following errors are the most likely to be returned:
+
+Value | Meaning
+--- | ---
+**QUIC_STATUS_SUCCESS** | The keying material was exported into `Output`.
+**QUIC_STATUS_INVALID_PARAMETER** | `Config`, `Config->Label`, or `Output` is NULL; `Config->OutputLength` is 0; `Config->Context` is NULL while `Config->ContextLength` is non-zero; or `Connection` is not a connection handle.
+**QUIC_STATUS_INVALID_STATE** | The connection's TLS context is no longer available. This happens if the handshake has not completed yet, or if it has already been released after handshake completion (see Remarks).
+**QUIC_STATUS_NOT_SUPPORTED** | The underlying TLS provider does not support exporting keying material. This is the case in kernel mode.
+
+# Remarks
+
+The keying material can only be exported once the handshake is completed and while the connection's TLS context is alive.
+On a server, the TLS context is is released shortly after the handshake completes (unless resumption tickets are used)
+
+This API is best called inline while handling the `QUIC_CONNECTION_EVENT_CONNECTED` event to ensure the TLS context is still alive.
+Calling it later may return `QUIC_STATUS_INVALID_STATE` if the context has already been released.
+
+This API is not supported for Windows Kernel Mode, where it returns `QUIC_STATUS_NOT_SUPPORTED`.
+
+# See Also
+
+[QUIC_KEYING_MATERIAL_CONFIG](QUIC_KEYING_MATERIAL_CONFIG.md)<br>
+[QUIC_CONNECTION_EVENT](QUIC_CONNECTION_EVENT.md)<br>

docs/api/ExecutionCreate.md

@@ -0,0 +1,8 @@
+ExecutionCreate function
+======
+
+TODO
+
+# See Also
+
+[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

docs/api/ExecutionDelete.md

@@ -0,0 +1,8 @@
+ExecutionDelete function
+======
+
+TODO
+
+# See Also
+
+[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

docs/api/ExecutionPoll.md

@@ -0,0 +1,8 @@
+ExecutionPoll function
+======
+
+TODO
+
+# See Also
+
+[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

docs/api/QUIC_API_TABLE.md

@@ -47,6 +47,30 @@ typedef struct QUIC_API_TABLE {
 
     QUIC_DATAGRAM_SEND_FN               DatagramSend;
 
+    QUIC_CONNECTION_COMP_RESUMPTION_FN  ConnectionResumptionTicketValidationComplete; // Available from v2.2
+    QUIC_CONNECTION_COMP_CERT_FN        ConnectionCertificateValidationComplete;      // Available from v2.2
+
+    QUIC_CONNECTION_OPEN_IN_PARTITION_FN
+                                        ConnectionOpenInPartition;   // Available from v2.5
+
+#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
+    QUIC_STREAM_PROVIDE_RECEIVE_BUFFERS_FN
+                                        StreamProvideReceiveBuffers; // Available from v2.5
+
+    QUIC_CONN_POOL_CREATE_FN            ConnectionPoolCreate;        // Available from v2.5
+
+#ifndef _KERNEL_MODE
+#define QUIC_API_EXECUTION_CONTEXT
+    QUIC_EXECUTION_CREATE_FN            ExecutionCreate;    // Available from v2.5
+    QUIC_EXECUTION_DELETE_FN            ExecutionDelete;    // Available from v2.5
+    QUIC_EXECUTION_POLL_FN              ExecutionPoll;      // Available from v2.5
+#endif // _KERNEL_MODE
+    QUIC_REGISTRATION_CLOSE2_FN         RegistrationClose2; // Available from v2.6
+
+    QUIC_CONNECTION_EXPORT_KEYING_MATERIAL_FN
+                                        ConnectionExportKeyingMaterial; // Available from v2.6
+#endif // QUIC_API_ENABLE_PREVIEW_FEATURES
+
 } QUIC_API_TABLE;
 ```
 
@@ -172,6 +196,42 @@ See [StreamReceiveSetEnabled](StreamReceiveSetEnabled.md)
 
 See [DatagramSend](DatagramSend.md)
 
+`ConnectionResumptionTicketValidationComplete`
+
+See [ConnectionResumptionTicketValidationComplete](ConnectionResumptionTicketValidationComplete.md)
+
+`ConnectionCertificateValidationComplete`
+
+See [ConnectionCertificateValidationComplete](ConnectionCertificateValidationComplete.md)
+
+`ConnectionOpenInPartition`
+
+See [ConnectionOpenInPartition](ConnectionOpenInPartition.md)
+
+`StreamProvideReceiveBuffers`
+
+See (Preview) [StreamProvideReceiveBuffers](StreamProvideReceiveBuffers.md)
+
+`ConnectionPoolCreate`
+
+See (Preview) [ConnectionPoolCreate](ConnectionPoolCreate.md)
+
+`ExecutionCreate`
+
+See (Preview) [ExecutionCreate](ExecutionCreate.md)
+
+`ExecutionDelete`
+
+See (Preview) [ExecutionDelete](ExecutionDelete.md)
+
+`ExecutionPoll`
+
+See (Preview) [ExecutionPoll](ExecutionPoll.md)
+
+`ConnectionExportKeyingMaterial`
+
+See (Preview) [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md)
+
 # See Also
 
 [MsQuicOpen2](MsQuicOpen2.md)<br>

docs/api/QUIC_KEYING_MATERIAL_CONFIG.md

@@ -0,0 +1,43 @@
+QUIC_KEYING_MATERIAL_CONFIG structure
+======
+
+The structure used to configure a call to [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md).
+
+> **Note** - This API is in [preview](../PreviewFeatures.md). It should be considered unstable and can be subject to breaking changes.
+
+# Syntax
+
+```C
+typedef struct QUIC_KEYING_MATERIAL_CONFIG {
+    _Field_z_ const char* Label;
+    uint32_t ContextLength;
+    _Field_size_bytes_opt_(ContextLength) const uint8_t* Context;
+    uint32_t OutputLength;
+} QUIC_KEYING_MATERIAL_CONFIG;
+```
+
+# Members
+
+`Label`
+
+A non-NULL, null-terminated ASCII string that disambiguates the exported keying material between different uses. Both peers must use the same label to derive the same material. See [RFC 5705](https://www.rfc-editor.org/rfc/rfc5705) for guidance on choosing a label.
+
+`ContextLength`
+
+The length, in bytes, of the buffer pointed to by `Context`. May be 0.
+
+`Context`
+
+An optional pointer to a `ContextLength`-byte context buffer that is mixed into the derivation, further scoping the exported material. May be NULL, in which case `ContextLength` must be 0.
+
+`OutputLength`
+
+The number of bytes of keying material to export. Must be non-zero. The `Output` buffer passed to [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md) must be at least this large.
+
+# Remarks
+
+Both peers of a connection derive identical keying material for the same `Label` and `Context`. Different labels or contexts produce independent, unrelated material.
+
+# See Also
+
+[ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md)<br>

src/core/api.c

@@ -676,6 +676,94 @@ MsQuicConnectionSendResumptionTicket(
     return Status;
 }
 
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+QUIC_API
+MsQuicConnectionExportKeyingMaterial(
+    _In_ _Pre_defensive_ HQUIC Handle,
+    _In_ _Pre_defensive_ const QUIC_KEYING_MATERIAL_CONFIG* Config,
+    _Out_writes_bytes_(Config->OutputLength)
+        uint8_t* Output
+    )
+{
+    QUIC_STATUS Status;
+    QUIC_CONNECTION* Connection;
+
+    CXPLAT_PASSIVE_CODE();
+
+    QuicTraceEvent(
+        ApiEnter,
+        "[ api] Enter %u (%p).",
+        QUIC_TRACE_API_CONNECTION_EXPORT_KEYING_MATERIAL,
+        Handle);
+
+    if (Config == NULL ||
+        Config->Label == NULL ||
+        Config->OutputLength == 0 ||
+        Output == NULL ||
+        (Config->Context == NULL && Config->ContextLength != 0) ||
+        !IS_CONN_HANDLE(Handle)) {
+        Status = QUIC_STATUS_INVALID_PARAMETER;
+        goto Error;
+    }
+
+#pragma prefast(suppress: __WARNING_25024, "Pointer cast already validated.")
+    Connection = (QUIC_CONNECTION*)Handle;
+
+    QUIC_CONN_VERIFY(Connection, !Connection->State.Freed);
+
+    if (MsQuicLib.CustomExecutions ||
+        Connection->WorkerThreadID == CxPlatCurThreadID()) {
+        //
+        // Execute this blocking API call inline if called on the worker thread.
+        //
+        BOOLEAN AlreadyInline = Connection->State.InlineApiExecution;
+        if (!AlreadyInline) {
+            Connection->State.InlineApiExecution = TRUE;
+        }
+        Status =
+            QuicConnExportKeyingMaterial(Connection, Config, Output);
+        if (!AlreadyInline) {
+            Connection->State.InlineApiExecution = FALSE;
+        }
+        goto Error;
+    }
+
+    //
+    // Queue the operation and wait for the worker to process it.
+    //
+    CXPLAT_EVENT CompletionEvent;
+    CxPlatEventInitialize(&CompletionEvent, TRUE, FALSE);
+
+    QUIC_API_CONTEXT ApiCtx;
+    ApiCtx.Type = QUIC_API_TYPE_CONN_EXPORT_KEYING_MATERIAL;
+    ApiCtx.Completed = &CompletionEvent;
+    ApiCtx.Status = &Status;
+    ApiCtx.CONN_EXPORT_KEYING_MATERIAL.Config = Config;
+    ApiCtx.CONN_EXPORT_KEYING_MATERIAL.Output = Output;
+
+    QUIC_OPERATION Oper = { 0 };
+    Oper.Type = QUIC_OPER_TYPE_API_CALL;
+    Oper.FreeAfterProcess = FALSE;
+    Oper.API_CALL.Context = &ApiCtx;
+
+    QuicConnQueueOper(Connection, &Oper);
+    QuicTraceEvent(
+        ApiWaitOperation,
+        "[ api] Waiting on operation");
+    CxPlatEventWaitForever(CompletionEvent);
+    CxPlatEventUninitialize(CompletionEvent);
+
+Error:
+
+    QuicTraceEvent(
+        ApiExitStatus,
+        "[ api] Exit %u",
+        Status);
+
+    return Status;
+}
+
 _IRQL_requires_max_(DISPATCH_LEVEL)
 QUIC_STATUS
 QUIC_API

src/core/api.h

@@ -214,6 +214,16 @@ MsQuicConnectionSendResumptionTicket(
         const uint8_t* ResumptionData
     );
 
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+QUIC_API
+MsQuicConnectionExportKeyingMaterial(
+    _In_ _Pre_defensive_ HQUIC Handle,
+    _In_ _Pre_defensive_ const QUIC_KEYING_MATERIAL_CONFIG* Config,
+    _Out_writes_bytes_(Config->OutputLength)
+        uint8_t* Output
+    );
+
 _IRQL_requires_max_(DISPATCH_LEVEL)
 QUIC_STATUS
 QUIC_API

src/core/connection.c

@@ -7775,6 +7775,42 @@ QuicConnApplyNewSettings(
     return TRUE;
 }
 
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+QuicConnExportKeyingMaterial(
+    _In_ QUIC_CONNECTION* Connection,
+    _In_ const QUIC_KEYING_MATERIAL_CONFIG* Config,
+    _Out_writes_bytes_(Config->OutputLength)
+        uint8_t* Output
+    )
+{
+    //
+    // The keying material is derived from the connection's TLS secrets: the
+    // handshake must be complete and the TLS context must still be present.
+    //
+    if (!Connection->State.Connected ||
+        !Connection->Crypto.TlsState.HandshakeComplete ||
+        Connection->Crypto.TLS == NULL) {
+        QuicTraceLogConnWarning(
+            ExportKeyingMaterialInvalidState,
+            Connection,
+            "Cannot export keying material [Connected=%hhu, HandshakeComplete=%hhu, HasTls=%hhu]",
+            Connection->State.Connected,
+            Connection->Crypto.TlsState.HandshakeComplete,
+            (uint8_t)(Connection->Crypto.TLS != NULL));
+        return QUIC_STATUS_INVALID_STATE;
+    }
+
+    return
+        CxPlatTlsExportKeyingMaterial(
+            Connection->Crypto.TLS,
+            Config->Label,
+            Config->Context,
+            Config->ContextLength,
+            Output,
+            Config->OutputLength);
+}
+
 _IRQL_requires_max_(PASSIVE_LEVEL)
 void
 QuicConnProcessApiOperation(
@@ -7932,6 +7968,14 @@ QuicConnProcessApiOperation(
         QuicDatagramSendFlush(&Connection->Datagram);
         break;
 
+    case QUIC_API_TYPE_CONN_EXPORT_KEYING_MATERIAL:
+        Status =
+            QuicConnExportKeyingMaterial(
+                Connection,
+                ApiCtx->CONN_EXPORT_KEYING_MATERIAL.Config,
+                ApiCtx->CONN_EXPORT_KEYING_MATERIAL.Output);
+        break;
+
     default:
         CXPLAT_TEL_ASSERT(FALSE);
         Status = QUIC_STATUS_INVALID_PARAMETER;

src/core/connection.h

@@ -1239,6 +1239,19 @@ QuicConnStart(
     _In_ QUIC_CONN_START_FLAGS StartFlags
     );
 
+//
+// Exports keying material derived from the connection's TLS session
+// (RFC 5705 / RFC 8446 section 7.5).
+//
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+QuicConnExportKeyingMaterial(
+    _In_ QUIC_CONNECTION* Connection,
+    _In_ const QUIC_KEYING_MATERIAL_CONFIG* Config,
+    _Out_writes_bytes_(Config->OutputLength)
+        uint8_t* Output
+    );
+
 //
 // Generates a new source connection ID.
 //