TsgcQUICClient › Properties › SSLQUICOptions

SSLQUICOptions Property

TLS 1.3 settings for the QUIC connection: certificates, peer verification, handshake timeout and the OpenSSL backend.

Type

TsgcSSLQUICClient_Options, which extends TsgcSSLQUIC_Options with ConnectTimeout.

Syntax

property SSLQUICOptions: TsgcSSLQUICClient_Options read FSSLQUICOptions write SetSSLQUICOptions;

Default

Created automatically by the component constructor. See the per-field defaults below.

Sub-Properties

Name	Type	Default	Description
`ConnectTimeout`	`Cardinal`	`10000`	Milliseconds allowed for the TLS 1.3 handshake to complete. This is a different timeout from the `aTimeout` parameter of Connect, which bounds the whole connect operation. The value is now enforced by the transport: the handshake is pumped against this deadline and gives up as soon as it expires, so with the default an unreachable server fails in about ten seconds instead of the thirty or so the earlier blocking handshake took.
`VerifyCertificate`	`Boolean`	`False`	Whether the server certificate is validated. Off by default, meaning the client accepts any certificate the server presents, which leaves the connection open to a man-in-the-middle. Set it to True in production and supply a trust anchor through `RootCertFile`. When it is True the certificate is also bound to the host being connected to: a DNS name in Host is matched against the host names in the certificate, an IP literal against the IP entries. A certificate with a valid chain but issued for a different name is rejected.
`RootCertFile`	`String`	empty	PEM file with the CA certificate used to validate the server certificate when `VerifyCertificate` is True.
`CertFile`	`String`	empty	PEM file with the client certificate, for servers that require mutual TLS.
`KeyFile`	`String`	empty	PEM file with the private key matching `CertFile`.
`Password`	`String`	empty	Passphrase protecting `KeyFile`. Public, not published, so it is set in code rather than in the Object Inspector.
`Mode`	`TsgcQUICSSLMode`	`qcsslmUndefined`	Client or server role. Public, not published. The client overrides whatever you set here with `qcsslmClient` when it builds the TLS handler, so this field is effectively read-only for TsgcQUICClient.
`Version`	`TwsTLSVersions`	`tls1_3`	TLS version. QUIC mandates TLS 1.3 (RFC 9001), so this is fixed at `tls1_3` in the constructor and there is no reason to change it.
`VerifyDepth`	`Integer`	`0`	Maximum certificate chain depth to walk during validation. The default `0` means not set rather than "reject everything": when `VerifyCertificate` is True, a `0` is promoted to an effective depth of `9`, the same convention the Indy-based components follow. Set it only when you want to cap the chain shorter than that.
`VerifyCertificate_Options`	`TsgcSSL_Verify_Certificate_Options`	see below	Finer-grained verification switches.
`OpenSSL_Options`	`TsgcOpenSSLClient_Options`	see below	How the OpenSSL library itself is located and loaded.
`IOHandler`	`TwsTLSIOHandler`	`iohOpenSSL`	TLS engine of the QUIC handshake. `iohOpenSSL` keeps the OpenSSL path and the automatic engine selection. `iohNativeTLS` runs the TLS 1.3 handshake on the native TLS engine of the sgcCrypto pack and always uses the sgc QUIC engine (`qmCustom`). Session tickets, resumption and 0-RTT work as on OpenSSL. The QUIC packet protection is native too, so OpenSSL is not loaded at all.

SSLQUICOptions.VerifyCertificate_Options

Name	Type	Default	Description
`FailIfNoCertificate`	`Boolean`	`False`	Fail the handshake when the peer presents no certificate at all.
`VerifyClientOnce`	`Boolean`	`False`	Verify the peer certificate only on the initial handshake and not again on renegotiation.

SSLQUICOptions.OpenSSL_Options

Name	Type	Default	Description
`APIVersion`	`TwsOpenSSLAPI`	`oslAPI_3_0`	Which OpenSSL API generation to bind to. Forced to `oslAPI_3_0` by the constructor because QUIC needs OpenSSL 3.x, unlike the rest of the library which defaults to `oslAPI_1_0`. Leave it alone.
`LibPath`	`TwsOpenSSLLibPath`	`oslpNone`	Where to look for the OpenSSL binaries: `oslpNone` uses the system search path, `oslpDefaultFolder` the application folder, `oslpCustomPath` the folder in `LibPathCustom`.
`LibPathCustom`	`String`	empty	Folder holding the OpenSSL binaries, used when `LibPath` is `oslpCustomPath`.
`CurveList`	`String`	empty	Colon-separated list of elliptic curves to offer. Empty means the OpenSSL defaults.
`VersionMin`	`TwsTLSVersions`	`tlsUndefined`	Lowest TLS version accepted. Irrelevant for QUIC, which is TLS 1.3 only.
`UnixSymLinks`	`TwsOpenSSLSymLinks`	`oslsSymLinksDefault`	How symbolic links to the OpenSSL libraries are resolved on unix-like systems.
`LegacyProvider`	`TsgcSocketOpenSSL_LegacyProvider_Options`	`Enabled = False`	Loads the OpenSSL 3.x legacy provider (sub-properties `Enabled`, `LibPath`, `LibPathCustom`). Not needed for QUIC.
`X509Checks`	`TsgcOpenSSLClient_X509Checks`	—	Built-in X.509 identity checks: `HostName` and `IPAddress` to match against the certificate, and `Mode` (a set of `TsgcOpenSSLX509Check` flags) selecting which checks run. You do not have to fill these in for the usual case, because when `VerifyCertificate` is True the identity check is set up automatically from the connection target. Use them when you want to override that target or add explicit checks of your own.

Remarks

Configure these values before opening the connection. They are read when the TLS handler is created, so changes made on a live connection are not picked up. Call ClearSSLQUIC after changing them if you want to be certain no cached secure state survives into the next connect.

Like QUICOptions, the setter assigns into the existing object rather than replacing it.

The Delphi client forwards the whole options object to the TLS handler: CertFile, KeyFile, RootCertFile, Password, VerifyCertificate, VerifyCertificate_Options, VerifyDepth, Version, OpenSSL_Options and ConnectTimeout. Two fields behave differently from what you set. Mode is overridden with qcsslmClient when the handler is built, and Version is effectively fixed at tls1_3 because QUIC mandates TLS 1.3 (RFC 9001) and both engines pin it, so forwarding it changes nothing.

The host identity check needs nothing from you. When VerifyCertificate is True the client passes the connection target to the verification step by itself, as a host name when Host holds a DNS name and as an address when it holds an IP literal. OpenSSL_Options.X509Checks is there to override or extend that check, not to enable it.

Client certificates load on the qmBuiltin engine, which is the one that ships. The qmCustom engine ignores CertFile and KeyFile, so client-side mutual TLS works on qmBuiltin only.

ALPN is not configurable. The client always advertises h3, hard-coded in the transport for both QUIC engines. If you need a different application protocol identifier, this component cannot negotiate it.

In .NET the same object exists with the same field names and the same ConnectTimeout default, but only VerifyCertificate, CertFile, KeyFile, Password and ConnectTimeout are consumed. RootCertFile, VerifyDepth and Mode are parity-only there, and OpenSSL_Options and VerifyCertificate_Options do not exist at all because the managed implementation uses System.Net.Quic and MsQuic instead of OpenSSL.

Example


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;

Back to Properties