cWinsock TLS/SSL Support

Overview

cWinsock supports TLS/SSL encrypted communication for both TCP server and client modes. Through chained function configuration, TLS certificates can be easily set up to achieve encrypted data transmission.

Function Signatures

Server-Side Certificate Configuration

TlsCertFile — Certificate File Mode

Public Function TlsCertFile( _
    ByVal CertFile As String, _
    Optional ByVal Password As String, _
    Optional ByVal AlpnProtocols As String = "http/1.1") As cWinsock

Parameter	Type	Required	Description
CertFile	String	Yes	Certificate file path, supports PFX/P12 and PEM formats
Password	String	No	Certificate password
AlpnProtocols	String	No	ALPN protocol negotiation, default "http/1.1"

TlsCertSubject — Windows Certificate Store Mode

Public Function TlsCertSubject( _
    ByVal CertSubject As String, _
    Optional ByVal AlpnProtocols As String = "http/1.1") As cWinsock

Parameter	Type	Required	Description
CertSubject	String	Yes	Certificate subject name
AlpnProtocols	String	No	ALPN protocol negotiation

TlsCertMemory — Memory Certificate Collection Mode

Public Function TlsCertMemory( _
    ByVal Certificates As Collection, _
    ByVal PrivateKey As Collection, _
    Optional ByVal AlpnProtocols As String = "http/1.1") As cWinsock

Client-Side TLS Enable (No Certificate Needed)

' Client only needs to call .Tls before Connect, no certificate needed
m_oClient.Tls.Connect "example.com", 443

Usage Examples

TLS TCP Server

Dim svr As New cWinsock

' PFX certificate with password
svr.TlsCertFile("C:\certs\server.pfx", "password").Listen 443

' PEM certificate (multiple files separated by |)
svr.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Listen 443

' Windows Certificate Store
svr.TlsCertSubject("tcp.example.com").Listen 443

TLS TCP Client

Dim cli As New cWinsock

' Connect to TLS server (no certificate needed for client)
cli.Tls.Connect "example.com", 443

' Or connect first, then upgrade to TLS
cli.Connect "example.com", 443
cli.Tls ' Upgrade current connection to TLS

Complete TLS Client Example

Private WithEvents m_oClient As cWinsock

Private Sub Form_Load()
    Set m_oClient = New cWinsock
    
    ' Set TCP protocol
    m_oClient.Protocol = sckTCPProtocol
    
    ' Connect and enable TLS
    m_oClient.Tls.Connect "example.com", 443
    
    Debug.Print "Connecting to TLS server..."
End Sub

Private Sub m_oClient_Connect(Client As cWinsock)
    Debug.Print "TLS connection established"
    
    ' Send encrypted data
    Client.SendData "Hello, Secure World!"
End Sub

Private Sub m_oClient_DataArrival(Client As cWinsock, ByVal bytesTotal As Long)
    Dim sData As String
    Client.GetData sData
    Debug.Print "Received (encrypted): " & sData
End Sub

Private Sub Form_Unload(Cancel As Integer)
    On Error Resume Next
    m_oClient.Close_
End Sub

TLS Server with Packet Protocol

Private WithEvents m_oServer As cWinsock

Private Sub Form_Load()
    Set m_oServer = New cWinsock
    
    ' Set packet protocol
    m_oServer.PacketProtocol = ppLengthHeader
    m_oServer.HeaderBytes = 4
    
    ' Start TLS server
    m_oServer.TlsCertFile("C:\certs\server.pfx", "password").Listen 443
    
    Debug.Print "TLS server started on port 443"
End Sub

Private Sub m_oServer_ConnectionRequest(Client As cWinsock, ByRef DisConnect As Boolean)
    Debug.Print "New TLS client: " & Client.RemoteHostIP
End Sub

Private Sub m_oServer_MessageArrival(Client As cWinsock, ByVal bytesTotal As Long)
    Dim sData As String
    sData = Client.GetDataText()
    Debug.Print "Received: " & sData
    
    ' Reply with encrypted data
    Client.SendData "Echo: " & sData
End Sub

Supported TLS Versions

• TLS 1.2
• TLS 1.3

Certificate Format Support

Format	Extension	Description
PKCS#12	.pfx, .p12	Binary format, contains certificate chain + private key
PEM	.pem, .crt, .key	Base64 text format

Certificate Chain

For PEM format, you can use | to separate multiple certificate files:

' fullchain.pem contains server certificate + intermediate certificates
' privkey.pem contains private key
svr.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Listen 443

ALPN Protocol Negotiation

Application-Layer Protocol Negotiation (ALPN) allows client and server to negotiate application protocol during TLS handshake.

' Default is "http/1.1", can be customized
svr.TlsCertFile("C:\certs\server.pfx", "", "my-protocol").Listen 443

Underlying Implementation

cWinsock ──uses──→ cTlsSocket ──uses──→ OpenSSL

All TLS operations are handled by cTlsSocket class, based on OpenSSL implementation.

Certificate Verification

Server Certificate Verification (Client-side)

Clients can customize certificate verification logic through events:

Private Sub m_oClient_ServerCertificateVerify( _
    ByVal Certificate As String, _
    ByVal Trusted As Boolean, _
    Allow As Boolean)
    
    ' Certificate: Base64 encoded certificate
    ' Trusted: Whether certificate is in system trust store
    ' Allow: Set to True to allow connection, False to reject
    
    If Trusted Then
        Allow = True
    Else
        ' Custom verification logic
        Allow = VerifyCustom(Certificate)
    End If
End Sub

Skip Certificate Verification (Development Only)

' Allow all certificates (insecure, for development only)
Private Sub m_oClient_ServerCertificateVerify(ByVal Certificate As String, ByVal Trusted As Boolean, Allow As Boolean)
    Allow = True
End Sub

Error Handling

Common TLS Errors

Error	Cause	Solution
Certificate not found	File path error or certificate not installed	Check file path or certificate store
Password error	Wrong PFX password	Confirm password correct
Certificate expired	Certificate past validity period	Update certificate
Handshake failed	Protocol mismatch or certificate issue	Check TLS version and certificate chain

Related Documentation

• TLS Certificate Configuration Overview
• Certificate File Mode
• Windows Certificate Store Mode
• Memory Certificate Collection Mode
• cHttpServer TLS Support
• cWebSocket TLS Support

---

Last Updated: 2026-06-09