Server SSL | SChannel for Indy Servers

Indy-based server components (TsgcWebSocketServer, TsgcWebSocketHTTPServer) can use Windows SChannel (Secure Channel) as the TLS provider instead of OpenSSL. SChannel is the native Windows TLS implementation, so it does not require any external DLLs.

How it works

When a server component has SSL enabled and the IOHandler is set to iohSChannel, the server creates a TsgcIdServerIOHandlerSSLSChannel instance that handles all TLS operations using the Windows SChannel API. For every incoming client connection the server performs the TLS handshake through the SChannel provider, negotiating the protocol version, cipher suite, and binding the configured certificate.

SChannel reads certificates from the Windows Certificate Store or from a PFX file (.pfx / .p12). No PEM files are needed and no OpenSSL libraries need to be deployed.

Configuration

To enable SChannel on an Indy server, configure the following properties:

1. Set the SSL property to True.

2. Set SSLOptions.IOHandler to iohSChannel.

3. Set SSLOptions.Version to the desired TLS version (tls1_2, tls1_3, ...).

4. Set SSLOptions.Port to the port used for secure connections.

5. Configure the certificate using one of the two methods described below.

SChannel_Options properties

The SSLOptions.SChannel_Options sub-property exposes the SChannel-specific settings:

Property	Description
CertHash	The thumbprint (hexadecimal hash) of a certificate installed in the Windows Certificate Store.
CertStoreName	Which certificate store to search: scsnMY (Personal), scsnRoot, scsnTrust, scsnCA.
CertStorePath	Store location: scspStoreLocalMachine or scspStoreCurrentUser.
CipherList	Optional colon-separated list of cipher algorithms (e.g. CALG_AES_256:CALG_AES_128). Empty means use system defaults.
UseLegacyCredentials	When True, uses the legacy SCHANNEL_CRED structure instead of SCH_CREDENTIALS. Enable this for older Windows versions that do not support the newer API.

Additionally, the general SSLOptions properties CertFile and Password are used when loading a certificate from a PFX file.

Certificate from Windows Store

If the certificate is already installed in the Windows Certificate Store, provide the certificate thumbprint and indicate where it is located.

To find the thumbprint, open PowerShell and run:

dir cert:\localmachine\my

The Thumbprint column shows the hexadecimal hash you need.

Directory: Microsoft.PowerShell.Security\Certificate::localmachine\my
Thumbprint                                Subject
----------                                -------
C12A8FC8AE668F866B48F23E753C93D357E9BE10  CN=*.mydomain.com

oServer := TsgcWebSocketHTTPServer.Create(nil);
oServer.SSL := True;
oServer.SSLOptions.IOHandler := iohSChannel;
oServer.SSLOptions.Version := tls1_2;
oServer.SSLOptions.Port := 443;
oServer.Port := 443;
oServer.SSLOptions.SChannel_Options.CertHash := 'C12A8FC8AE668F866B48F23E753C93D357E9BE10';
oServer.SSLOptions.SChannel_Options.CertStoreName := scsnMY;
oServer.SSLOptions.SChannel_Options.CertStorePath := scspStoreLocalMachine;
oServer.Active := True;

Certificate from PFX file

If you have a PFX (.pfx or .p12) certificate file, set the CertFile and Password properties on SSLOptions. SChannel will import the certificate at startup.

oServer := TsgcWebSocketHTTPServer.Create(nil);
oServer.SSL := True;
oServer.SSLOptions.IOHandler := iohSChannel;
oServer.SSLOptions.Version := tls1_2;
oServer.SSLOptions.Port := 443;
oServer.Port := 443;
oServer.SSLOptions.CertFile := 'c:\certificates\server.pfx';
oServer.SSLOptions.Password := 'mypassword';
oServer.Active := True;

If you have a PEM certificate and private key, convert them to PFX format first using OpenSSL:

openssl pkcs12 -inkey server.key -in server.crt -export -out server.pfx

TLS Version

Use the SSLOptions.Version property to control which TLS version the server accepts:

Value	Description
tls1_0	TLS 1.0 (not recommended)
tls1_1	TLS 1.1
tls1_2	TLS 1.2 (recommended)
tls1_3	TLS 1.3
tlsUndefined	Accept TLS 1.0, 1.1 and 1.2

Cipher List

By default SChannel uses the system cipher configuration. You can restrict the allowed ciphers by setting SChannel_Options.CipherList to a colon-separated list of algorithm names, for example:

CALG_AES_256:CALG_AES_128

Leave this property empty to use the Windows defaults.

Legacy Credentials

Windows Server 2019 and earlier may not support the newer SCH_CREDENTIALS API. If the server fails to start on an older Windows version, set SChannel_Options.UseLegacyCredentials to True to use the legacy SCHANNEL_CRED structure instead.

The component detects the Windows version automatically in most cases, but you can force legacy mode if needed.

Advantages over OpenSSL

• No external DLLs: SChannel is built into Windows, so you do not need to deploy libeay32.dll / ssleay32.dll or libcrypto / libssl.
• Windows Certificate Store integration: use certificates already installed and managed by the operating system.
• Automatic updates: TLS improvements and security patches are applied through Windows Update.

Notes

• SChannel is available on Windows only. For cross-platform servers, use OpenSSL (iohOpenSSL).
• The server must have the private key associated with the certificate. When using the Windows Store method, the certificate must have been imported with its private key.
• For production servers using the Certificate Store method, the Local Machine store (scspStoreLocalMachine) is recommended so the certificate is available regardless of which user account runs the service.
• Only PFX (.pfx / .p12) certificate files are supported. If you have PEM files, convert them to PFX format first.