Certificate File Mode (TlsCertFile)

Overview

Certificate file mode is the most commonly used and simplest TLS configuration method. Pass the certificate file path and password to the TlsCertFile() chained function, and the underlying layer automatically parses the file format and loads the certificate.

Function Signature

Public Function TlsCertFile( _
    ByVal CertFile As String, _
    Optional ByVal Password As String, _
    Optional ByVal AlpnProtocols As String = "...") As <ComponentType>

Parameters

Parameter	Type	Required	Description
CertFile	String	Yes	Certificate file path, supports PFX/P12 and PEM formats
Password	String	No	Certificate password. Leave empty for PEM with unencrypted private key
AlpnProtocols	String	No	ALPN protocol negotiation. Default values vary by component, see table below

Component	AlpnProtocols Default
cHttpServer	"http/1.1"
cWinsock	"http/1.1"
cWebSocketServer	"" (Empty)

Supported File Formats

1. PFX / P12 (PKCS#12)

Binary format, single file containing certificate chain and private key, most convenient for management.

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

Characteristics:

• Single file contains complete certificate chain + private key
• Supports password protection
• Windows certificate export standard format
• Default format for IIS certificate export

Acquisition Methods:

• Download from CA authority
• OpenSSL generation: openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
• OpenSSL to PFX: openssl pkcs12 -export -out server.pfx -inkey key.pem -in cert.pem
• Windows Certificate Manager export (with private key)

2. PEM Format — Single File

Text format, file contains both certificate and private key.

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

File Content Example:

-----BEGIN CERTIFICATE-----
MIIFazCCBFOgAwIBAgISA2Q3p...
(Server certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFazCCBFOgAwIBAgISA3B4q...
(Intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQ...
(Private key)
-----END PRIVATE KEY-----

3. PEM Format — Multiple Files (Use | separator)

Most flexible method, certificate and private key stored in separate files. Use | pipe character to separate multiple file paths.

' Let's Encrypt standard output format
Server.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Start 443

' Three files: certificate + intermediate + private key
Server.TlsCertFile("C:\certs\cert.pem|C:\certs\chain.pem|C:\certs\privkey.pem").Start 443

Underlying Processing:

1. First attempts PKCS#12 parsing (for single files)
2. On failure, splits CertFile by | into array
3. Calls PEM parsing for each file path
4. Automatically identifies PEM block types (CERTIFICATE / PRIVATE KEY / RSA PRIVATE KEY / EC PRIVATE KEY)

Usage Examples by Component

cHttpServer (HTTPS)

' PEM multiple files (Let's Encrypt most common)
Server.TlsCertFile("C:\certs\fullchain.pem|C:\certs\privkey.pem").Start 443

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

' PEM single file
Server.TlsCertFile("C:\certs\server.pem").Start 443

' HTTP + HTTPS dual ports
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)

' Server: Present certificate
Dim svr As New cWinsock
svr.TlsCertFile("C:\certs\server.pfx", "password").Listen 443

' Client: Just enable TLS (no certificate needed)
Dim cli As New cWinsock
cli.Tls.Connect "example.com", 443

cWebSocketServer (wss://)

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

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

Let's Encrypt Automation

Let's Encrypt is the most common free certificate source, and its output files perfectly match the PEM multi-file mode:

/etc/letsencrypt/live/example.com/
├── fullchain.pem   ← Server certificate + Intermediate certificate
├── privkey.pem     ← Private key
├── cert.pem        ← Server certificate only
└── chain.pem       ← Intermediate certificate only

' Using fullchain + privkey (recommended)
Server.TlsCertFile("/etc/letsencrypt/live/example.com/fullchain.pem|" & _
                   "/etc/letsencrypt/live/example.com/privkey.pem").Start 443

Note: On Windows use backslash C:\certs\fullchain.pem|C:\certs\privkey.pem.

Self-Signed Certificates (Development/Testing)

Use OpenSSL to generate self-signed certificates:

# Generate private key and certificate (valid for 365 days)
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

# Merge into single PEM file
type cert.pem key.pem > server.pem

# Or convert to PFX
openssl pkcs12 -export -out server.pfx -inkey key.pem -in cert.pem

' Use self-signed PEM
Server.TlsCertFile("C:\dev\server.pem").Start 443

' Use self-signed PFX
Server.TlsCertFile("C:\dev\server.pfx").Start 443

Certificate Chain Completeness

PEM format must contain complete certificate chain, otherwise clients will report untrusted certificate:

✅ Correct: fullchain.pem = Server certificate + Intermediate certificate
❌ Incorrect: cert.pem = Server certificate only (missing intermediate)

Common CA intermediate certificates:

• Let's Encrypt: ISRG Root X1 → R3/R4/R10 etc.
• DigiCert: DigiCert Global Root CA → Intermediate CA
• GlobalSign: GlobalSign Root CA → Intermediate CA

FAQ

1. File path not found

LastError: Certificate file does not exist or format error

Solution: Check if file path is correct, note Windows paths use backslashes.

2. Password error

LastError: Certificate file does not exist or format error

Solution: PFX passwords are case-sensitive, confirm password is correct. Leave Password empty for unencrypted PEM private keys.

3. PEM missing private key

LastError: Certificate file does not exist or format error

Solution: Ensure PEM file or file combination contains -----BEGIN PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY----- block.

4. Certificate expired

Browser shows: Your connection is not private

Solution: Update certificate. Let's Encrypt certificates are valid for 90 days, automatic renewal needs to be configured.

Underlying Processing Flow

TlsCertFile(path, pwd)
    │
    ├─ Attempt PKCS#12 parsing (for single files)
    │   └─ pvPkiPkcs12ImportCertificates()
    │       └─ OpenSSL d2i_PKCS12 + PKCS12_parse
    │
    └─ Attempt PEM parsing (Split by "|")
        └─ pvPkiPemImportCertificates()
            └─ OpenSSL PEM_read_bio_X509 + PEM_read_bio_PrivateKey

Related Documentation

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

---

Last Updated: 2026-06-09