PowerTCP Telnet for .NET CF
AuthenticateAsClient(String,X509CertificateCollection,SslProtocols,Boolean,RemoteCertificateValidationCallback,LocalCertificateSelectionCallback) Method
See Also  Example Send comments on this topic.
Dart.Common Namespace > TcpBase Class > AuthenticateAsClient Method : AuthenticateAsClient(String,X509CertificateCollection,SslProtocols,Boolean,RemoteCertificateValidationCallback,LocalCertificateSelectionCallback) Method




targetHost
The name of the remote host to be authenticated.
clientCertificates
A collection of client certificates to select from during the authentication.
enabledSslProtocols
The enabled SSL protocols.
checkCertificateRevocation
Whether or not the certificate revocation list is checked during authentication.
userCertificateValidationCallback
The callback function that executes after the server presents its certificate.
userCertificateSelectionCallback
The callback function that executes after the server requests a certificate.
Authenticates the server when establishing a secure connection.

Syntax

Visual Basic (Declaration) 
Public Overloads Sub AuthenticateAsClient( _
   ByVal targetHost As String, _
   ByVal clientCertificates As X509CertificateCollection, _
   ByVal enabledSslProtocols As SslProtocols, _
   ByVal checkCertificateRevocation As Boolean, _
   ByVal userCertificateValidationCallback As RemoteCertificateValidationCallback, _
   ByVal userCertificateSelectionCallback As LocalCertificateSelectionCallback _
) 
Visual Basic (Usage)Copy Code
Dim instance As TcpBase
Dim targetHost As String
Dim clientCertificates As X509CertificateCollection
Dim enabledSslProtocols As SslProtocols
Dim checkCertificateRevocation As Boolean
Dim userCertificateValidationCallback As RemoteCertificateValidationCallback
Dim userCertificateSelectionCallback As LocalCertificateSelectionCallback
 
instance.AuthenticateAsClient(targetHost, clientCertificates, enabledSslProtocols, checkCertificateRevocation, userCertificateValidationCallback, userCertificateSelectionCallback)

Parameters

targetHost
The name of the remote host to be authenticated.
clientCertificates
A collection of client certificates to select from during the authentication.
enabledSslProtocols
The enabled SSL protocols.
checkCertificateRevocation
Whether or not the certificate revocation list is checked during authentication.
userCertificateValidationCallback
The callback function that executes after the server presents its certificate.
userCertificateSelectionCallback
The callback function that executes after the server requests a certificate.

Example

This example demonstrates the AuthenticateAsClient call and the callback that executes when a certificate is received.
C#Copy Code
private void doAuthentication(string server, SslProtocols protocol, bool checkRevocation)
{
    //Authenticate server and specify certificate callback functions
    myComponent.AuthenticateAsClient(server, null, protocol, checkRevocation, certificateReceived, null);
}

private static bool certificateReceived(object sender, 
    System.Security.Cryptography.X509Certificates.X509Certificate certificate,
    X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
    //Return true if the server certificate is ok
    if (sslPolicyErrors == SslPolicyErrors.None)
        return true;

    bool acceptCertificate = true;
    string msg = "The server could not be validated for the following reason(s):\r\n";

    //The server did not present a certificate
    if ((sslPolicyErrors &
        SslPolicyErrors.RemoteCertificateNotAvailable) == SslPolicyErrors.RemoteCertificateNotAvailable)
    {
        msg = msg + "\r\n    -The server did not present a certificate.\r\n";
        acceptCertificate = false;
    }
    else
    {
        //The certificate does not match the server name
        if ((sslPolicyErrors &
            SslPolicyErrors.RemoteCertificateNameMismatch) == SslPolicyErrors.RemoteCertificateNameMismatch)
        {
            msg = msg + "\r\n    -The certificate name does not match the authenticated name.\r\n";
            acceptCertificate = false;
        }

        //There is some other problem with the certificate
        if ((sslPolicyErrors &
            SslPolicyErrors.RemoteCertificateChainErrors) == SslPolicyErrors.RemoteCertificateChainErrors)
        {
            foreach (X509ChainStatus item in chain.ChainStatus)
            {
                if (item.Status != X509ChainStatusFlags.RevocationStatusUnknown &&
                    item.Status != X509ChainStatusFlags.OfflineRevocation)
                    break;

                if (item.Status != X509ChainStatusFlags.NoError)
                {
                    msg = msg + "\r\n    -" + item.StatusInformation;
                    acceptCertificate = false;
                }
            }
        }
    }

    //If Validation failed, present message box
    if (acceptCertificate == false)
    {
        msg = msg + "\r\nDo you wish to override the security check?";
        if (MessageBox.Show(msg, "Security Alert: Server could not be validated",
            MessageBoxButtons.YesNo, MessageBoxIcon.Exclamation, MessageBoxDefaultButton.Button1) == DialogResult.Yes)
            acceptCertificate = true;
    }

    return acceptCertificate;
}
Visual BasicCopy Code
Private Sub doAuthentication(ByVal server As String, ByVal protocol As SslProtocols, _
	ByVal checkRevocation As Boolean)
	'Authenticate server and specify certificate callback functions
	myComponent.AuthenticateAsClient(server, Nothing, protocol, checkRevocation, _
		AddressOf certificateReceived, Nothing)
End Sub

Private Shared Function certificateReceived(ByVal sender As Object, _
	ByVal certificate As System.Security.Cryptography.X509Certificates.X509Certificate, _
	ByVal chain As X509Chain, ByVal sslPolicyErrors As SslPolicyErrors) As Boolean
	'Return true if the server certificate is ok
	If sslPolicyErrors = SslPolicyErrors.None Then
		Return True
	End If

	Dim acceptCertificate As Boolean = True
	Dim msg As String = "The server could not be validated for the following reason(s):" & Constants.vbCrLf

	'The server did not present a certificate
	If (sslPolicyErrors And _
		SslPolicyErrors.RemoteCertificateNotAvailable) = SslPolicyErrors.RemoteCertificateNotAvailable Then
		msg = msg & Constants.vbCrLf & "    -The server did not present a certificate." & Constants.vbCrLf
		acceptCertificate = False
	Else
		'The certificate does not match the server name
		If ((sslPolicyErrors And _
			SslPolicyErrors.RemoteCertificateNameMismatch) = SslPolicyErrors.RemoteCertificateNameMismatch) Then
			msg = msg & Constants.vbCrLf & _ 
				"    -The certificate name does not match the authenticated name." & Constants.vbCrLf
				acceptCertificate = False
		End If
		
		'There is some other problem with the certificate
		If (sslPolicyErrors And _
			SslPolicyErrors.RemoteCertificateChainErrors) = SslPolicyErrors.RemoteCertificateChainErrors Then
			For Each item As X509ChainStatus In chain.ChainStatus
				If item.Status <> X509ChainStatusFlags.RevocationStatusUnknown AndAlso _
					item.Status <> X509ChainStatusFlags.OfflineRevocation Then
					Exit For
				End If

				If (item.Status <> X509ChainStatusFlags.NoError) Then
					msg = msg & Constants.vbCrLf & "    -" & item.StatusInformation
					acceptCertificate = False
				End If
			Next item
		End If
	End If

	'If Validation failed, present message box
	If acceptCertificate = False Then
		msg = msg & Constants.vbCrLf & "Do you wish to override the security check?"
		If MessageBox.Show(msg, "Security Alert: Server could not be validated", _
			MessageBoxButtons.YesNo, MessageBoxIcon.Exclamation, MessageBoxDefaultButton.Button1) _
               = System.Windows.Forms.DialogResult.Yes Then
		   acceptCertificate = True
		End If
	End If

	Return acceptCertificate
End Function

Remarks

The targetHost must match the server certificate name. If authentication fails, an AuthenticationException will occur.

To accept or reject a certificate "on-the-fly" implement a userCertificateValidationCallback function.

To select a client certificate "on-the-fly" implement a userCertificateSelectionCallback function.

Requirements

Target Platforms: Microsoft .NET Framework 2.0

See Also

Documentation Version 4.2
© 2010 Dart Communications. All Rights Reserved.