SChannel server Indy per Delphi

· Funzionalità

Per anni, gli sviluppatori Delphi che distribuiscono server TLS su Windows hanno affrontato la stessa sfida: includere le librerie OpenSSL corrette con la loro applicazione. Mancate corrispondenze di versione, DLL mancanti a runtime e aggiornamenti manuali dopo gli advisory di sicurezza sono stati una costante fonte di attrito negli ambienti di produzione.

A partire da sgcWebSockets 2026.3.0, i componenti server basati su Indy — TsgcWebSocketServer e TsgcWebSocketHTTPServer — possono usare Windows SChannel (Secure Channel) come provider TLS. SChannel è l'implementazione TLS nativa di Windows, integrata in ogni versione di Windows. Non richiede DLL esterne, si integra direttamente con il Windows Certificate Store e riceve patch di sicurezza automaticamente tramite Windows Update.

Questo articolo ti guida nella configurazione e nel deploy di server basati su SChannel nelle tue applicazioni Delphi.

Perché SChannel lato server?

SChannel elimina i grattacapi di deploy più comuni associati a TLS su server Windows.

Zero dipendenze esterne
SChannel è integrato in Windows. Niente libeay32.dll, niente ssleay32.dll, niente libcrypto, niente libssl. Il tuo installer diventa più piccolo e il tuo deploy più semplice. 		Windows Certificate Store
Usa certificati già installati e gestiti dal sistema operativo. Niente più file PEM da copiare in giro, basta fare riferimento al certificato tramite il suo thumbprint. 		Aggiornamenti di sicurezza automatici
I miglioramenti TLS e le patch di sicurezza vengono applicati tramite Windows Update. Niente aggiornamenti manuali delle librerie, niente re-deploy per le CVE di OpenSSL.

Guida rapida — 5 passi

Abilitare SChannel sul tuo server richiede solo poche modifiche di proprietà:

  1. Abilita SSL — imposta la proprietà SSL a True.
  2. Seleziona SChannel come IOHandler — imposta SSLOptions.IOHandler a iohSChannel.
  3. Scegli una versione TLS — imposta SSLOptions.Version alla versione desiderata. tls1_2 è consigliato per la maggior parte dei deploy.
  4. Imposta la porta — imposta SSLOptions.Port e Port alla porta di ascolto (tipicamente 443).
  5. Configura il certificato — fornisci un certificato tramite il Windows Certificate Store (thumbprint) o un file PFX.

Metodo 1: certificato dal Windows Store

Se il tuo certificato è già installato nel Windows Certificate Store, devi solo fornire il suo thumbprint. È l'approccio consigliato per server di produzione e servizi Windows.

Trovare il thumbprint del certificato

Apri PowerShell ed elenca i certificati nello store personale Local Machine:

PS C:\> dir cert:\localmachine\my
Directory: Microsoft.PowerShell.Security\Certificate::localmachine\my
Thumbprint                                Subject
----------                                -------
C12A8FC8AE668F866B48F23E753C93D357E9BE10  CN=*.mydomain.com
A7F3D2E1B9C84A6D5E0F123456789ABCDEF01234  CN=api.mydomain.com

Copia il thumbprint esadecimale di 40 caratteri del certificato che vuoi usare.

Configurare il server

var
  oServer: TsgcWebSocketHTTPServer;
begin
  oServer := TsgcWebSocketHTTPServer.Create(nil);
  // Abilita TLS con SChannel
  oServer.SSL := True;
  oServer.SSLOptions.IOHandler := iohSChannel;
  oServer.SSLOptions.Version := tls1_2;
  oServer.SSLOptions.Port := 443;
  oServer.Port := 443;
  // Punta al certificato nel Windows Store
  oServer.SSLOptions.SChannel_Options.CertHash :=
    'C12A8FC8AE668F866B48F23E753C93D357E9BE10';
  oServer.SSLOptions.SChannel_Options.CertStoreName := scsnMY;
  oServer.SSLOptions.SChannel_Options.CertStorePath := scspStoreLocalMachine;
  // Inizia l'ascolto
  oServer.Active := True;
end;

Suggerimento per la produzione. Usa sempre scspStoreLocalMachine per server deployati come servizi Windows. Lo store Local Machine è accessibile indipendentemente dall'account utente che esegue il servizio, mentre scspStoreCurrentUser è legato al profilo dell'utente loggato.

Opzioni del certificate store

Nome dello store Costante Contiene
Personal (MY) scsnMY Certificati server con chiavi private
Root scsnRoot Autorità di certificazione root fidate
Trust scsnTrust Certificati fidati
CA scsnCA Autorità di certificazione intermedie

Metodo 2: certificato da un file PFX

Se hai un file di certificato PFX (.pfx o .p12), puoi caricarlo direttamente senza installarlo nel Windows Certificate Store. SChannel importerà il certificato all'avvio del server.

var
  oServer: TsgcWebSocketHTTPServer;
begin
  oServer := TsgcWebSocketHTTPServer.Create(nil);
  // Abilita TLS con SChannel
  oServer.SSL := True;
  oServer.SSLOptions.IOHandler := iohSChannel;
  oServer.SSLOptions.Version := tls1_2;
  oServer.SSLOptions.Port := 443;
  oServer.Port := 443;
  // Carica il certificato da un file PFX
  oServer.SSLOptions.CertFile := 'c:\certificates\server.pfx';
  oServer.SSLOptions.Password := 'mypassword';
  // Inizia l'ascolto
  oServer.Active := True;
end;

Hai file PEM? SChannel accetta solo il formato PFX. Converti il tuo certificato PEM e la chiave privata con un singolo comando:

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

Riferimento di SChannel_Options

La sotto-proprietà SSLOptions.SChannel_Options espone tutte le impostazioni del server specifiche per SChannel.

Proprietà Tipo Descrizione
CertHash Stringa Il thumbprint esadecimale di 40 caratteri di un certificato installato nel Windows Certificate Store.
CertStoreName Enum Quale store cercare: scsnMY (Personal), scsnRoot, scsnTrust, scsnCA.
CertStorePath Enum Posizione dello store: scspStoreLocalMachine (consigliato) o scspStoreCurrentUser.
CipherList Stringa Elenco separato da due punti degli algoritmi di cifratura consentiti (es. CALG_AES_256:CALG_AES_128). Lascialo vuoto per i default di Windows.
UseLegacyCredentials Booleano Quando True, usa la struttura legacy SCHANNEL_CRED. Abilitala per Windows Server 2019 e versioni precedenti.

Configurazione della versione TLS

Controlla quale versione del protocollo TLS il server accetta tramite la proprietà SSLOptions.Version.

Valore Protocollo Consiglio
tls1_3 TLS 1.3 Massima sicurezza. Usalo quando tutti i client lo supportano.
tls1_2 TLS 1.2 Consigliato per la maggior parte dei deploy di produzione.
tls1_1 TLS 1.1 Legacy. Evitalo a meno che non sia richiesto da client vecchi.
tls1_0 TLS 1.0 Deprecato. Non consigliato.
tlsUndefined TLS 1.0 – 1.2 Accetta TLS 1.0, 1.1 o 1.2. 
// Imponi TLS 1.2 come minimo per una sicurezza moderna
oServer.SSLOptions.Version := tls1_2;
// Oppure usa TLS 1.3 per la cifratura più forte
oServer.SSLOptions.Version := tls1_3;

Configurazione della cipher suite

Di default, SChannel usa la configurazione di cifrature a livello di sistema gestita da Windows. Per ambienti che richiedono un controllo più stretto, puoi restringere gli algoritmi consentiti.

// Restringi solo a AES-256 e AES-128
oServer.SSLOptions.SChannel_Options.CipherList :=
  'CALG_AES_256:CALG_AES_128';

Lascia vuota la proprietà CipherList per accettare la configurazione di cifrature di default di Windows. È adatta alla maggior parte dei deploy, dato che Windows mantiene un insieme di default sicuro aggiornato tramite Windows Update.

Attenzione. Restringere le cifrature in modo troppo aggressivo può impedire ad alcuni client di connettersi. Testa a fondo contro la base di client prevista prima di deployare cipher list personalizzate in produzione.

Compatibilità con Windows legacy

Il componente usa di default l'API moderna SCH_CREDENTIALS. Su versioni Windows più vecchie (Server 2019 e precedenti) che non supportano questa API, puoi ricadere sulla struttura di credenziali legacy.

// Abilita la modalità legacy per Windows Server 2019 e versioni precedenti
oServer.SSLOptions.SChannel_Options.UseLegacyCredentials := True;

Nella maggior parte dei casi, il componente rileva automaticamente la versione di Windows e seleziona l'API appropriata. Usa la proprietà UseLegacyCredentials solo se il server non si avvia su una versione Windows più vecchia.

SChannel vs. OpenSSL — quando usare quale

Entrambi i provider TLS sono pienamente supportati. La scelta giusta dipende dalla tua piattaforma di deploy e dai requisiti operativi.

Funzionalità SChannel OpenSSL
DLL esterne richieste No Sì
Windows Certificate Store Nativo Non supportato
Aggiornamenti di sicurezza automatici Sì (Windows Update) Aggiornamento manuale della libreria
Multipiattaforma Solo Windows Windows, Linux, macOS
Formati di certificato PFX + Windows Store PEM, PFX
TLS 1.0 – 1.3 Sì Sì

In sintesi. Se il tuo server gira esclusivamente su Windows, SChannel è la scelta più semplice e mantenibile. Se hai bisogno di supporto multipiattaforma, usa iohOpenSSL. Passare dall'uno all'altro richiede di cambiare solo la proprietà IOHandler, non servono altre modifiche di codice.

Esempio completo: server WebSocket sicuro

Un server WebSocket completamente configurato che usa SChannel con un certificato dal Windows Certificate Store.

uses
  sgcWebSocket_Server, sgcWebSocket_Classes;
var
  oServer: TsgcWebSocketHTTPServer;
begin
  oServer := TsgcWebSocketHTTPServer.Create(nil);
  Try
    // Configurazione del server
    oServer.Port := 443;
    // Configurazione TLS con SChannel
    oServer.SSL := True;
    oServer.SSLOptions.IOHandler := iohSChannel;
    oServer.SSLOptions.Version := tls1_2;
    oServer.SSLOptions.Port := 443;
    // Certificato dal Windows Certificate Store
    oServer.SSLOptions.SChannel_Options.CertHash :=
      'C12A8FC8AE668F866B48F23E753C93D357E9BE10';
    oServer.SSLOptions.SChannel_Options.CertStoreName := scsnMY;
    oServer.SSLOptions.SChannel_Options.CertStorePath := scspStoreLocalMachine;
    // Assegna gli handler degli eventi WebSocket
    oServer.OnConnect := OnClientConnect;
    oServer.OnDisconnect := OnClientDisconnect;
    oServer.OnMessage := OnClientMessage;
    // Avvia il server
    oServer.Active := True;
    WriteLn('Secure WebSocket server listening on port 443 (SChannel TLS 1.2)');
    WriteLn('Press Enter to stop...');
    ReadLn;
  Finally
    oServer.Active := False;
    oServer.Free;
  End;
end;

Funziona con entrambi i componenti server

SChannel è disponibile su entrambi i componenti server basati su Indy. La configurazione è identica.

Componente Descrizione
TsgcWebSocketHTTPServer Server WebSocket con server HTTP integrato. Ideale per API WebSocket + REST combinate.
TsgcWebSocketServer Server WebSocket puro basato su Indy TCP. Ideale per endpoint WebSocket dedicati.

Note importanti