Windows Certificate Store Mode (TlsCertSubject)

Overview

Windows Certificate Store mode looks up certificates from the operating system's certificate store without specifying file paths. Suitable for the following scenarios:

• Enterprise environment with unified certificate management
• Sharing the same certificate with IIS
• Certificate distribution through Group Policy (GPO)
• Automatic certificate renewal (e.g., Windows Certificate Enrollment)
• Private key files not exposed on disk

Function Signature

Public Function TlsCertSubject( _
    ByVal CertSubject As String, _
    Optional ByVal AlpnProtocols As String = "...") As <ComponentType>

Parameters

Parameter	Type	Required	Description
CertSubject	String	Yes	Certificate subject name (Subject), used to lookup in certificate store
AlpnProtocols	String	No	ALPN protocol negotiation. Default values vary by component

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

CertSubject Parameter Details

CertSubject is the Subject field of the X.509 certificate, used to locate the certificate in Windows Certificate Store.

Subject Format

X.509 Subject uses Distinguished Name (DN) format:

CN=www.example.com, O=Example Inc, L=Beijing, S=Beijing, C=CN

Common fields:

Field	Full Name	Description	Example
CN	Common Name	Common name, usually domain	CN=www.example.com
O	Organization	Organization name	O=Example Inc
OU	Organizational Unit	Department	OU=IT Department
L	Locality	City	L=Beijing
S	State	Province/State	S=Beijing
C	Country	Country code	C=CN

Lookup Rules

Underlying layer uses CertFindCertificateInStore API for fuzzy matching by Subject:

• Passing "www.example.com" will match CN=www.example.com, O=...
• If multiple certificates match, returns the first found
• Recommend using exact CN value to avoid matching wrong certificates

How to View Certificate Subject

Method 1: Certificate Manager

1. Win+R → certmgr.msc (Current User) or certlm.msc (Local Machine)
2. Expand "Personal" → "Certificates"
3. Double-click certificate → "Details" tab → "Subject" field

Method 2: Command Line

certutil -store My

Output example:

Cert Serial Number: ...
Issuer: CN=Example CA ...
NotBefore: ...
NotAfter: ...
Subject: CN=www.example.com, O=Example Inc, L=Beijing, S=Beijing, C=CN

Method 3: PowerShell

Get-ChildItem Cert:\LocalMachine\My | Select-Object Subject, Thumbprint, NotAfter

Certificate Store Locations

Windows Certificate Store has two main categories:

Store Location	Management Tool	Use Case
Current User	certmgr.msc	User-level certificates
Local Machine	certlm.msc	System-level certificates, recommended for services

Underlying API lookup order:

1. MY store (Personal certificates, contains private key)
2. Lookup in both CurrentUser and LocalMachine

Important: Certificates must contain private keys to be used for TLS server. In Certificate Manager, certificates with private keys have a small key icon.

Usage Examples by Component

cHttpServer (HTTPS)

' Use same certificate as IIS
Server.TlsCertSubject("www.example.com").Start 443

' With WebRoot
Server.TlsCertSubject("www.example.com").WebRoot("C:\www").Start 443

cWinsock (TLS TCP Server)

Dim svr As New cWinsock
svr.TlsCertSubject("tcp.example.com").Listen 443

cWebSocketServer (wss://)

Dim wsSvr As New cWebSocketServer
wsSvr.TlsCertSubject("ws.example.com").Listen 443

Certificate Installation

Import from PFX to Certificate Store

Method 1: Certificate Manager GUI

1. certlm.msc → Right-click "Personal" → "All Tasks" → "Import"
2. Select .pfx file
3. Enter password
4. Select "Place all certificates in the following store" → "Personal"
5. Ensure "Mark this key as exportable" is checked (if need to export later)

Method 2: Command Line

certutil -p "password" -importpfx "C:\certs\server.pfx"

Method 3: PowerShell

$pwd = ConvertTo-SecureString -String "password" -AsPlainText -Force
Import-PfxCertificate -FilePath "C:\certs\server.pfx" -CertStoreLocation Cert:\LocalMachine\My -Password $pwd

Grant Private Key Access Permissions

Windows services or specific users need private key read permissions:

1. certlm.msc → Find certificate → Right-click → "All Tasks" → "Manage Private Keys"
2. Add user or group → Grant "Read" permission

PowerShell:

$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -match "www.example.com"}
$rsaCert = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$file = Get-Item -Path $($rsaCert.keyuniquecontainername)
$acl = $file.GetAccessControl()
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule("IIS_IUSRS", "Read", "Allow")
$acl.AddAccessRule($rule)
$file.SetAccessControl($acl)

IIS Shared Certificate Scenario

When server runs both IIS and vbmanlib applications, sharing the same certificate:

1. Bind certificate to port 443 in IIS Manager
2. Certificate automatically installs to LocalMachine\My store
3. vbmanlib application uses TlsCertSubject to reference the same certificate
4. IIS listens on 443, vbmanlib listens on other ports (e.g., 8443)

' IIS uses 443, vbmanlib uses 8443
Server.TlsCertSubject("www.example.com").WebRoot("C:\www").Start 8443

Certificate Renewal

After certificate renewal in Windows Certificate Store, Subject usually remains the same, but Thumbprint changes. Underlying API looks up by Subject, automatically gets the latest version of the certificate.

' No code changes needed after renewal, automatically uses new certificate
Server.TlsCertSubject("www.example.com").Start 443

Note: Application needs to restart to load new certificate, no automatic hot update while running.

Enterprise AD Certificate Services

Large enterprises typically use Active Directory Certificate Services (AD CS):

1. Administrators configure certificate templates in AD CS
2. Domain computers auto-enroll certificates (Auto-Enrollment)
3. Certificates automatically install to LocalMachine\My store
4. Applications use TlsCertSubject directly

AD CS Advantages:

• Automatic certificate issuance and renewal
• Group Policy unified management
• Private keys never leave the machine
• Auditing and tracking

FAQ

1. Certificate Not Found

LastError: Certificate file does not exist or format error

Troubleshooting Steps:

1. Open certlm.msc to check if certificate is in "Personal" store
2. Confirm certificate contains private key (icon has small key)
3. Confirm Subject CN value spelling is correct
4. Check if certificate has expired

2. Private Key Access Denied

No error at application startup, but TLS handshake fails

Solution: Grant read permission on private key to the user running the application (see "Grant Private Key Access Permissions" above).

3. Multiple Certificates Match Same Subject

Underlying layer returns the first matching certificate, which may not be the expected one.

Solution: Use more precise Subject, or switch to TlsCertFile to directly specify the file.

4. Certificate Not in "Personal" Store

Only certificates in MY store contain private keys, other stores (e.g., "Trusted Root") only contain public keys.

Solution: Ensure certificate is imported to "Personal" store and contains private key.

Underlying Implementation

' cTlsSocket.InitServerTls internal
If LenB(CertSubject) <> 0 Then
    If pvPkiSystemStoreImportCertificate(CertSubject, 0, cCerts, cPrivKey) Then
        GoTo StartTls
    End If
    pvSetLastError vbObjectError, MODULE_NAME & "." & FUNC_NAME, ERR_NO_CERTIFICATE
    GoTo QH
End If

pvPkiSystemStoreImportCertificate uses Windows CryptoAPI:

1. CertOpenStore / CertOpenSystemStore opens "MY" store
2. CertFindCertificateInStore lookup by Subject
3. CertGetCertificateContextProperty gets private key handle
4. Converts certificate and private key to OpenSSL compatible format

Comparison with Other Modes

Feature	TlsCertFile	TlsCertSubject	TlsCertMemory
Certificate Source	Disk files	Windows Certificate Store	Memory Collection
Private Key Security	File system	OS protection	Process memory
Certificate Update	Replace file	Renew to store	Reload
Multi-app Sharing	File sharing	Native sharing	Independent
Deployment Complexity	Low	Medium	High
Enterprise Suitability	General	Excellent	General

Related Documentation

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

---

Last Updated: 2026-06-09