WebSocket TLS (wss://) Support

Overview

WebSocket library supports TLS encrypted communication:

• cWebSocketServer: Configure TLS certificate through chained functions, listen for wss:// connections
• cWebSocketClient: Use wss:// URL to automatically enable TLS, no additional configuration needed

Underlying depends on cWinsock's TLS capability (cWinsock → cTlsSocket).

cWebSocketServer

Chained Functions

TlsCertFile — Certificate File Mode

Public Function TlsCertFile( _
    ByVal CertFile As String, _
    Optional ByVal Password As String, _
    Optional ByVal AlpnProtocols As String = "") As cWebSocketServer

Parameter	Type	Required	Description
CertFile	String	Yes	Certificate file path, PFX/P12 or PEM format
Password	String	No	Certificate password
AlpnProtocols	String	No	ALPN protocol, default empty (WebSocket doesn't need ALPN)

TlsCertSubject — Windows Certificate Store Mode

Public Function TlsCertSubject( _
    ByVal CertSubject As String, _
    Optional ByVal AlpnProtocols As String = "") As cWebSocketServer

TlsCertMemory — Memory Certificate Collection Mode

Public Function TlsCertMemory( _
    ByVal Certificates As Collection, _
    ByVal PrivateKey As Collection, _
    Optional ByVal AlpnProtocols As String = "") As cWebSocketServer

Note: WebSocket's AlpnProtocols defaults to empty because WebSocket has its own upgrade mechanism, usually no ALPN negotiation needed.

Usage Examples

' PFX certificate
Dim wsSvr As New cWebSocketServer
wsSvr.TlsCertFile("C:\certs\server.pfx", "password").Listen 443

' PEM certificate
wsSvr.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Listen 443

' Windows Certificate Store
wsSvr.TlsCertSubject("ws.example.com").Listen 443

' Pure ws:// (No TLS functions called)
wsSvr.Listen 8080

cWebSocketClient

Automatic TLS

Client automatically enables TLS when using wss:// URL, no manual function calls needed.

' wss:// automatically enables TLS
Dim wsCli As New cWebSocketClient
wsCli.Connect "wss://example.com/ws"

' ws:// unchanged
wsCli.Connect "ws://localhost:8080/ws"

Refactoring Notes

Original code explicitly rejected wss://:

' Old code (deleted)
If m_IsSecure Then
    RaiseError "Secure WebSocket (wss://) is not yet supported"
    Exit Sub
End If

Now changed to automatic enable:

' New code
If m_IsSecure Then
    m_Socket.Tls  ' Automatically enable TLS
End If
m_Socket.Connect m_Host, m_Port

Certificate Verification

Client can customize certificate verification logic through cWinsock's ServerCertificateVerify event. By default automatically trusts all certificates.

Certificate Source Documentation

Detailed introduction to three certificate modes, see TLS Certificate Configuration Overview:

Certificate Mode	Details
TlsCertFile (Certificate File)	Certificate File Mode
TlsCertSubject (Windows Certificate Store)	Windows Certificate Store Mode
TlsCertMemory (Memory Certificate Collection)	Memory Certificate Collection Mode

Internal Mechanism

TLS Mode Enum

Private Enum EnumWsTlsMode
    WsTlsNone          ' Not enabled (default, ws://)
    WsTlsModeCertFile  ' Certificate file
    WsTlsModeSubject   ' Windows Certificate Store
    WsTlsModeMemory    ' Memory certificate collection
End Enum

Dependency Relationship

cWebSocketServer ──uses──→ cWinsock ──uses──→ cTlsSocket
cWebSocketClient  ──uses──→ cWinsock ──uses──→ cTlsSocket

Prerequisite: cWinsock must support TLS first (completed).

Transparency

TLS is completely transparent to WebSocket frame parsing:

• cWebSocketFrame — Frame encoding/decoding independent of transport layer
• cByteBuffer — Buffer independent of transport layer
• cWebSocketUtils — Utility functions independent of transport layer

Notes

1. wss:// default port 443: URL parsing already supported, wss:// automatically sets port to 443
2. Certificate error handling: Invalid certificates trigger OnError event on client
3. Frame transmission: Encryption doesn't affect fragmentation and large data frame transmission
4. AlpnProtocols: WebSocket usually doesn't need ALPN, defaults to empty
5. TLS state automatically resets after stopping service: StopServer() clears all TLS configuration