WebSocket TLS (wss://) 支持

概述

WebSocket 类库支持 TLS 加密通信：

• cWebSocketServer：通过链式函数配置 TLS 证书，监听 wss:// 连接
• cWebSocketClient：使用 wss:// URL 自动启用 TLS，无需额外配置

底层依赖 cWinsock 的 TLS 能力（cWinsock → cTlsSocket）。

cWebSocketServer

链式函数

TlsCertFile — 证书文件模式

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

参数	类型	必要	说明
CertFile	String	是	证书文件路径，PFX/P12 或 PEM 格式
Password	String	否	证书密码
AlpnProtocols	String	否	ALPN 协议，默认留空（WebSocket 不需要 ALPN）

TlsCertSubject — Windows 证书存储模式

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

TlsCertMemory — 内存证书集合模式

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

注意： WebSocket 的 AlpnProtocols 默认留空，因为 WebSocket 有自己的升级机制，通常不需要 ALPN 协商。

使用示例

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

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

' Windows 证书存储
wsSvr.TlsCertSubject("ws.example.com").Listen 443

' 纯 ws://（不调用 Tls 函数）
wsSvr.Listen 8080

cWebSocketClient

自动 TLS

客户端使用 wss:// URL 时自动启用 TLS，无需手动调用任何函数。

' wss:// 自动启用 TLS
Dim wsCli As New cWebSocketClient
wsCli.Connect "wss://example.com/ws"

' ws:// 无变化
wsCli.Connect "ws://localhost:8080/ws"

改造说明

原来的代码显式拒绝 wss://：

' 旧代码（已删除）
If m_IsSecure Then
    RaiseError "Secure WebSocket (wss://) is not yet supported"
    Exit Sub
End If

现在改为自动启用：

' 新代码
If m_IsSecure Then
    m_Socket.Tls  ' 自动启用 TLS
End If
m_Socket.Connect m_Host, m_Port

证书验证

客户端可通过 cWinsock 的 ServerCertificateVerify 事件自定义证书验证逻辑。默认自动信任所有证书。

证书来源说明

三种证书模式的详细介绍，参见 TLS 证书配置总览：

证书模式	详见
TlsCertFile（证书文件）	证书文件模式
TlsCertSubject（Windows 证书存储）	Windows 证书存储模式
TlsCertMemory（内存证书集合）	内存证书集合模式

内部机制

TLS 模式枚举

Private Enum EnumWsTlsMode
    WsTlsNone          ' 未启用（默认，ws://）
    WsTlsModeCertFile  ' 证书文件
    WsTlsModeSubject   ' Windows 证书存储
    WsTlsModeMemory    ' 内存证书集合
End Enum

依赖关系

cWebSocketServer ──使用──→ cWinsock ──使用──→ cTlsSocket
cWebSocketClient  ──使用──→ cWinsock ──使用──→ cTlsSocket

前提条件： cWinsock 必须先支持 TLS（已完成）。

透明性

TLS 对 WebSocket 帧解析完全透明：

• cWebSocketFrame — 帧编解码与传输层无关
• cByteBuffer — 缓冲区与传输层无关
• cWebSocketUtils — 工具函数与传输层无关

注意事项

1. wss:// 默认端口 443：URL 解析已支持，wss:// 自动设端口为 443
2. 证书错误处理：无效证书时客户端收到 OnError 事件
3. 帧传输：加密不影响分片和大数据帧传输
4. AlpnProtocols：WebSocket 通常不需要 ALPN，默认留空
5. 停止服务后 TLS 状态自动重置：StopServer() 清空所有 TLS 配置