System.Net.Security.SslCertificateSelectionCallback Delegate

Represents the method that will select an X509Certificate object when an SSL or TLS connection requires client authentication.

Syntax

public delegate X509Certificate SslCertificateSelectionCallback(
    object sender,
    string targetHost,
    X509CertificateCollection localCertificates,
    X509Certificate remoteCertificate,
    string acceptableIssuers
);

Parameters

  • sender
    object
    The SslStream object that is requesting a certificate.
  • targetHost
    string
    The name of the server that the client is attempting to authenticate.
  • localCertificates
    X509CertificateCollection
    A collection of local certificates available for authentication.
  • remoteCertificate
    X509Certificate
    The certificate of the server requesting client authentication.
  • acceptableIssuers
    string
    A string that contains the distinguished names (DN) of the acceptable certificate issuers.

Return Value

A X509Certificate object that represents the certificate to be presented to the server for authentication. Returns null to indicate that no certificate should be presented.

Remarks

The SslCertificateSelectionCallback delegate is used with the SslStream.AuthenticateAsClient method. When the client needs to present a certificate to the server for authentication, the SslStream calls the method represented by this delegate.

Your callback method should examine the parameters provided (especially targetHost, localCertificates, and acceptableIssuers) and return the most appropriate X509Certificate from the localCertificates collection. If no suitable certificate is found or if no certificate should be presented, the method should return null.

The remoteCertificate parameter contains the certificate of the server. This can be useful for certain authentication scenarios, but is often less critical for client certificate selection than the other parameters.

The acceptableIssuers parameter is a string that contains the distinguished names (DNs) of certificate authorities that the server will accept. You can parse this string to filter your local certificates.

Example

The following example shows how to define and assign a callback method to select a client certificate. 

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

public class SslClientExample
{
    public static X509Certificate SelectClientCertificate(
        object sender,
        string targetHost,
        X509CertificateCollection localCertificates,
        X509Certificate remoteCertificate,
        string acceptableIssuers)
    {
        Console.WriteLine("Client certificate selection requested.");
        Console.WriteLine($"Target Host: {targetHost}");
        Console.WriteLine($"Acceptable Issuers: {acceptableIssuers}");

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

        // In a real application, you would implement logic here to choose
        // the best certificate based on targetHost, acceptableIssuers, and
        // any other criteria. For this example, we'll just pick the first one.
        Console.WriteLine($"Selecting the first available certificate.");
        return localCertificates[0];
    }

    public static void Main(string[] args)
    {
        // Example usage:
        // Imagine this is part of an SslStream.AuthenticateAsClient call
        // SslStream sslStream = new SslStream(innerStream);
        // sslStream.AuthenticateAsClient(targetHost,
        //                               new X509CertificateCollection(), // Initially empty, may be populated by system
        //                               SslProtocols.Tls12,
        //                               false,
        //                               SelectClientCertificate); // Assigning the callback delegate

        Console.WriteLine("This is a demonstration of the SslCertificateSelectionCallback delegate.");
        Console.WriteLine("In a real scenario, this would be called by SslStream during client authentication.");
    }
}
< Previous
Next >