TsgcQUICClient › Eigenschaften › SSLQUICOptions

SSLQUICOptions Eigenschaft

TLS 1.3-Einstellungen für die QUIC-Verbindung: Zertifikate, Peer-Überprüfung, Handshake-Timeout und das OpenSSL-Backend.

Typ

TsgcSSLQUICClient_Options, das TsgcSSLQUIC_Options um ConnectTimeout erweitert.

Syntax

property SSLQUICOptions: TsgcSSLQUICClient_Options read FSSLQUICOptions write SetSSLQUICOptions;

Hinweise

Wird automatisch vom Konstruktor der Komponente erstellt. Siehe die Standardwerte der einzelnen Felder unten.

Untereigenschaften

Name	Typ	Hinweise	Beschreibung
`ConnectTimeout`	`Cardinal`	`10000`	Millisekunden, die dem TLS-1.3-Handshake bis zum Abschluss zugestanden werden. Dies ist ein anderes Timeout als der Parameter `aTimeout` von Connect, der die gesamte Verbindungsoperation begrenzt. Der Wert wird jetzt vom Transport durchgesetzt: Der Handshake wird gegen diese Frist vorangetrieben und bricht ab, sobald sie abgelaufen ist, sodass ein nicht erreichbarer Server mit dem Standardwert in etwa zehn Sekunden fehlschlägt statt in den rund dreißig Sekunden, die der frühere blockierende Handshake benötigte.
`VerifyCertificate`	`Boolean`	`False`	Ob das Serverzertifikat validiert wird. Standardmäßig deaktiviert, das heißt, der Client akzeptiert jedes vom Server präsentierte Zertifikat, wodurch die Verbindung für einen Man-in-the-Middle offen bleibt. Setzen Sie sie in der Produktion auf True und geben Sie über `RootCertFile` einen Vertrauensanker an. Ist sie True, wird das Zertifikat außerdem an den Host gebunden, mit dem verbunden wird: Ein DNS-Name in Host wird mit den Hostnamen im Zertifikat abgeglichen, ein IP-Literal mit den IP-Einträgen. Ein Zertifikat mit gültiger Kette, das aber für einen anderen Namen ausgestellt wurde, wird abgelehnt.
`RootCertFile`	`String`	empty	PEM-Datei mit dem CA-Zertifikat, das zur Validierung des Serverzertifikats verwendet wird, wenn `VerifyCertificate` True ist.
`CertFile`	`String`	empty	PEM-Datei mit dem Client-Zertifikat, für Server, die mutual TLS verlangen.
`KeyFile`	`String`	empty	PEM-Datei mit dem privaten Schlüssel, der zu `CertFile` passt.
`Password`	`String`	empty	Passphrase, die `KeyFile` schützt. Public, nicht published, daher wird sie im Code statt im Objektinspektor gesetzt.
`Mode`	`TsgcQUICSSLMode`	`qcsslmUndefined`	Client- oder Serverrolle. Public, nicht published. Der Client überschreibt beim Aufbau des TLS-Handlers alles, was Sie hier setzen, mit `qcsslmClient`, sodass dieses Feld für TsgcQUICClient effektiv schreibgeschützt ist.
`Version`	`TwsTLSVersions`	`tls1_3`	TLS-Version. QUIC schreibt TLS 1.3 vor (RFC 9001), daher ist sie im Konstruktor fest auf `tls1_3` gesetzt und es gibt keinen Grund, sie zu ändern.
`VerifyDepth`	`Integer`	`0`	Maximale Tiefe der Zertifikatskette, die bei der Validierung durchlaufen wird. Der Standardwert `0` bedeutet nicht gesetzt und nicht „alles ablehnen“: Wenn `VerifyCertificate` True ist, wird eine `0` auf eine effektive Tiefe von `9` angehoben, dieselbe Konvention, der auch die Indy-basierten Komponenten folgen. Setzen Sie sie nur, wenn Sie die Kette kürzer begrenzen möchten.
`VerifyCertificate_Options`	`TsgcSSL_Verify_Certificate_Options`	siehe unten	Feingranularere Schalter für die Überprüfung.
`OpenSSL_Options`	`TsgcOpenSSLClient_Options`	siehe unten	Wie die OpenSSL-Bibliothek selbst gefunden und geladen wird.
`IOHandler`	`TwsTLSIOHandler`	`iohOpenSSL`	TLS-Engine des QUIC-Handshakes. `iohOpenSSL` behält den OpenSSL-Pfad und die automatische Engine-Auswahl bei. `iohNativeTLS` führt den TLS-1.3-Handshake auf der nativen TLS-Engine des sgcCrypto-Packs aus und verwendet immer die sgc-QUIC-Engine (`qmCustom`). Session-Tickets, Wiederaufnahme und 0-RTT funktionieren wie bei OpenSSL. Der QUIC-Paketschutz ist ebenfalls nativ, sodass OpenSSL überhaupt nicht geladen wird.

SSLQUICOptions.VerifyCertificate_Options

Name	Typ	Hinweise	Beschreibung
`FailIfNoCertificate`	`Boolean`	`False`	Den Handshake fehlschlagen lassen, wenn der Peer überhaupt kein Zertifikat präsentiert.
`VerifyClientOnce`	`Boolean`	`False`	Prüft das Peer-Zertifikat nur beim ersten Handshake und nicht erneut bei einer Neuaushandlung.

SSLQUICOptions.OpenSSL_Options

Name	Typ	Hinweise	Beschreibung
`APIVersion`	`TwsOpenSSLAPI`	`oslAPI_3_0`	An welche OpenSSL-API-Generation gebunden wird. Vom Konstruktor auf `oslAPI_3_0` festgelegt, weil QUIC OpenSSL 3.x benötigt, anders als der Rest der Bibliothek, der standardmäßig `oslAPI_1_0` verwendet. Ändern Sie diesen Wert nicht.
`LibPath`	`TwsOpenSSLLibPath`	`oslpNone`	Wo nach den OpenSSL-Binärdateien gesucht wird: `oslpNone` verwendet den Systemsuchpfad, `oslpDefaultFolder` den Anwendungsordner, `oslpCustomPath` den Ordner in `LibPathCustom`.
`LibPathCustom`	`String`	empty	Ordner mit den OpenSSL-Binärdateien, wird verwendet, wenn `LibPath` gleich `oslpCustomPath` ist.
`CurveList`	`String`	empty	Durch Doppelpunkt getrennte Liste elliptischer Kurven, die angeboten werden sollen. Leer bedeutet die OpenSSL-Standardwerte.
`VersionMin`	`TwsTLSVersions`	`tlsUndefined`	Niedrigste akzeptierte TLS-Version. Für QUIC irrelevant, das ausschließlich TLS 1.3 verwendet.
`UnixSymLinks`	`TwsOpenSSLSymLinks`	`oslsSymLinksDefault`	Wie symbolische Links auf die OpenSSL-Bibliotheken auf unixartigen Systemen aufgelöst werden.
`LegacyProvider`	`TsgcSocketOpenSSL_LegacyProvider_Options`	`Enabled = False`	Lädt den Legacy-Provider von OpenSSL 3.x (Untereigenschaften `Enabled`, `LibPath`, `LibPathCustom`). Für QUIC nicht erforderlich.
`X509Checks`	`TsgcOpenSSLClient_X509Checks`	—	Integrierte X.509-Identitätsprüfungen: `HostName` und `IPAddress` zum Abgleich mit dem Zertifikat sowie `Mode` (eine Menge von `TsgcOpenSSLX509Check`-Flags), das auswählt, welche Prüfungen ausgeführt werden. Für den üblichen Fall müssen Sie diese nicht ausfüllen, denn wenn `VerifyCertificate` True ist, wird die Identitätsprüfung automatisch aus dem Verbindungsziel eingerichtet. Verwenden Sie sie, wenn Sie dieses Ziel überschreiben oder eigene ausdrückliche Prüfungen hinzufügen möchten.

Hinweise

Konfigurieren Sie diese Werte, bevor Sie die Verbindung öffnen. Sie werden gelesen, wenn der TLS-Handler erzeugt wird, Änderungen an einer laufenden Verbindung werden daher nicht übernommen. Rufen Sie ClearSSLQUIC nach dem Ändern auf, wenn Sie sicher sein wollen, dass kein zwischengespeicherter Sicherheitszustand in den nächsten Verbindungsaufbau übernommen wird.

Wie bei QUICOptions weist der Setter in das vorhandene Objekt zu, anstatt es zu ersetzen.

Der Delphi-Client leitet das gesamte Options-Objekt an den TLS-Handler weiter: CertFile, KeyFile, RootCertFile, Password, VerifyCertificate, VerifyCertificate_Options, VerifyDepth, Version, OpenSSL_Options und ConnectTimeout. Zwei Felder verhalten sich anders, als Sie sie setzen. Mode wird beim Aufbau des Handlers mit qcsslmClient überschrieben, und Version ist faktisch auf tls1_3 festgelegt, da QUIC TLS 1.3 vorschreibt (RFC 9001) und beide Engines es fixieren, sodass die Weiterleitung nichts ändert.

Die Host-Identitätsprüfung erfordert nichts von Ihnen. Wenn VerifyCertificate True ist, übergibt der Client das Verbindungsziel von sich aus an den Überprüfungsschritt, als Hostnamen, wenn Host einen DNS-Namen enthält, und als Adresse, wenn er ein IP-Literal enthält. OpenSSL_Options.X509Checks dient dazu, diese Prüfung zu überschreiben oder zu erweitern, nicht dazu, sie zu aktivieren.

Client-Zertifikate werden auf der Engine qmBuiltin geladen, also derjenigen, die ausgeliefert wird. Die Engine qmCustom ignoriert CertFile und KeyFile, clientseitiges gegenseitiges TLS funktioniert daher nur mit qmBuiltin.

ALPN ist nicht konfigurierbar. Der Client kündigt immer h3 an, fest im Transport für beide QUIC-Engines codiert. Wenn Sie einen anderen Anwendungsprotokoll-Bezeichner benötigen, kann diese Komponente ihn nicht aushandeln.

In .NET existiert dasselbe Objekt mit denselben Feldnamen und demselben Standardwert für ConnectTimeout, aber nur VerifyCertificate, CertFile, KeyFile, Password und ConnectTimeout werden ausgewertet. RootCertFile, VerifyDepth und Mode dienen dort nur der Parität, und OpenSSL_Options und VerifyCertificate_Options existieren dort überhaupt nicht, weil die verwaltete Implementierung System.Net.Quic und MsQuic statt OpenSSL verwendet.

Beispiel


oClient := TsgcQUICClient.Create(nil);
oClient.Host := 'www.example.com';
oClient.Port := 443;
oClient.SSLQUIC := True;

// validate the server against our CA
oClient.SSLQUICOptions.VerifyCertificate := True;
oClient.SSLQUICOptions.RootCertFile := 'ca.pem';
// 10000 ms is already the default, shown here for clarity
oClient.SSLQUICOptions.ConnectTimeout := 10000;

// mutual TLS, when the server asks for a client certificate
oClient.SSLQUICOptions.CertFile := 'client.pem';
oClient.SSLQUICOptions.KeyFile := 'client.key';

// point at a specific OpenSSL 3.5 build
oClient.SSLQUICOptions.OpenSSL_Options.LibPath := oslpCustomPath;
oClient.SSLQUICOptions.OpenSSL_Options.LibPathCustom := 'C:\openssl';

oClient.Connect;

Zurück zu Properties