Secure Echo Client Example

In the SocketWrench control, a number of properties have been added to support secure connections. Note that a secure connection requires a Secure Edition development license. The boolean Secure property controls whether or not a secure connection is established, and must be explicitly set in code prior to making the connection attempt or accepting a connection from a client. The default value for this property is False, which means that the control should establish a standard (non-secure) connection to the server. By setting this property to True, the control will attempt to establish a secure connection.

To use the secure features of SocketWrench, let's modify our echo client/server example to establish a secure connection. The first thing that we need to do is use a different port number than the standard echo port. For purposes of this example, we'll use port 7000 for our secure client and servers program. Modify the command button's Click event to use this new port number and set the Secure property to True.

Private Sub Command1_Click()

    If Not SocketWrench1.Connected Then
        Dim strRemoteHost As String
        Dim nError As Long

        strRemoteHost = Trim(Text1.Text)

        SocketWrench1.Blocking = False
        SocketWrench1.Secure = True

        nError = SocketWrench1.Connect(strRemoteHost, 7000)

        If nError <> 0 Then
            MsgBox "Unable to connect to remote host", vbExclamation
            Exit Sub
        End If

        Command1.Enabled = False
    Else
        SocketWrench1.Disconnect
        Command1.Caption = "Connect"
        Text2.Enabled = False
        Text3.Enabled = False
    End If

End Sub

Once a secure connection has been established, a number of other security related properties become available to the control. These fall into two general groups, returning information either about the secure connection itself, or about the server's digital certificate. The properties which provide information about the connection are:

CipherStrength	This property returns information about the relative strength of the encryption that is being used to secure the data. The value returned is actually the length of the key (in bits) used by the encryption algorithm, and will typically be 40, 56 or 128. A key length of 40 bits is considered to be weak, while a key length of 56 bits is considered to be moderate and 128 bit keys are considered to be very secure.
HashStrength	This property returns information about the strength of the message digest (hash) that was selected. Common values returned by this property are 128 and 160.
SecureCipher	This property identifies the encryption algorithm that was selected. The algorithms supported are RC2, RC4, DES, and Triple DES. The most commonly used algorithm is RC4.
SecureHash	This property identifies the message digest (hash) algorithm that was selected. The algorithms supported are SHA and MD5. The most commonly used message digest is MD5. This algorithm is used during the handshake phase between the client and server, and is made available to the client for informational purposes.
SecureKeyExchange	This property identifies the key exchange algorithm that was selected. The algorithms supported are RSA, KEA and Diffie-Hellman. The most commonly used key exchange algorithm is RSA.
SecureProtocol	This property identifies the protocol used to establish the secure connection. The protocols supported are SSL 2.0, SSL 3.0, PCT 1.0 and TLS 1.0.

In addition to information about the secure connection, there are several properties which return information about the remote host's digital certificate. These properties are:

CertificateExpires	This property returns the date that the server's certificate expires.
CertificateIssued	This property returns the date that the server's certificate was issued by the certificate authority.
CertificateIssuer	This property returns information about the organization that issued the certificate. The data is returned as a string which contains one or more tagged name and value pairs.
CertificateStatus	This property returns information about the status of the certificate. The client is responsible for checking this value, and based on the value returned, decide if the connection should be terminated or not.
CertificateSubject	This property returns information about the organization that the certificate was issued to. Like the CertificateIssuer property, this property returns a string which contains one or more tagged name and value pairs.

It is recommended that your application immediately check the value of the CertificateStatus property after the secure connection has been established. This allows your application to make the decision as to whether or not it is safe to communicate with the server based on the status of the digital certificate it returns. For example, using the above code the CertificateStatus property would return a value of 1 (swCertificateValid), which indicates that the certificate is valid. However, let's modify the code slightly, changing the value of the host name to the IP address for that same server. If you executed the program again, this time the CertificateStatus property would return a value of 2 (swCertificateNoMatch). What this tells you is that, although the certificate is valid, the name in the certificate does not match the host name that you used to connect to the server. This is because you've specified an IP address, but the name in the certificate is normally the domain name for the server. Note that you can try the same thing with your web browser specifying the IP address instead of the domain name in the URL and you should get a warning that the site name doesn't match the certificate name.

So, let's say that for your application it is acceptable to connect to a site if the certificate is valid, or if the domain name does not match the name in the certificate; however, it is not acceptable to connect to a site where the certificate has expired, has been revoked, is not trusted or invalid. You could write code that looks like this:

Private Sub SocketWrench1_OnConnect()
    Command1.Caption = "Disconnect"
    Command1.Enabled = True
    MsgBox "Connect to remote host", vbInformation
    Text2.Enabled = True
    Text3.Enabled = True
    If SocketWrench1.CertificateStatus > swCertificateNoMatch Then
        MsgBox "The certificate could not be validated", vbExclamation
        SocketWrench1_Disconnect
        Exit Sub
    End If

End Sub

If you wanted to display specific information about a certificate, for example, the name of the organization that issued the certificate or the name of the company that it was issued to, you would need to use the CertificateIssuer and CertificateSubject properties. These are strings that consist of one or more values, separated by a comma. Each comma-separated value is a tagged pair of values which provides information about the certificate. For example:

C=US, O="RSA Data Security, Inc."

In this case, there are two values:

C=US
O="RSA Data Security, Inc."

Each of these values consist of an identifier called an RDN (Relative Distinguished Name) and its data. Since the second value contains a comma, it is enclosed in quotes, so this needs to be accounted for when parsing the string. There are a predefined set of RDNs defined by the X.500 standard which are used in certificates. The most commonly used RDNs in X.509 certificates are:

C	The ISO standard two character country code
S	The name of the state or province
L	The name of the city or locality
O	The name of the company or organization
OU	The name of the department or organizational unit
CN	The common name; with X.509 certificates, this is the domain name of the site the certificate was issued for

So, for example, if you wanted to determine the domain name that a certificate was issued for, you would need to read the value of the CertificateSubject property and parse the resulting string for the "CN" (Common Name) RDN. The samples included with SocketWrench include code which displays certificate information and provides some general purpose routines for parsing the CertificateIssuer and CertificateSubject properties.