AuthenticateAsClientTaskAsync(TcpSession) Method

Authenticates the server when establishing a secure connection.

Syntax

Visual Basic (Declaration)
Visual Basic (Usage)
C#
C++/CLI

<SecuritySafeCriticalAttribute()>
Public Overloads Function AuthenticateAsClientTaskAsync( _
   ByVal session As TcpSession _
) As Task

Dim instance As TcpBase
Dim session As TcpSession
Dim value As Task
 
value = instance.AuthenticateAsClientTaskAsync(session)

[SecuritySafeCritical()]
public Task AuthenticateAsClientTaskAsync( 
   TcpSession session
)

[SecuritySafeCritical()]
public:
Task^ AuthenticateAsClientTaskAsync( 
   TcpSession^ session
)

Parameters

session: Session parameters used during authentication.

Remarks

Uses Session.RemoteEndPoint, TcpSession.Proxy and TcpSession.Security to specify Security.ValidationCallback, SelectionCallback, ClientSecurity.TargetHost, Certificates, Security.Protocols, and Security.CheckCertificateRevocation.

If session.Security.TargetHost is not specifed, then session.RemoteEndPoint.HostNameOrAddress will be used instead. session.Security.TargetHost should match the server certificate name. If authentication fails, an AuthenticationException will occur.

To accept or reject a certificate "on-the-fly" implement a TcpSession.Security.ValidationCallback function.

To select a client certificate "on-the-fly" implement a TcpSession.Security.SelectionCallback function.

Example

This example demonstrates the AuthenticateAsClient call, the callback that prompts for a local certificate, and the callback that executes when a certificate is received.

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

/// <summary>
/// Establishes SSL with the provided Tcp object. Typically called immediately after connecting to the server (implicit) 
/// or after a command such as STARTTLS is sent to the server (explicit).
/// </summary>
/// <param name="myComponent">Object to establish SSL with</param>
/// <param name="session">The TcpSession object used for connecting to the server</param>
/// <param name="serverHostName">The name of the server</param>
/// <param name="protocols">Protocols the client will accept</param>
/// <param name="checkRevocation">Check certificate revocation list during authentication</param>
private void authenticateTcp(Tcp myComponent, TcpSession session, string serverHostName, SslProtocols protocols, bool checkRevocation)
{
    //Specify configuration and certificate callback function, and authenticate server
    //Specifying TargetHost is only necessary if TcpSession.RemoteEndPoint.HostNameOrAddress doesn't match the server's certificate
    session.Security.TargetHost = serverHostName;
    session.Security.Protocols = protocols;
    session.Security.CheckCertificateRevocation = checkRevocation;
    session.Security.ValidationCallback = certificateReceived;
    session.Security.SelectionCallback = selectLocalCertificate;
    myComponent.AuthenticateAsClient(session);
}

/// <summary>
/// Prompts the user to select a certificate for SSL authentication.
/// </summary>
/// <remarks>
/// This snippet assumes the presence of the Dart Test Certificate in the user's 'My' certificate store. 
/// The Dart Test Certificate may be installed from the component's Start Menu program group.
/// For a UI-based certificate selection, please see the CertificateListForm included with our 
/// WinForms samples.
/// </remarks>
/// <param name="targetHost">The host server specified by the client.</param>
/// <param name="localCertificates">A reference to ClientSecurity.Certificates</param>
/// <param name="remoteCertificate">The certificate used to authenticate the remote party.</param>
/// <param name="acceptableIssuers">A String array of certificate issuers acceptable to the remote party.</param>
/// <returns>An X509Certificate to use for establishing the SSL connection.</returns>
private X509Certificate selectLocalCertificate(Object sender, string targetHost, 
    X509CertificateCollection localCertificates, X509Certificate remoteCertificate, string[] acceptableIssuers)
{
    //Try to find the Dart Test Certificate
    X509Store certificateStore = new X509Store(StoreName.My);
    certificateStore.Open(OpenFlags.ReadOnly);
    foreach (X509Certificate2 cert in certificateStore.Certificates)
        if (cert.GetNameInfo(X509NameType.SimpleName, true) == "DartdomCA")
        {
            certificateStore.Close();
            return cert;
        }
    //Certificate not found, return null
    return null;
}

/// <summary>
/// Presents the server's certificate for validation.
/// </summary>
/// <param name="certificate">The certificate presented by the server</param>
/// <param name="chain">The chain of certificate authorities associated with the remote certificate</param>
/// <param name="sslPolicyErrors">One or more errors associated with the server's certificate</param>
/// <returns>A Boolean value that specifies whether the presented certificate is accepted for authentication</returns>
private bool certificateReceived(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
    //Accept certificate if it passed standard validation.
    if (sslPolicyErrors == SslPolicyErrors.None)
        return true;

    string msg = "The server could not be validated for the following reason(s):";

    if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateNotAvailable) == SslPolicyErrors.RemoteCertificateNotAvailable)
        msg += Environment.NewLine + "    -The server did not present a certificate.";
    else
    {
        if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateNameMismatch) == SslPolicyErrors.RemoteCertificateNameMismatch)
            msg += Environment.NewLine + "    -Certificate name mismatch.";
        if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateChainErrors) == SslPolicyErrors.RemoteCertificateChainErrors)
        {
            msg += Environment.NewLine + "    -Certificate chain errors:" + Environment.NewLine;

            foreach (X509ChainStatus item in chain.ChainStatus)
                msg += "    --" + item.StatusInformation;
        }
    }

    //Prompt to override security check
    msg += Environment.NewLine + "Override security check?";
    if (MessageBox.Show(msg, "Security Alert: Server could not be validated", MessageBoxButtons.YesNo, MessageBoxIcon.Exclamation) == DialogResult.Yes)
        return true;
    else
        return false;
}

Visual Basic

Imports System.Net.Security
Imports System.Security.Authentication
Imports System.Security.Cryptography.X509Certificates

''' <summary>
''' Establishes SSL with the provided Tcp object. Typically called immediately after connecting to the server (implicit) 
''' or after a command such as STARTTLS is sent to the server (explicit).
''' </summary>
''' <param name="myComponent">Object to establish SSL with</param>
''' <param name="session">The TcpSession object used for connecting to the server</param>
''' <param name="serverHostName">The name of the server</param>
''' <param name="protocols">Protocols the client will accept</param>
''' <param name="checkRevocation">Check certificate revocation list during authentication</param>
Private Sub authenticateTcp(ByVal myComponent As Tcp, ByVal session As TcpSession, ByVal serverHostName As String, ByVal protocols As SslProtocols, ByVal checkRevocation As Boolean)
    'Specify configuration and certificate callback function, and authenticate server
    'Specifying TargetHost is only necessary if TcpSession.RemoteEndPoint.HostNameOrAddress doesn't match the server's certificate
    session.Security.TargetHost = serverHostName
    session.Security.Protocols = protocols
    session.Security.CheckCertificateRevocation = checkRevocation
    session.Security.ValidationCallback = AddressOf certificateReceived
    session.Security.SelectionCallback = AddressOf selectLocalCertificate
    myComponent.AuthenticateAsClient(session)
End Sub

''' <summary>
''' Prompts the user to select a certificate for SSL authentication.
''' </summary>
''' <remarks>
''' This snippet assumes the presence of the Dart Test Certificate in the user's 'My' certificate store. 
''' The Dart Test Certificate may be installed from the component's Start Menu program group.
''' For a UI-based certificate selection, please see the CertificateListForm included with our 
''' WinForms samples.
''' </remarks>
''' <param name="targetHost">The host server specified by the client.</param>
''' <param name="localCertificates">A reference to ClientSecurity.Certificates</param>
''' <param name="remoteCertificate">The certificate used to authenticate the remote party.</param>
''' <param name="acceptableIssuers">A String array of certificate issuers acceptable to the remote party.</param>
''' <returns>An X509Certificate to use for establishing the SSL connection.</returns>
Private Function selectLocalCertificate(ByVal sender As Object, ByVal targetHost As String, ByVal localCertificates As X509CertificateCollection, ByVal remoteCertificate As X509Certificate, ByVal acceptableIssuers() As String) As X509Certificate
    'Try to find the Dart Test Certificate
    Dim certificateStore As New X509Store(StoreName.My)
    certificateStore.Open(OpenFlags.ReadOnly)
    For Each cert As X509Certificate2 In certificateStore.Certificates
        If cert.GetNameInfo(X509NameType.SimpleName, True) = "DartdomCA" Then
            certificateStore.Close()
            Return cert
        End If
    Next cert
    'Certificate not found, return null
    Return Nothing
End Function

''' <summary>
''' Presents the server's certificate for validation.
''' </summary>
''' <param name="certificate">The certificate presented by the server</param>
''' <param name="chain">The chain of certificate authorities associated with the remote certificate</param>
''' <param name="sslPolicyErrors">One or more errors associated with the server's certificate</param>
''' <returns>A Boolean value that specifies whether the presented certificate is accepted for authentication</returns>
Private Function certificateReceived(ByVal sender As Object, ByVal certificate As X509Certificate, ByVal chain As X509Chain, ByVal sslPolicyErrors As SslPolicyErrors) As Boolean
    'Accept certificate if it passed standard validation.
    If sslPolicyErrors = System.Net.Security.SslPolicyErrors.None Then
        Return True
    End If

    Dim msg As String = "The server could not be validated for the following reason(s):"

    If (sslPolicyErrors And System.Net.Security.SslPolicyErrors.RemoteCertificateNotAvailable) = System.Net.Security.SslPolicyErrors.RemoteCertificateNotAvailable Then
        msg &= Environment.NewLine & "    -The server did not present a certificate."
    Else
        If (sslPolicyErrors And System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch) = System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch Then
            msg &= Environment.NewLine & "    -Certificate name mismatch."
        End If
        If (sslPolicyErrors And System.Net.Security.SslPolicyErrors.RemoteCertificateChainErrors) = System.Net.Security.SslPolicyErrors.RemoteCertificateChainErrors Then
            msg &= Environment.NewLine & "    -Certificate chain errors:" & Environment.NewLine

            For Each item As X509ChainStatus In chain.ChainStatus
                msg &= "    --" & item.StatusInformation
            Next item
        End If
    End If

    'Prompt to override security check
    msg &= Environment.NewLine & "Override security check?"
    If MessageBox.Show(msg, "Security Alert: Server could not be validated", MessageBoxButtons.YesNo, MessageBoxIcon.Exclamation) = System.Windows.Forms.DialogResult.Yes Then
        Return True
    Else
        Return False
    End If
End Function

Reference

TcpBase Class
TcpBase Members
Overload List