SSL / TLS Backends

Overview

Four TLS Transports, One Property

Every backend plugs into the same TLSOptions API. Pick the one that fits your platform and deployment, then set TLSOptions.IOHandler.

OpenSSL

Cross-platform TLS via the OpenSSL libraries. The default, most portable backend, with the widest protocol and cipher coverage. Ships in every edition.

SChannel

Windows-native TLS (Microsoft Secure Channel). No libraries to deploy, uses the Windows certificate store. Windows only. Professional and Enterprise.

Android TLS

Android-native TLS via the platform SSLEngine. No OpenSSL .so to bundle. Android only. Enterprise edition.

Apple TLS

iOS/macOS-native TLS. No OpenSSL .dylib. Auto-selects Network.framework (TLS 1.3) on modern systems. Enterprise edition.

At a glance

Backend Comparison

Platforms, deployment footprint, TLS 1.3 support and edition for each transport.

Backend	Platforms	Library to deploy	TLS 1.3	Edition
OpenSSL	Windows, Linux, macOS, iOS, Android	OpenSSL (libssl/libcrypto)	Yes	All editions
SChannel	Windows	None (built into Windows)	Yes (Windows 11/Server 2022+)	Professional, Enterprise
Android TLS	Android	None (uses the OS)	Yes	Enterprise
Apple TLS	iOS, macOS	None (uses the OS)	Yes (10.14+/iOS 12+)	Enterprise

Cross-platform

OpenSSL (iohOpenSSL)

Cross-platform TLS implemented over Indy's socket, available on every platform sgcWebSockets targets.

Cross-platform TLS implemented over Indy's socket. Available on every platform sgcWebSockets targets and the default on most. Full TLS 1.0 to 1.3, the broadest cipher suite coverage, custom CA, client certificates and ALPN. The trade-off is that you must deploy the OpenSSL runtime libraries with your application (libssl-3.dll / libcrypto-3.dll on Windows, .so on Linux/Android, .dylib on Apple) and keep them patched. Use it when you need identical TLS behavior across all platforms, or a capability only OpenSSL exposes.

uses
  sgcWebSocket, sgcWebSocket_Types;
// ...
WSClient.TLS := True;
WSClient.TLSOptions.IOHandler := iohOpenSSL;
WSClient.Host := 'your.server.com';
WSClient.Port := 443;
WSClient.Active := True;

WSClient->TLS = true;
WSClient->TLSOptions->IOHandler = iohOpenSSL;
WSClient->Host = "your.server.com";
WSClient->Port = 443;
WSClient->Active = true;

Windows native

SChannel (iohSChannel)

Microsoft's native TLS stack, built into Windows. Zero library deployment.

Microsoft's native TLS stack (Secure Channel / SSPI), built into Windows. Zero library deployment, no OpenSSL DLLs to ship or patch, and it uses the Windows certificate store with OS-managed trust and updates. Windows-only. Use it for Windows desktop or server apps that want native TLS and a smaller, dependency-free deployment.

uses
  sgcWebSocket, sgcWebSocket_Types;
// ...
WSClient.TLS := True;
WSClient.TLSOptions.IOHandler := iohSChannel;
WSClient.Host := 'your.server.com';
WSClient.Port := 443;
WSClient.Active := True;

WSClient->TLS = true;
WSClient->TLSOptions->IOHandler = iohSChannel;
WSClient->Host = "your.server.com";
WSClient->Port = 443;
WSClient->Active = true;

Android native · Enterprise

Native Android TLS (iohAndroidTLS)

Android-native TLS using the platform's SSLEngine through JNI. No OpenSSL .so in your APK.

Android-native TLS using the platform's javax.net.ssl.SSLEngine through JNI. No OpenSSL .so files in your APK, a smaller package, and TLS maintained and updated by the OS. It validates against the Android system trust store with hostname verification, negotiates TLS 1.3, and supports ALPN on Android 10 (API 29) and later. Use it for Android apps that must avoid shipping or patching OpenSSL.

uses
  sgcWebSocket, sgcWebSocket_Types;
// ...
WSClient.TLS := True;
WSClient.TLSOptions.IOHandler := iohAndroidTLS;
WSClient.Host := 'your.server.com';
WSClient.Port := 443;
WSClient.Active := True;

WSClient->TLS = true;
WSClient->TLSOptions->IOHandler = iohAndroidTLS;
WSClient->Host = "your.server.com";
WSClient->Port = 443;
WSClient->Active = true;

iOS & macOS native · Enterprise

Native Apple TLS (iohAppleTLS)

Apple-native TLS for iOS and macOS, with no OpenSSL .dylib to deploy.

Apple-native TLS for iOS and macOS, with no OpenSSL .dylib to deploy. It auto-selects the best system API: Network.framework (TLS 1.3) on macOS 10.14+ / iOS 12+, falling back to Secure Transport (TLS 1.2) on older systems, all behind the same iohAppleTLS setting. It supports the system trust store, SNI/hostname verification, an OnVerifyPeer callback for custom validation, a custom CA root (RootCertFile), client certificate / mutual TLS (CertFile + Password), and ALPN. Use it for App Store apps that want OS-maintained TLS 1.3 and no third-party crypto to manage.

WSClient.TLS := True;
WSClient.TLSOptions.IOHandler := iohAppleTLS;
WSClient.TLSOptions.ALPNProtocols.Add('http/1.1');
WSClient.TLSOptions.RootCertFile := '';   // optional custom CA (PEM/DER)
WSClient.TLSOptions.CertFile := '';       // optional client cert (PKCS#12) for mTLS
WSClient.TLSOptions.VerifyCertificate := True;
WSClient.OnAppleTLSVerifyPeer := DoVerifyPeer;  // optional
WSClient.Active := True;

WSClient->TLS = true;
WSClient->TLSOptions->IOHandler = iohAppleTLS;
WSClient->TLSOptions->ALPNProtocols->Add("http/1.1");
WSClient->TLSOptions->RootCertFile = "";   // optional custom CA (PEM/DER)
WSClient->TLSOptions->CertFile = "";       // optional client cert (PKCS#12) for mTLS
WSClient->TLSOptions->VerifyCertificate = true;
WSClient->OnAppleTLSVerifyPeer = DoVerifyPeer;  // optional
WSClient->Active = true;

Edition note

Native platform TLS, Android (iohAndroidTLS) and Apple (iohAppleTLS), requires the Enterprise edition. OpenSSL (iohOpenSSL) is included in every edition; SChannel (iohSChannel) is included in the Professional and Enterprise editions.

Same API

Switch With One Line

All four backends share the same TLSOptions API, so moving between them is a single property change. Nothing else in your code has to change.

TLS & VerifyCertificate

Enable TLS and toggle peer certificate verification the same way on every backend.

RootCertFile

Point at a custom CA root to trust a private or self-signed certificate authority.

CertFile & Password

Supply a client certificate and its password for mutual TLS (mTLS) authentication.

ALPNProtocols

Advertise application protocols (for example http/1.1) during the TLS handshake.

// Same TLSOptions, only the IOHandler line changes per platform.
WSClient.TLS := True;
WSClient.TLSOptions.IOHandler := iohOpenSSL;   // or iohSChannel / iohAndroidTLS / iohAppleTLS
WSClient.TLSOptions.VerifyCertificate := True;
WSClient.TLSOptions.RootCertFile := '';
WSClient.TLSOptions.CertFile := '';
WSClient.TLSOptions.Password := '';
WSClient.TLSOptions.ALPNProtocols.Add('http/1.1');
WSClient.Active := True;

// Same TLSOptions, only the IOHandler line changes per platform.
WSClient->TLS = true;
WSClient->TLSOptions->IOHandler = iohOpenSSL;   // or iohSChannel / iohAndroidTLS / iohAppleTLS
WSClient->TLSOptions->VerifyCertificate = true;
WSClient->TLSOptions->RootCertFile = "";
WSClient->TLSOptions->CertFile = "";
WSClient->TLSOptions->Password = "";
WSClient->TLSOptions->ALPNProtocols->Add("http/1.1");
WSClient->Active = true;