Server app managed custom resumption tickets/Client app managed resumption tickets over SChannel #5371

sm-msft · 2025-08-20T17:31:46Z

Description

SChannel in Windows 2025 and newer releases allows

Server app to generate/manage resumption tickets that can include custom Server application state
Client app to manage the resumption ticket blobs it receives from the server

These features help implement custom 1-RTT resumption tickets on SChannel server applications and custom resumption ticket handling on SChannel clients.

This PR adds support for these features and integrates it into existing MsQuic code that utilizes similar features supported in OpenSSL and quictls libraries. Bulk of these changes are in tls_schannel.c wrapper.

Where available (and when not explicitly disabled), MsQuic has been using the automatic SChannel 1-RTT resumption handling thus far and it would remain the default mechanism in the library.

This change introduces a new QUIC_CREDENTIAL_FLAG for SChannel use

for a server app to opt into exclusively managing custom application state tickets/resumption ticket issuance
for a client app to opt into exclusively managing resumption ticket reception and use.

An additional QUIC_CREDENTIAL_FLAG allows an app to turn disable the use of 1-RTT/resumption in SChannel.
These flags are available only under the preview features macro.

Methods added to tls_schannel.c and other wrappers help enable the new functionality on Server2025 and newer releases and also to target 1-RTT tests on the appropriate platforms.

This change is linked to these issues: #5307 and #5162

Testing

Existing 1-RTT unit tests, BVTs have been enabled for SChannel on Server2025+ and new unit tests are added for additional coverage in SChannel/OpenSSL/quictls.

Existing automatic resumption tests cover the default scenario and older Windows OS scenarios.

Documentation

Documentation has been added to the newly introduced credential flags.

…SChannel - Code to push/retrieve client resumption ticket over SChannel - Few corresponding test changes

…g explicit ticket management for SChannel - Refactored tls_schannel code to rx/tx resumption tickets/ session state only when the credential flag is enabled - If the app receiving ticket indicates error, it is logged but the TLS connection will proceed - Added further checks and fixed up code in tls_schannel to ensure all TLS tests pass - Refactored tls unit tests to include the new credential flag and enabled all unit tests for SChannel - Other minor refactoring

- Added comments - Fixed TLS resumption unit tests (ignored scnearios/bugs) - Added many unit tests to cover the various resumption scenarios - Minor refactoring

- Minor refactoring

…w flag

- Fix up comments/documentation

- Update some traces and CLOG sidecar

…propriate init path - Clear buffers/buffer length at initialization - Clear buffer length after a ticket/app state is delivered - Add new series of e2e tests for non-zero length app resumption states for the new Schannel scenarios

…o missing library support - Unit tests that rely on empty tickets being indicated are moved back into OpenSSL-only category

sm-msft · 2025-08-20T17:35:10Z

This draft PR was used to develop this change: #5311

codecov · 2025-08-20T18:07:49Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.59%. Comparing base (591b7db) to head (93cd305).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5371      +/-   ##
==========================================
- Coverage   86.71%   85.59%   -1.12%     
==========================================
  Files          59       59              
  Lines       18328    18328              
==========================================
- Hits        15893    15688     -205     
- Misses       2435     2640     +205

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

csujedihy · 2025-08-21T23:38:51Z

src/platform/tls_schannel.c

+
+            if (TLSExtensionAllocated && AppSessionStateAllocated && SessionTicketAllocated) {
                break;
            }


Is this check still needed when you have the check below

if (!(Result & CXPLAT_TLS_RESULT_ERROR) && (TLSExtensionAllocated || AppSessionStateAllocated || SessionTicketAllocated)) { break; }

csujedihy · 2025-08-22T00:55:33Z

src/platform/tls_schannel.c

+    // Inline 1-RTT app state validation is not supported on Windows
+    //
+    return FALSE;
+}


What does "Inline 1-RTT app state validation" mean?

guhetier

Review in progress

guhetier · 2025-08-27T00:53:06Z

src/test/bin/quic_gtest.cpp


+extern "C"
+BOOLEAN
+CxPlatSupportsTicketManagement();


Test should not use internal functions.
To skip tests, please use the pattern used below (QUIC_DISABLE_0RTT_TESTS) so it is controled as a test configuration.

guhetier · 2025-08-27T00:53:35Z

src/test/bin/quic_gtest.cpp

+    }
+    else {


Suggested change

}

else {

} else {

guhetier · 2025-08-27T01:00:23Z

src/test/lib/HandshakeTest.cpp

    _In_ MsQuicConfiguration& ClientConfiguration,
-    _Out_ QUIC_BUFFER** ResumptionTicket
+    _Out_ QUIC_BUFFER** ResumptionTicket,
+    _In_ bool TrueResume


I think a better name is needed. TrueResume is very vague. I think it means "send a non-empty resume ticket"? A name capturing this would be better.

csujedihy · 2025-08-27T01:28:03Z

src/platform/tls_schannel.c

+    //
+    // Received application session state on the server, typically notified to the server app.
+    //
+    PSEC_APP_SESSION_STATE RxAppSessionState;


Can we have "client" and "server" in the name for these variables? It's a little difficult to follow when looking at how they are used.

Maybe we can match the bit flags defined above?

guhetier

Review in progress

guhetier · 2025-08-27T16:14:43Z

src/inc/msquic.h

+
+#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
+
+    QUIC_CREDENTIAL_FLAG_DISABLE_RESUMPTION                     = 0x00400000, // TODO: Combine this with CXPLAT_TLS_CREDENTIAL_FLAG_DISABLE_RESUMPTION


TODO to be solved before merging.

guhetier · 2025-08-27T16:25:29Z

src/test/bin/quic_gtest.cpp

+            memcpy(&ServerSelfSignedCredConfigSChannelResumption, SelfSignedCertParams, sizeof(QUIC_CREDENTIAL_CONFIG));
            memcpy(&ServerSelfSignedCredConfigClientAuth, SelfSignedCertParams, sizeof(QUIC_CREDENTIAL_CONFIG));
+
+#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES


Question: Do we actually need this ifdef?
As far as I know:

test code is always compiled with QUIC_API_ENABLE_PREVIEW_FEATURES

preview features implementation is always compiled in MsQuic, QUIC_API_ENABLE_PREVIEW_FEATURES only control the visibility of definitions in the header

These uses of QUIC_API_ENABLE_PREVIEW_FEATURES in test code might be a remain from the past and not have any effect.

guhetier · 2025-08-27T16:28:42Z

src/test/bin/quic_gtest.cpp

+    }
+
+#ifndef QUIC_API_ENABLE_PREVIEW_FEATURES
+    GTEST_SKIP_("Resumption ticket management is not supported in this build.");


That skip reason is misleading, the build always support preview features.

guhetier · 2025-08-27T16:34:24Z

src/test/bin/quic_gtest.cpp

+    return CxPlatSupportsTicketManagement();
+}
+
+TEST_P(WithHandshakeArgs1, TrueResume) {


Please adapt the test name to describe what is tested here. If needed, feel free to change the Resume test name above to make it clear what the difference is.

guhetier · 2025-08-27T16:37:11Z

src/test/lib/HandshakeTest.cpp

    struct PrimeResumption {
        CxPlatEvent ShutdownEvent;
        MsQuicConnection* Connection {nullptr};
+        bool TrueResume;


This is a C++ struct, please intialize this

guhetier · 2025-08-27T17:55:48Z

src/platform/tls_schannel.c

        //
-        // If the input length is zero, then we are initializing the client
-        // side, and have a few special differences in this code path.
+        // Call to encode ticket data has different ordering of inputs and different inputs as well.


I don't understand this comment. Different from what? It would be more helpfult to explain the ordering needs in for the different scenarios

guhetier · 2025-08-27T17:58:09Z

src/platform/tls_schannel.c

+
+    if (ManagedResumptionTickets) {
+        //
+        // Explicit session management is in force for this context.


"in force": is this a typo? Did you mean "enforced"?

guhetier · 2025-08-27T18:02:43Z

src/platform/tls_schannel.c

    }
 #endif

+    if (AppSessionState != NULL) {


:O that function is so long, I had to scroll forever to find this cleanup.
We should break it down somehow (not for this PR)

guhetier · 2025-08-27T18:03:25Z

src/platform/tls_schannel.c

+        !AreResumptionTicketsManaged(TlsContext->SecConfig->Flags)){
        //
-        // Schannel currently sends the NST after receiving client finished.
+        // Older client behavior: Schannel sends the NST after receiving client finished.


What is "older" in this context?

This isn't client behavior. Sending NST after receiving client finished is a server behavior. Its still the case, I believe, because NSTs can only be sent from the server after handshake but now the server with active management can defer sending the ticket. This piece of code fakes a ticket received event for schannel.

guhetier · 2025-08-27T18:05:41Z

src/platform/tls_schannel.c

+            //
+            // Client session state ticket is delivered only once.
+            //
+            TlsContext->RxSessionTicket->SessionTicketSize = 0;


Shouldn't we free the memory too in this case?

sm-msft added 21 commits July 18, 2025 01:01

Bump up default windows sdk version used in Windows builds

d5b8e97

Add WinSDK version requirement to Build doc.

9ac6c8e

- Code to push/retrieve server app state in a resumption ticket over …

d82b5ed

…SChannel - Code to push/retrieve client resumption ticket over SChannel - Few corresponding test changes

Merge branch 'main' into sm/msquic_schannel_resumption1

04285f8

Merge branch 'main' into sm/msquic_schannel_resumption1

fe6fb17

- Fixed corner cases in notifying received tickets

622a9f2

- Added comments - Fixed TLS resumption unit tests (ignored scnearios/bugs) - Added many unit tests to cover the various resumption scenarios - Minor refactoring

- Skip an unit test on OpenSSL

bcf69d9

- Minor refactoring

Fix OpenSSL build issue

efc43d3

- Add documentation for the newly added credential flags under previe…

78394f4

…w flag

- Clean up CxPlatTlsWriteDataToSchannel and other related refactoring

88fd266

- Fix up comments/documentation

- Restore default rx ticket notification to prior location

9a2c2c2

Rearrange when empty tickets are indicated on the client and server

3cef739

- Update rust bindings

6038a0d

- Update some traces and CLOG sidecar

- Apply rust bindings patch

6961f27

- Fix build errors in kernel test code

2543239

Fix build break

fe962d3

- Address more test build failures

8239307

- Empty tickets will not be indicated on SChannel client/server due t…

33ae9db

…o missing library support - Unit tests that rely on empty tickets being indicated are moved back into OpenSSL-only category

Merge branch 'main' into sm/msquic_schannel_resumption1

93cd305

sm-msft requested a review from a team as a code owner August 20, 2025 17:31

sm-msft requested a review from anrossi August 20, 2025 17:35

csujedihy reviewed Aug 21, 2025

View reviewed changes

csujedihy reviewed Aug 22, 2025

View reviewed changes

guhetier reviewed Aug 27, 2025

View reviewed changes

csujedihy reviewed Aug 27, 2025

View reviewed changes

guhetier reviewed Aug 27, 2025

View reviewed changes


		#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES

		QUIC_CREDENTIAL_FLAG_DISABLE_RESUMPTION = 0x00400000, // TODO: Combine this with CXPLAT_TLS_CREDENTIAL_FLAG_DISABLE_RESUMPTION

Server app managed custom resumption tickets/Client app managed resumption tickets over SChannel #5371

Are you sure you want to change the base?

Server app managed custom resumption tickets/Client app managed resumption tickets over SChannel #5371

Uh oh!

Conversation

sm-msft commented Aug 20, 2025 • edited by anrossi Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Documentation

Uh oh!

sm-msft commented Aug 20, 2025

Uh oh!

codecov bot commented Aug 20, 2025

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guhetier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

csujedihy Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guhetier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sm-msft commented Aug 20, 2025 •

edited by anrossi

Loading

csujedihy Aug 27, 2025 •

edited

Loading