CertificateSupplyCallback Delegate

Assembly: System.Net.Primitives.dll

Represents the method that is called to supply a certificate when the client or server needs one during an SSL/TLS authentication process.

Syntax

public delegate X509Certificate2 CertificateSupplyCallback(
    object                       sender,
    string                        targetHost,
    X509CertificateCollection    localCertificates,
    X509Certificate                 remoteCertificate,
    string[]                        acceptableIssuers
);

Parameters

Parameter	Description
`sender`	The object that initiated the callback. This is typically an instance of `SslStream` or a related class.
`targetHost`	The target host name for the SSL/TLS connection. This is the host to which the client is attempting to connect.
`localCertificates`	A collection of local certificates available to the client or server. The callback can choose a certificate from this collection.
`remoteCertificate`	The certificate presented by the remote party. This parameter is null if the remote party did not present a certificate.
`acceptableIssuers`	An array of distinguished names of certificate authorities (CAs) that are acceptable to the remote party. The client or server can use this information to select an appropriate certificate.

Return Value

A X509Certificate2 object that represents the certificate to be supplied for authentication. Returns null if no suitable certificate can be supplied.

Remarks

The CertificateSupplyCallback delegate is used to provide a mechanism for dynamically selecting a client certificate during SSL/TLS handshake. This is particularly useful in scenarios where multiple certificates might be available, and the selection needs to be based on criteria such as the target host, the remote party's certificate, or the list of acceptable issuers.

When an SSL/TLS connection requires a client certificate (e.g., for mutual authentication), the system invokes the delegate assigned to the ClientCertificateValidationCallback property of SslClientAuthenticationOptions (or similar properties on server-side authentication options). The callback method receives information about the connection and available certificates and is responsible for returning an appropriate certificate.

Note: If the callback returns null, and a certificate is required for authentication, the connection may fail.

Example

The following example demonstrates how to implement a CertificateSupplyCallback that selects a certificate based on the target host name.

C#
public static X509Certificate2 SelectClientCertificate(
    object                       sender,
    string                        targetHost,
    X509CertificateCollection    localCertificates,
    X509Certificate                 remoteCertificate,
    string[]                        acceptableIssuers
)
{
    // In a real application, you would load certificates from a store
    // or a file system and apply more sophisticated selection logic.
    if (targetHost.Equals("my.secure.server.com", StringComparison.OrdinalIgnoreCase))
    {
        // Attempt to find a certificate suitable for this host
        foreach (X509Certificate2 cert in localCertificates)
        {
            // Example: Check if the certificate's subject name matches the target host
            if (cert.Subject.Contains(targetHost))
            {
                return cert;
            }
        }
    }
    // If no suitable certificate is found, return null
    return null;
}