Skip to content

Commit 06bd751

Browse files
wfurtDeagleGrossCopilot
authored
Add low-level TLS state machine API (TlsContext / TlsSession) (#130366)
Introduce a caller-driven, non-blocking TLS state machine API for System.Net.Security, enabling high-performance scenarios where the caller controls buffer management and I/O scheduling. fixes #128871 supports Linux, macOS, Windows & FreeBSD This is initial submit (already too big) to expose the approved API surface. I will work on cleanup & integration with SslStream once this lands. --------- Co-authored-by: Dmitrii Korolev <deagle.gross@gmail.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3d22b61a-2dc4-4417-ab8a-54529a87c655
1 parent 3e64752 commit 06bd751

42 files changed

Lines changed: 8088 additions & 272 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/project/list-of-diagnostics.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,4 +330,5 @@ Diagnostic id values for experimental APIs must not be recycled, as that could s
330330
| __`SYSLIB5004`__ | .NET 9 | TBD | `X86Base.DivRem` is experimental since performance is not as optimized as `T.DivRem` |
331331
| __`SYSLIB5005`__ | .NET 9 | .NET 10 | `System.Formats.Nrbf` is experimental |
332332
| __`SYSLIB5006`__ | .NET 10 | TBD | Types for Post-Quantum Cryptography (PQC) are experimental. |
333+
| __`SYSLIB5007`__ | .NET 11 | TBD | Low-level TLS engine types (`TlsContext`, `TlsSession`) in `System.Net.Security` are experimental. |
333334
| __`SYSLIB5008`__ | .NET 11 | TBD | `SocketsHttpHandler` connection eviction control and `HttpRequestMessage.ConnectionId` APIs are experimental. |

‎src/libraries/Common/src/Interop/OSX/Interop.NetworkFramework.Tls.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ internal static unsafe partial bool Init(
2828

2929
// Create a new connection context
3030
[LibraryImport(Interop.Libraries.AppleCryptoNative, EntryPoint = "AppleCryptoNative_NwConnectionCreate", StringMarshalling = StringMarshalling.Utf8)]
31-
internal static unsafe partial SafeNwHandle NwConnectionCreate([MarshalAs(UnmanagedType.I4)] bool isServer, IntPtr context, string targetName, byte* alpnBuffer, int alpnLength, SslProtocols minTlsProtocol, SslProtocols maxTlsProtocol, uint* cipherSuites, int cipherSuitesLength);
31+
internal static unsafe partial SafeNwHandle NwConnectionCreate([MarshalAs(UnmanagedType.I4)] bool isServer, IntPtr context, string targetName, byte* alpnBuffer, int alpnLength, SslProtocols minTlsProtocol, SslProtocols maxTlsProtocol, uint* cipherSuites, int cipherSuitesLength, IntPtr serverIdentity);
3232

3333
// Start the TLS handshake, notifications are received via the status callback (potentially from a different thread).
3434
[LibraryImport(Interop.Libraries.AppleCryptoNative, EntryPoint = "AppleCryptoNative_NwConnectionStart")]

‎src/libraries/Common/src/Interop/Unix/System.Security.Cryptography.Native/Interop.OpenSsl.cs‎

Lines changed: 159 additions & 105 deletions
Large diffs are not rendered by default.

‎src/libraries/Common/src/Interop/Unix/System.Security.Cryptography.Native/Interop.Ssl.cs‎

Lines changed: 122 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
using System.Collections.ObjectModel;
77
using System.Diagnostics;
88
using System.Net.Security;
9+
using System.Net.Sockets;
910
using System.Runtime.CompilerServices;
1011
using System.Runtime.InteropServices;
1112
using System.Runtime.InteropServices.Marshalling;
@@ -117,6 +118,15 @@ internal static unsafe ushort[] GetDefaultSignatureAlgorithms()
117118
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslSetBio")]
118119
internal static partial void SslSetBio(SafeSslHandle ssl, SafeBioHandle rbio, SafeBioHandle wbio);
119120

121+
// The OpenSSL shims below report errors via out params + the OpenSSL error
122+
// queue (SSL_get_error / ERR_get_error); they do not set errno. SetLastError is
123+
// omitted so we don't pay the marshaller cost of capturing a value no caller reads.
124+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslSetFd")]
125+
internal static partial int SslSetFd(SafeSslHandle ssl, SafeSocketHandle socket);
126+
127+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslDoHandshake")]
128+
internal static partial int SslDoHandshake(SafeSslHandle ssl, out SslErrorCode error);
129+
120130
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslHandshake", SetLastError = true)]
121131
internal static unsafe partial int SslHandshake(
122132
SafeSslHandle ssl,
@@ -166,6 +176,38 @@ internal static unsafe partial int SslDecrypt(
166176
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_BioNewManagedSpan")]
167177
internal static partial SafeBioHandle BioNewManagedSpan();
168178

179+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_BioNewSocketReplay")]
180+
private static unsafe partial SafeBioHandle BioNewSocketReplay(IntPtr fd, byte* prefix, int prefixLen);
181+
182+
internal static unsafe SafeBioHandle BioNewSocketReplay(SafeSocketHandle socket, ReadOnlySpan<byte> prefix)
183+
{
184+
fixed (byte* pPrefix = prefix)
185+
{
186+
return BioNewSocketReplay(socket.DangerousGetHandle(), pPrefix, prefix.Length);
187+
}
188+
}
189+
190+
// Reads directly from the BIO's bound fd into its internal peek buffer until a
191+
// full TLS record is present. Returns:
192+
// 1 = have full frame; framePtr / frameLen point into the BIO's buffer.
193+
// 0 = need more data (fd would block); caller polls SelectRead and retries.
194+
// -1 = error (EOF, oversized record, or recv failure).
195+
//
196+
// The returned pointer is valid until the BIO is destroyed or SocketReplayBioRead
197+
// starts consuming the buffer (i.e. once SSL_do_handshake runs against this BIO).
198+
// Callers must span-wrap and parse before creating the SSL* that owns the BIO.
199+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_BioPeekTlsFrame")]
200+
internal static unsafe partial int BioPeekTlsFrame(SafeBioHandle bio, out byte* framePtr, out int frameLen);
201+
202+
// Returns the socket-replay BIO's retained peek buffer (bytes captured by
203+
// BioPeekTlsFrame). Valid until the BIO is destroyed, even after OpenSSL has
204+
// drained it during handshake.
205+
// 1 = prefix present; prefixPtr / prefixLen wrap the internal buffer.
206+
// 0 = BIO has no captured prefix.
207+
// -1 = error (invalid args).
208+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_BioGetReplayPrefix")]
209+
internal static unsafe partial int BioGetReplayPrefix(SafeBioHandle bio, out byte* prefixPtr, out int prefixLen);
210+
169211
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_BioGetWriteResult")]
170212
internal static partial void BioGetWriteResult(SafeBioHandle bio, out int writtenToWindow, out int spillLen);
171213

@@ -231,6 +273,9 @@ internal static SafeSharedX509StackHandle SslGetPeerCertChain(SafeSslHandle ssl)
231273
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslSetVerifyPeer")]
232274
internal static partial void SslSetVerifyPeer(SafeSslHandle ssl, [MarshalAs(UnmanagedType.Bool)] bool failIfNoPeerCert);
233275

276+
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslSetRetryVerify")]
277+
internal static partial int SslSetRetryVerify(SafeSslHandle ssl);
278+
234279
[LibraryImport(Libraries.CryptoNative, EntryPoint = "CryptoNative_SslGetData")]
235280
internal static partial IntPtr SslGetData(IntPtr ssl);
236281

@@ -422,6 +467,7 @@ internal enum SslErrorCode
422467
SSL_ERROR_WANT_X509_LOOKUP = 4,
423468
SSL_ERROR_SYSCALL = 5,
424469
SSL_ERROR_ZERO_RETURN = 6,
470+
SSL_ERROR_WANT_RETRY_VERIFY = 12,
425471

426472
// NOTE: this SslErrorCode value doesn't exist in OpenSSL, but
427473
// we use it to distinguish when a renegotiation is pending.
@@ -450,6 +496,17 @@ internal sealed class SafeSslHandle : SafeDeleteSslContext
450496
// we may rethrow it after returning to managed code.
451497
public Exception? CertificateValidationException;
452498

499+
// OpenSSL 3.0+ retry-verify state (dormant infrastructure). When CertVerifyCallback
500+
// eventually opts into SSL_set_retry_verify (currently disabled — upstream OpenSSL
501+
// does not re-enter the peer-cert verify callback on either client or server SSLs),
502+
// it will set RetryVerifyAttempted = true and, on re-entry, honor
503+
// ExternalValidationAccepted (posted by TlsSession.PushExternalValidationVerdict-
504+
// ToPalIfRetryVerify). Both fields are read but never written today, hence CS0649.
505+
#pragma warning disable CS0649
506+
public bool RetryVerifyAttempted;
507+
public bool ExternalValidationAccepted;
508+
#pragma warning restore CS0649
509+
453510
public bool IsServer
454511
{
455512
get { return _isServer; }
@@ -478,37 +535,85 @@ internal void MarkHandshakeCompleted()
478535

479536
public static SafeSslHandle Create(SafeSslContextHandle context, SslAuthenticationOptions options)
480537
{
481-
SafeBioHandle readBio = Interop.Ssl.BioNewManagedSpan();
482-
SafeBioHandle writeBio = Interop.Ssl.BioNewManagedSpan();
538+
SafeSocketHandle? socket = options.SocketHandle;
539+
bool useFd = socket is not null && !socket.IsInvalid;
540+
SafeBioHandle? preallocatedReadBio = useFd ? options.PreallocatedReadBio : null;
541+
byte[]? replayPrefix = useFd ? options.ReplayPrefix : null;
542+
bool usePreallocatedBio = preallocatedReadBio is not null;
543+
bool useReplayBio = usePreallocatedBio || (useFd && replayPrefix is not null);
544+
545+
SafeBioHandle? readBio = null;
546+
SafeBioHandle? writeBio = null;
547+
if (usePreallocatedBio)
548+
{
549+
// Deferred-server flow (native pre-fetch): the caller populated a
550+
// socket-replay BIO via BioPeekTlsFrame; adopt it as the read BIO
551+
// and create a peer write BIO for OpenSSL's outbound records.
552+
// Clear the field so ownership transfer happens exactly once.
553+
readBio = preallocatedReadBio;
554+
options.PreallocatedReadBio = null;
555+
writeBio = Interop.Ssl.BioNewSocketReplay(socket!, ReadOnlySpan<byte>.Empty);
556+
}
557+
else if (useReplayBio)
558+
{
559+
// Legacy deferred-server flow (managed pre-fetch): install a socket-
560+
// replay BIO seeded with the peeked ClientHello bytes.
561+
readBio = Interop.Ssl.BioNewSocketReplay(socket!, replayPrefix);
562+
writeBio = Interop.Ssl.BioNewSocketReplay(socket!, ReadOnlySpan<byte>.Empty);
563+
}
564+
else if (!useFd)
565+
{
566+
readBio = Interop.Ssl.BioNewManagedSpan();
567+
writeBio = Interop.Ssl.BioNewManagedSpan();
568+
}
569+
483570
SafeSslHandle handle = Interop.Ssl.SslCreate(context);
484-
if (readBio.IsInvalid || writeBio.IsInvalid || handle.IsInvalid)
571+
if (((readBio is not null) && (readBio.IsInvalid || writeBio!.IsInvalid)) || handle.IsInvalid)
485572
{
486-
readBio.Dispose();
487-
writeBio.Dispose();
573+
readBio?.Dispose();
574+
writeBio?.Dispose();
488575
handle.Dispose(); // will make IsInvalid==true if it's not already
489576
return handle;
490577
}
491578
handle._isServer = options.IsServer;
492579
handle._authOptionsHandle = new WeakGCHandle<SslAuthenticationOptions>(options);
493580
Interop.Ssl.SslSetData(handle, WeakGCHandle<SslAuthenticationOptions>.ToIntPtr(handle._authOptionsHandle));
494581

495-
// SslSetBio will transfer ownership of the BIO handles to the SSL context
496-
try
582+
// CertVerifyCallback needs the SafeSslHandle to stash a
583+
// CertificateValidationException; expose it via the options.
584+
options.SafeSslHandle = handle;
585+
586+
if (useFd && !useReplayBio)
497587
{
498-
readBio.TransferOwnershipToParent(handle);
499-
writeBio.TransferOwnershipToParent(handle);
500-
handle._readBio = readBio;
501-
handle._writeBio = writeBio;
502-
Interop.Ssl.SslSetBio(handle, readBio, writeBio);
588+
if (Interop.Ssl.SslSetFd(handle, socket!) != 1)
589+
{
590+
handle.Dispose();
591+
throw Interop.OpenSsl.CreateSslException(SR.net_allocate_ssl_context_failed);
592+
}
503593
}
504-
catch (Exception exc)
594+
else
505595
{
506-
// The only way this should be able to happen without thread aborts is if we hit OOMs while
507-
// manipulating the safe handles, in which case we may leak the bio handles.
508-
Debug.Fail("Unexpected exception while transferring SafeBioHandle ownership to SafeSslHandle", exc.ToString());
509-
throw;
596+
// SslSetBio will transfer ownership of the BIO handles to the SSL context
597+
try
598+
{
599+
readBio!.TransferOwnershipToParent(handle);
600+
writeBio!.TransferOwnershipToParent(handle);
601+
handle._readBio = readBio;
602+
handle._writeBio = writeBio;
603+
Interop.Ssl.SslSetBio(handle, readBio, writeBio);
604+
}
605+
catch (Exception exc)
606+
{
607+
// The only way this should be able to happen without thread aborts is if we hit OOMs while
608+
// manipulating the safe handles, in which case we may leak the bio handles.
609+
Debug.Fail("Unexpected exception while transferring SafeBioHandle ownership to SafeSslHandle", exc.ToString());
610+
throw;
611+
}
510612
}
511613

614+
// Consumed exactly once: the BIO holds its own copy of the prefix bytes.
615+
options.ReplayPrefix = null;
616+
512617
if (options.IsServer)
513618
{
514619
Interop.Ssl.SslSetAcceptState(handle);

‎src/libraries/Common/src/System/Experimentals.cs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ internal static class Experimentals
3333
// Types for Post-Quantum Cryptography (PQC) are experimental.
3434
internal const string PostQuantumCryptographyDiagId = "SYSLIB5006";
3535

36+
// Low-level TLS engine (TlsContext / TlsSession) is experimental.
37+
internal const string LowLevelTlsDiagId = "SYSLIB5007";
38+
3639
// SocketsHttpHandler connection eviction control and HttpRequestMessage.ConnectionId APIs are experimental.
3740
internal const string SocketsHttpHandlerExperimentalDiagId = "SYSLIB5008";
3841

‎src/libraries/System.Net.Security/ref/System.Net.Security.cs‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -687,6 +687,72 @@ public enum TlsCipherSuite : ushort
687687
TLS_ECDHE_PSK_WITH_AES_128_CCM_8_SHA256 = (ushort)53251,
688688
TLS_ECDHE_PSK_WITH_AES_128_CCM_SHA256 = (ushort)53253,
689689
}
690+
[System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5007", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
691+
public enum TlsOperationStatus
692+
{
693+
Complete = 0,
694+
DestinationTooSmall = 1,
695+
NeedMoreData = 2,
696+
Closed = 3,
697+
CertificateRequested = 4,
698+
NeedsCertificateValidation = 5,
699+
NeedsTlsContext = 6,
700+
}
701+
[System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5007", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
702+
public sealed partial class TlsContext : System.IDisposable
703+
{
704+
internal TlsContext() { }
705+
public static System.Net.Security.TlsContext CreateServer(System.Net.Security.SslServerAuthenticationOptions options) { throw null; }
706+
public static System.Net.Security.TlsContext CreateClient(System.Net.Security.SslClientAuthenticationOptions options) { throw null; }
707+
public void Dispose() { }
708+
}
709+
[System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5007", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
710+
public abstract partial class TlsSession : System.IDisposable
711+
{
712+
private protected TlsSession() { }
713+
public bool IsHandshakeComplete { get { throw null; } }
714+
public bool HasPendingOutput { get { throw null; } }
715+
public string? TargetHostName { get { throw null; } set { } }
716+
public System.Net.Security.SslClientHelloInfo? ClientHelloInfo { get { throw null; } }
717+
public int GetClientHelloLength() { throw null; }
718+
public bool TryGetClientHelloBytes(System.Span<byte> destination, out int bytesWritten) { throw null; }
719+
public System.Security.Authentication.SslProtocols NegotiatedProtocol { get { throw null; } }
720+
[System.CLSCompliantAttribute(false)]
721+
public System.Net.Security.TlsCipherSuite NegotiatedCipherSuite { get { throw null; } }
722+
public System.Net.Security.SslApplicationProtocol NegotiatedApplicationProtocol { get { throw null; } }
723+
public System.Security.Cryptography.X509Certificates.X509Certificate2? GetRemoteCertificate() { throw null; }
724+
public System.Security.Cryptography.X509Certificates.X509Certificate2Collection? GetRemoteCertificates() { throw null; }
725+
public System.Net.Security.SslPolicyErrors AcceptWithDefaultValidation() { throw null; }
726+
public void SetRemoteCertificateValidationResult(System.Net.Security.SslPolicyErrors errors) { }
727+
public void SetContext(System.Net.Security.TlsContext context) { }
728+
public void SetClientCertificateContext(System.Net.Security.SslStreamCertificateContext? context) { }
729+
public System.Collections.Generic.IReadOnlyList<string>? GetAcceptableIssuers() { throw null; }
730+
public System.Security.Cryptography.X509Certificates.X509Certificate2? LocalCertificate { get { throw null; } }
731+
public System.Security.Authentication.ExtendedProtection.ChannelBinding? GetChannelBinding(System.Security.Authentication.ExtendedProtection.ChannelBindingKind kind) { throw null; }
732+
public void Dispose() { }
733+
}
734+
[System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5007", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
735+
public sealed partial class TlsBufferSession : System.Net.Security.TlsSession
736+
{
737+
public TlsBufferSession() { }
738+
public System.Net.Security.TlsOperationStatus Handshake(System.ReadOnlySpan<byte> source, System.Span<byte> destination, out int bytesConsumed, out int bytesWritten) { throw null; }
739+
public System.Net.Security.TlsOperationStatus Write(System.ReadOnlySpan<byte> source, System.Span<byte> destination, out int bytesConsumed, out int bytesWritten) { throw null; }
740+
public System.Net.Security.TlsOperationStatus Read(System.ReadOnlySpan<byte> source, System.Span<byte> destination, out int bytesConsumed, out int bytesWritten) { throw null; }
741+
public System.Net.Security.TlsOperationStatus Shutdown(System.Span<byte> destination, out int bytesWritten) { throw null; }
742+
public System.Net.Security.TlsOperationStatus DrainPendingOutput(System.Span<byte> destination, out int bytesWritten) { throw null; }
743+
public System.Net.Security.TlsOperationStatus RequestClientCertificate(System.Span<byte> destination, out int bytesWritten) { throw null; }
744+
}
745+
[System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5007", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
746+
public sealed partial class TlsSocketSession : System.Net.Security.TlsSession
747+
{
748+
public TlsSocketSession(System.Net.Sockets.SafeSocketHandle socket) { }
749+
public System.Net.Sockets.SafeSocketHandle Socket { get { throw null; } }
750+
public System.Net.Security.TlsOperationStatus Handshake() { throw null; }
751+
public System.Net.Security.TlsOperationStatus Read(System.Span<byte> buffer, out int bytesRead) { throw null; }
752+
public System.Net.Security.TlsOperationStatus Write(System.ReadOnlySpan<byte> buffer, out int bytesWritten) { throw null; }
753+
public System.Net.Security.TlsOperationStatus Shutdown() { throw null; }
754+
public System.Net.Security.TlsOperationStatus RequestClientCertificate() { throw null; }
755+
}
690756
}
691757
namespace System.Security.Authentication
692758
{

‎src/libraries/System.Net.Security/ref/System.Net.Security.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
<ProjectReference Include="$(LibrariesProjectRoot)System.Collections\ref\System.Collections.csproj" />
1313
<ProjectReference Include="$(LibrariesProjectRoot)System.Memory\ref\System.Memory.csproj" />
1414
<ProjectReference Include="$(LibrariesProjectRoot)System.Net.Primitives\ref\System.Net.Primitives.csproj" />
15+
<ProjectReference Include="$(LibrariesProjectRoot)System.Net.Sockets\ref\System.Net.Sockets.csproj" />
1516
<ProjectReference Include="$(LibrariesProjectRoot)System.Runtime\ref\System.Runtime.csproj" />
1617
<ProjectReference Include="$(LibrariesProjectRoot)System.Security.Cryptography\ref\System.Security.Cryptography.csproj" />
1718
</ItemGroup>

0 commit comments

Comments
 (0)