证书文件模式 (TlsCertFile)

概述

证书文件模式是最常用、最简单的 TLS 配置方式。将证书文件路径和密码传入 TlsCertFile() 链式函数，底层自动解析文件格式并加载证书。

函数签名

Public Function TlsCertFile( _
    ByVal CertFile As String, _
    Optional ByVal Password As String, _
    Optional ByVal AlpnProtocols As String = "...") As <组件类型>

参数

参数	类型	必要	说明
CertFile	String	是	证书文件路径，支持 PFX/P12 和 PEM 格式
Password	String	否	证书密码。PEM 无加密私钥时留空
AlpnProtocols	String	否	ALPN 协议协商。各组件默认值不同，见下表

组件	AlpnProtocols 默认值
cHttpServer	"http/1.1"
cWinsock	"http/1.1"
cWebSocketServer	""（空）

支持的文件格式

1. PFX / P12（PKCS#12）

二进制格式，单文件包含证书链和私钥，最方便管理。

Server.TlsCertFile("C:\certs\server.pfx", "my-password").Start 443

特点：

• 单文件包含完整证书链 + 私钥
• 支持密码保护
• Windows 证书导出标准格式
• IIS 证书导出的默认格式

获取方式：

• 从 CA 机构下载
• OpenSSL 生成：openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
• OpenSSL 转 PFX：openssl pkcs12 -export -out server.pfx -inkey key.pem -in cert.pem
• Windows 证书管理器导出（含私钥）

2. PEM 格式 — 单文件

文本格式，文件中同时包含证书和私钥。

Server.TlsCertFile("C:\certs\server.pem").Start 443

文件内容示例：

-----BEGIN CERTIFICATE-----
MIIFazCCBFOgAwIBAgISA2Q3p...
（服务器证书）
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFazCCBFOgAwIBAgISA3B4q...
（中间证书）
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQ...
（私钥）
-----END PRIVATE KEY-----

3. PEM 格式 — 多文件（用 | 分隔）

最灵活的方式，证书和私钥分别存放在不同文件中。使用 | 管道符分隔多个文件路径。

' Let's Encrypt 标准输出格式
Server.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Start 443

' 三文件：证书 + 中间证书 + 私钥
Server.TlsCertFile("C:\certs\cert.pem|C:\certs\chain.pem|C:\certs\privkey.pem").Start 443

底层处理：

1. 首先尝试作为 PFX/P12 解析（单文件时）
2. 失败后将 CertFile 按 | 分割为数组
3. 对每个文件路径调用 PEM 解析
4. 自动识别 PEM 块类型（CERTIFICATE / PRIVATE KEY / RSA PRIVATE KEY / EC PRIVATE KEY）

各组件使用示例

cHttpServer（HTTPS）

' PEM 多文件（Let's Encrypt 最常见）
Server.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Start 443

' PFX 带密码 + WebRoot
Server.TlsCertFile("C:\certs\server.pfx", "password").WebRoot("C:\www").Start 443

' PEM 单文件
Server.TlsCertFile("C:\certs\server.pem").Start 443

' HTTP + HTTPS 双端口
Dim httpSvr As New cHttpServer
httpSvr.WebRoot("C:\www").Start 80

Dim httpsSvr As New cHttpServer
httpsSvr.TlsCertFile("C:\certs\server.pfx", "pwd").WebRoot("C:\www").Start 443

cWinsock（TLS TCP）

' 服务端：出示证书
Dim svr As New cWinsock
svr.TlsCertFile("C:\certs\server.pfx", "password").Listen 443

' 客户端：只需启用 TLS（无需证书）
Dim cli As New cWinsock
cli.Tls.Connect "example.com", 443

cWebSocketServer（wss://）

' 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

Let's Encrypt 自动化

Let's Encrypt 是最常见的免费证书来源，其输出文件与 PEM 多文件模式完美匹配：

/etc/letsencrypt/live/example.com/
├── fullchain.pem   ← 服务器证书 + 中间证书
├── privkey.pem     ← 私钥
├── cert.pem        ← 仅服务器证书
└── chain.pem       ← 仅中间证书

' 使用 fullchain + privkey（推荐）
Server.TlsCertFile("/etc/letsencrypt/live/example.com/fullchain.pem|" & _
                   "/etc/letsencrypt/live/example.com/privkey.pem").Start 443

注意： Windows 上路径使用反斜杠 C:\certs\fullchain.pem|C:\certs\privkey.pem。

自签名证书（开发测试）

使用 OpenSSL 生成自签名证书：

# 生成私钥和证书（有效期 365 天）
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

# 合并为单文件 PEM
type cert.pem key.pem > server.pem

# 或转换为 PFX
openssl pkcs12 -export -out server.pfx -inkey key.pem -in cert.pem

' 使用自签名 PEM
Server.TlsCertFile("C:\dev\server.pem").Start 443

' 使用自签名 PFX
Server.TlsCertFile("C:\dev\server.pfx").Start 443

证书链完整性

PEM 格式必须包含完整的证书链，否则客户端会报证书不可信：

✅ 正确：fullchain.pem = 服务器证书 + 中间证书
❌ 错误：cert.pem = 仅服务器证书（缺少中间证书）

常见 CA 的中间证书：

• Let's Encrypt：ISRG Root X1 → R3/R4/R10 等
• DigiCert：DigiCert Global Root CA → 中间 CA
• GlobalSign：GlobalSign Root CA → 中间 CA

常见问题

1. 文件路径找不到

LastError: 证书文件不存在或格式错误

解决： 检查文件路径是否正确，注意 Windows 路径使用反斜杠。

2. 密码错误

LastError: 证书文件不存在或格式错误

解决： PFX 密码区分大小写，确认密码正确。PEM 私钥未加密时 Password 留空。

3. PEM 缺少私钥

LastError: 证书文件不存在或格式错误

解决： 确保 PEM 文件或文件组合中包含 -----BEGIN PRIVATE KEY----- 或 -----BEGIN RSA PRIVATE KEY----- 块。

4. 证书过期

浏览器显示：您的连接不是私密连接

解决： 更新证书。Let's Encrypt 证书有效期 90 天，需配置自动续期。

底层处理流程

TlsCertFile(path, pwd)
    │
    ├─ 尝试 PKCS#12 解析（单文件时）
    │   └─ pvPkiPkcs12ImportCertificates()
    │       └─ OpenSSL d2i_PKCS12 + PKCS12_parse
    │
    └─ 尝试 PEM 解析（Split by "|"）
        └─ pvPkiPemImportCertificates()
            └─ OpenSSL PEM_read_bio_X509 + PEM_read_bio_PrivateKey

相关文档

• TLS 证书配置总览
• Windows 证书存储模式
• 内存证书集合模式
• cHttpServer TLS 支持
• cWinsock TLS 支持
• cWebSocket TLS 支持

---

最后更新: 2026-06-09