System.Net.Security.ClientHelloInfo Class

Represents information about a client's initial TLS/SSL handshake message (ClientHello).

Properties
Remarks
Examples
Requirements

Properties

ProtocolType

Gets the protocol type of the client's connection.

Public ProtocolType ProtocolType { get; }

TargetHost

Gets the target host name for the client's connection.

Public string TargetHost { get; }

SslProtocol

Gets the SSL/TLS protocol version requested by the client.

Public SslProtocol SslProtocol { get; }

CipherSuites

Gets the list of cipher suites supported by the client.

Public IEnumerable<string> CipherSuites { get; }

Extensions

Gets the list of TLS extensions sent by the client.

Public IEnumerable<string> Extensions { get; }

Remarks

The ClientHelloInfo class is used to inspect the details of an incoming TLS/SSL handshake from a client. This information can be valuable for security analysis, custom TLS server implementations, or for enforcing specific client requirements.

This class is typically accessed within event handlers for security-related operations, such as when customizing the behavior of an TcpClient or HttpClient.

Note: The availability and content of properties like Extensions may vary depending on the TLS version and client implementation.

Examples

C# Example: Inspecting ClientHelloInfo

This example demonstrates how to capture and inspect ClientHelloInfo in a custom TLS server scenario.


using System;
using System.Net;
using System.Net.Security;
using System.Net.Sockets;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public class CustomTlsServer
{
    public static async Task StartServer(int port)
    {
        TcpListener listener = new TcpListener(IPAddress.Any, port);
        listener.Start();
        Console.WriteLine($"Server started on port {port}. Waiting for connections...");

        while (true)
        {
            TcpClient client = await listener.AcceptTcpClientAsync();
            _ = Task.Run(() => HandleClient(client));
        }
    }

    private static void HandleClient(TcpClient tcpClient)
    {
        try
        {
            // Obtain the certificate for the server
            X509Certificate serverCertificate = GetServerCertificate();

            // Use SslStream to wrap the network stream and enable SSL/TLS
            SslStream sslStream = new SslStream(
                tcpClient.GetStream(),
                false,
                new RemoteCertificateValidationCallback(ValidateServerCertificate),
                new LocalCertificateSelectionCallback(SelectServerCertificate)
            );

            // Begin the SSL/TLS handshake.
            // This is where ClientHelloInfo becomes available if we hook into it.
            // For simplicity, we'll just initiate the handshake here.
            // A more advanced scenario might involve intercepting the handshake process.
            sslStream.AuthenticateAsServer(serverCertificate,
                                         clientCertificateRequired: false,
                                         enabledSslProtocols: System.Security.Authentication.SslProtocols.Tls12 | System.Security.Authentication.SslProtocols.Tls13,
                                         checkCertificateRevocation: true);

            // At this point, the handshake is complete.
            // To directly access ClientHelloInfo during authentication,
            // you'd typically need a lower-level interception mechanism or a
            // custom SslStream implementation, which is more complex.
            // However, some properties might be inferable or accessible post-authentication
            // through different means depending on the framework version.

            Console.WriteLine($"Client authenticated. SSL/TLS Protocol: {sslStream.SslProtocol}");
            Console.WriteLine($"Cipher Suite: {sslStream.CipherSuite}");

            // Example: Reading data from the client
            byte[] buffer = new byte[1024];
            int bytesRead = sslStream.Read(buffer, 0, buffer.Length);
            string request = System.Text.Encoding.ASCII.GetString(buffer, 0, bytesRead);
            Console.WriteLine($"Received: {request}");

            // Send a response back to the client
            byte[] responseBytes = System.Text.Encoding.ASCII.GetBytes("Hello from server!");
            sslStream.Write(responseBytes, 0, responseBytes.Length);

            sslStream.Close();
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error handling client: {ex.Message}");
        }
        finally
        {
            tcpClient.Close();
        }
    }

    // Placeholder for getting the server certificate
    private static X509Certificate GetServerCertificate()
    {
        // In a real application, you would load your server certificate here.
        // For demonstration, we'll assume a self-signed certificate exists.
        // Replace with your certificate loading logic.
        try
        {
            // Example: Load from a PFX file
            // return new X509Certificate2("server.pfx", "password");

            // Example: Find a certificate in the local machine store
            var store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
            store.Open(OpenFlags.ReadOnly);
            var certificates = store.Certificates.Find(X509FindType.FindBySubjectName, "localhost", false);
            if (certificates.Count > 0)
            {
                return certificates[0];
            }
            else
            {
                throw new Exception("Server certificate not found. Please create a self-signed certificate for 'localhost'.");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error loading certificate: {ex.Message}");
            throw;
        }
    }

    // Callback to validate the client certificate (optional)
    private static bool ValidateServerCertificate(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
    {
        if (sslPolicyErrors == SslPolicyErrors.None)
            return true;

        Console.WriteLine("Certificate error: " + sslPolicyErrors);
        return false; // Reject the connection if there are errors
    }

    // Callback to select the server certificate (if multiple are available)
    private static X509Certificate SelectServerCertificate(object sender, string targetHost, X509CertificateCollection localCertificates, X509Certificate remoteCertificate, string[] acceptableIssuers)
    {
        // If no certificates were passed in, return null.
        if (localCertificates == null || localCertificates.Count == 0)
            return null;

        // Use the first certificate in the collection.
        // In a real-world scenario, you might have logic to select the best certificate.
        return localCertificates[0];
    }

    // Example of how to start the server
    // public static void Main(string[] args)
    // {
    //     // Make sure you have a certificate for 'localhost' in your LocalMachine\My store
    //     // Or replace GetServerCertificate with your own logic to load a certificate.
    //     StartServer(8080).GetAwaiter().GetResult();
    // }
}

VB.NET Example: Inspecting ClientHelloInfo