TsgcWebSocketHTTPServer › Właściwości › SSLOptions
Przechowuje ścieżki certyfikatów, wybór wersji TLS oraz ustawienia OpenSSL dla nasłuchiwacza TLS.
property SSLOptions: TsgcWSSSL_Options read FSSLOptions write SetSSLOptions;Version=tlsUndefined, VerifyCertificate=False
Przed aktywacją serwera, gdy właściwość SSL ma wartość True, należy dostarczyć materiał certyfikatu: RootCertFile, CertFile i KeyFile wskazują pliki PEM (można użyć tej samej ścieżki dla wszystkich trzech, gdy plik zawiera pełny łańcuch), a Password jest wymagane wyłącznie, gdy klucz prywatny jest zaszyfrowany. Password jest odczytywane również przez nasłuch HTTP/3 włączany przez HTTP3Options, więc ten sam plik zaszyfrowanego klucza obsługuje oba nasłuchy. Należy ustawić VerifyCertificate na True, aby żądać i weryfikować certyfikaty klienta (opcje podrzędne FailIfNoCertificate i VerifyClientOnce precyzują weryfikację), a VerifyDepth steruje długością łańcucha. Version wybiera konkretną wersję TLS (tls1_0, tls1_1, tls1_2, tls1_3) lub pozostawia negocjację otwartą (tlsUndefined). Z iohNativeTLS jest to natomiast najniższa dozwolona wersja, zobacz poniżej. OpenSSL_Options udostępnia niskopoziomowe parametry: APIVersion (oslAPI_1_0/oslAPI_1_1/oslAPI_3_0), LibPath/LibPathCustom do lokalizowania plików binarnych OpenSSL, UnixSymLinks, ECDHE, CipherList, CurveList, VersionMin oraz X509Checks do weryfikacji nazwy hosta/adresu IP.
IOHandler wybiera silnik TLS. iohOpenSSL jest wartością domyślną, a iohSChannel korzysta z dostawcy systemu Windows. iohNativeTLS wybiera silnik TLS napisany w całości w Object Pascal, wchodzący w skład pakietu sgcCrypto, obsługujący TLS 1.3 i TLS 1.2: nie jest ładowana żadna biblioteka OpenSSL, a w TLS 1.3 hybrydowe postkwantowe grupy wymiany kluczy z RFC 10024 są oferowane z X25519MLKEM768 na pierwszym miejscu. Jego dwie listy preferencji to NativeTLS_Options.Groups i NativeTLS_Options.CipherSuites, rozdzielane dwukropkami w stylu OpenSSL, a pusta lista pozostawia domyślne ustawienia silnika. Silnik działa zarówno w klasycznym modelu jeden wątek na połączenie, jak i na silnikach IOCP oraz EPOLL. iohAppleTLS i iohAndroidTLS to handlery wyłącznie klienckie: serwer z jednym z nich zgłasza wyjątek, gdy Active zostanie ustawione na True, chyba że OnSSLGetHandler dostarczy własny handler. Zamiast nich użyj iohNativeTLS, iohOpenSSL albo, w systemie Windows, iohSChannel.
Dla silnika natywnego Version to najniższa dozwolona wersja, a nie dokładna wersja, jak w przypadku iohOpenSSL. tlsUndefined (wartość domyślna) i tls1_2 akceptują TLS 1.3 i TLS 1.2, tls1_3 akceptuje wyłącznie TLS 1.3, a tls1_0 lub tls1_1 zgłaszają błąd konfiguracji przy uruchamianiu serwera, ponieważ silnik obsługuje wyłącznie TLS 1.2 i TLS 1.3. Aby akceptować wyłącznie TLS 1.2, należy podać w NativeTLS_Options.CipherSuites tylko zestawy szyfrów TLS 1.2, na przykład TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. Silnik weryfikuje certyfikaty klienta względem certyfikatów głównych z RootCertFile oraz, gdy NativeTLS_Options.UseSystemRoots ma wartość True (domyślnie False), także względem certyfikatów, którym ufa system operacyjny. Z iohNativeTLS, CertFile może być też plikiem .pfx lub .p12 zawierającym certyfikat, łańcuch i klucz, otwieranym za pomocą Password. Silnik wznawia sesje za pomocą biletów sesji TLS 1.3 i TLS 1.2: NativeTLS_Options.SessionTickets (domyślnie True) je włącza, a NativeTLS_Options.TicketLifetime (domyślnie 7200 sekund) ustala, jak długo można używać biletu do wznowienia. Wznowienie w TLS 1.2 wymaga, aby klient obsługiwał rozszerzony sekret główny. Nie przyjmuje danych 0-RTT i nie zgłasza zdarzenia OnSSLVerifyPeer, które należy do handlera OpenSSL. VerifyCertificate żąda od klienta certyfikatu i go weryfikuje, VerifyCertificate_Options.FailIfNoCertificate odrzuca klienta, który żadnego nie przesyła, a VerifyClientOnce nie ma tu znaczenia, ponieważ silnik nigdy nie renegocjuje. Zobacz Natywny TLS.
AllowPlainText (domyślnie False) sprawia, że nasłuch TLS przyjmuje także zwykłe połączenia HTTP i WebSocket na tym samym porcie. Serwer podgląda pierwszy bajt każdego nowego połączenia: $16 (rekord uzgadniania TLS) oznacza TLS, każdy inny bajt jest obsługiwany jako zwykły tekst, a gdy w czasie PlainTextTimeout (w milisekundach, domyślnie 5000) nie nadejdzie żaden bajt, połączenie jest traktowane jako TLS. PlainTextPolicy decyduje, co dzieje się ze zwykłym połączeniem: ptpServe (domyślnie) obsługuje żądanie normalnie, ptpRedirect odpowiada 308 Permanent Redirect na adres https://<Host><path>, zachowując metodę i treść żądania (400 Bad Request, gdy żądanie nie zawiera nagłówka Host), a ptpReject odpowiada 400 Bad Request i zamyka połączenie. Właściwość połączenia TLS klasy TsgcWSConnectionServer informuje, czy połączenie używa TLS. Te opcje działają z domyślnym IOHandlerem Indy oraz z IOHandlerami IOCP i EPOLL. W zdarzeniu OnCommandGet metoda serwera IsTLS(AContext) informuje, czy żądanie używa TLS. Zobacz TLS i zwykły HTTP na tym samym porcie.
oServer := TsgcWebSocketHTTPServer.Create(nil);
oServer.SSL := true;
oServer.SSLOptions.CertFile := 'c:\certificates\mycert.pem';
oServer.SSLOptions.KeyFile := 'c:\certificates\mycert.pem';
oServer.SSLOptions.RootCertFile := 'c:\certificates\mycert.pem';
oServer.SSLOptions.Version := tls1_3;
oServer.SSLOptions.OpenSSL_Options.VersionMin := tls1_2;
oServer.SSLOptions.Port := 443;
oServer.Active := true;