Tmsch_CertificateSelectionCallback Delegate

Represents the method that handles the selection of a client certificate during an SSL/TLS handshake.

Syntax

Parameters

• sender

  The source of the callback.

• targetHost

  The target host name.

• localCertificates

  An array of X509Certificate objects that represent the available client certificates.

• remoteCertificate

  The certificate presented by the remote server.

• acceptableIssuers

  An array of strings that specifies the distinguished names of acceptable certificate authorities.

Return Value

An X509Certificate object that represents the client certificate to be used for the connection. Returns null if no certificate is available or should be sent.

Remarks

The Tmsch_CertificateSelectionCallback delegate is used to provide a custom mechanism for selecting a client certificate when establishing an SSL/TLS connection. This is particularly useful in scenarios where multiple client certificates are available and the application needs to choose the most appropriate one based on factors such as the target host, the server's certificate, or policy requirements.

When a connection requires a client certificate, the underlying networking stack invokes the method pointed to by the Tmsch_CertificateSelectionCallback delegate. The delegate receives information about the connection context, including a list of available client certificates and the requirements of the server. The delegate implementation should then examine this information and return the certificate that best satisfies the requirements, or null if no suitable certificate is found.

Example

The following example demonstrates how to implement a Tmsch_CertificateSelectionCallback to select a client certificate based on the target host and a specific issuer.

using System;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;

public class CertificateSelector
{
    public static X509Certificate SelectClientCertificate(
        object sender,
        string targetHost,
        X509Certificate[] localCertificates,
        X509Certificate remoteCertificate,
        string[] acceptableIssuers)
    {
        Console.WriteLine($"Target Host: {targetHost}");
        Console.WriteLine($"Remote Certificate: {remoteCertificate?.Subject}");

        if (localCertificates == null || localCertificates.Length == 0)
        {
            Console.WriteLine("No local certificates available.");
            return null;
        }

        Console.WriteLine($"Found {localCertificates.Length} local certificates.");

        // Example: Select a certificate issued by a specific CA for a specific host
        string desiredIssuer = "CN=MyCompany Root CA, OU=IT, O=MyCompany, C=US";
        string specificHost = "secure.example.com";

        if (targetHost.Equals(specificHost, StringComparison.OrdinalIgnoreCase))
        {
            foreach (var cert in localCertificates)
            {
                X509Certificate2 cert2 = cert as X509Certificate2;
                if (cert2 != null && cert2.Issuer.Contains(desiredIssuer))
                {
                    Console.WriteLine($"Selecting certificate for {targetHost}: {cert2.Subject}");
                    return cert2;
                }
            }
        }

        // Default to the first available certificate if no specific criteria match
        Console.WriteLine($"Selecting the first available certificate: {localCertificates[0].Subject}");
        return localCertificates[0];
    }
}
            

Requirements

Namespace: System.Net.Security

Assembly: System.Net.Primitives (in .NET Core and .NET 5+)

Platform: Windows, Linux, macOS