System.Net.SslStream new APIs for TLS Alert support

[CIPop]

System.Net.SslStream is not currently supporting TLS Alerts as specified by RFC 2246 sections 7.2.1: Closure alerts and 7.2.2: Error alerts.

Proposed API

In order to support closing the TLS channel gracefully the following async API is proposed:

public virtual System.Threading.Tasks.Task System.Net.SslStream.ShutdownAsync()

Details

The ShutdownAsync semantics are similar to Socket.Shutdown(SocketShutdown.Send) or WebSocket.CloseOutputAsync. After ShutdownAsync has been called, the write portion of the full-duplex channel is closed and the channel becomes read-only. The handshake is completed when no more bytes can be read from the SslStream (Read APIs return 0.)

New API Usage

The following code shows usage of the new API as well as new server-side behavior. This as well as tests demonstrating the new behavior to support 7.2.2. during TLS Handshake is available in SslStreamAlertsTest.cs, dotnet/corefx#11489.

var handshake = new Task[2];

handshake[0] = server.AuthenticateAsServerAsync(certificate);
handshake[1] = client.AuthenticateAsClientAsync(certificate.GetNameInfo(X509NameType.SimpleName, false));

await Task.WhenAll(handshake).TimeoutAfter(TestConfiguration.PassingTestTimeoutMilliseconds);

var readBuffer = new byte[1024];

await server.ShutdownAsync();
int bytesRead = await client.ReadAsync(readBuffer, 0, readBuffer.Length);
// close_notify received by the client.
Assert.Equal(0, bytesRead);

await client.ShutdownAsync();
bytesRead = await server.ReadAsync(readBuffer, 0, readBuffer.Length);
// close_notify received by the server.
Assert.Equal(0, bytesRead);

Pull Requests

WIP (tooling/WIP) API change: dotnet/corefx#11265.
Implementation and tests: dotnet/corefx#11489:

[CIPop]

@terrajobst @davidsh PTAL

[davidsh]

The ShutdownAsync semantics are similar to Socket.Shutdown(SocketShutdown.Send) or WebSocket.CloseOutputAsync.

That may be true. However, what happens when a developer of Socket doesn't use Socket.Shutdown(SocketShutdown.Send)? Or a developer doesn't use WebSocket.CloseOutputAsync? If they just do Close or Dispose don't they get a similar graceful close of the socket and websocket?

These APIs for Socket and WebSocket allow a developer more granular control of the sending-side. But the APIs don't seem required for Socket and WebSocket. Isn't that true?

But now for SslStream, we are stating that the normal Close / Dispose is not sufficient and in reality we are doing a non-graceful "close" of the channel. And to fix that moving forward, we are asking developers to understand a new async API and that they should start using it.

I just want to clarify this point so that we can correctly discuss and document this new API and expected behaviors.

[CIPop]

/cc @bartonjs

But now for SslStream, we are stating that the normal Close / Dispose is not sufficient

There are cases when the close_notify message is not required.
For example, in my experiments, none of the browsers I've tested will send the close_notify message for HTTPS connections.

The definition shows that it is possible to close the channel without sending the alert, although the session will become unresumable:

   close_notify
       This message notifies the recipient that the sender will not send
       any more messages on this connection. The session becomes
       unresumable if any connection is terminated without proper
       close_notify messages with level equal to warning.

The second aspect is the distinction between the TLS/SSL and transport channels. The TLS RFC applies to the TLS channel only, not the transport.

   If the application protocol will not
   transfer any additional data, but will only close the underlying
   transport connection, then the implementation may choose to close the
   transport without waiting for the responding close_notify. No part of
   this standard should be taken to dictate the manner in which a usage
   profile for TLS manages its data transport, including when
   connections are opened or closed.

In case of other protocols or when the connection will be reused, close_notify is mandatory:

7.2.1. Closure alerts

   The client and the server must share knowledge that the connection is
   ending in order to avoid a truncation attack. Either party may
   initiate the exchange of closing messages.

[CIPop]

@terrajobst PTAL

[terrajobst]

The API looks good as proposed.