TsgcQUICClient

QUIC ist das in RFC 9000 standardisierte Transportprotokoll, mit seiner TLS-Integration in RFC 9001 und seiner Verlusterkennung und Überlastkontrolle in RFC 9002. Es ist der Transport, auf dem HTTP/3 läuft. Im Vergleich zu TCP plus TLS ändert es vier Dinge, die für eine Anwendung von Bedeutung sind:

• Es läuft über UDP. QUIC lebt im User Space oberhalb von UDP-Datagrammen, hängt daher nicht vom TCP-Stack des Betriebssystems ab und kann ohne Kernel-Änderungen ausgerollt werden. Der Preis dafür ist, dass ein Netzwerk, das UDP blockiert oder drosselt, auch QUIC blockiert.
• TLS 1.3 ist eingebaut, nicht aufgesetzt. Eine unverschlüsselte QUIC-Verbindung gibt es nicht: Der Handshake ist Teil des Transports, und sogar der größte Teil des Paket-Headers ist geschützt. Das reduziert auch die Roundtrips, eine neue Verbindung wird in 1-RTT aufgebaut statt über den TCP-Handshake gefolgt von einem separaten TLS-Handshake.
• Streams werden innerhalb einer Verbindung gemultiplext. Eine Verbindung trägt viele unabhängige Streams, jeder für sich geordnet und mit eigener Flusssteuerung. Ein auf einem Stream verlorenes Paket blockiert die anderen nicht, wodurch das Head-of-Line-Blocking entfällt, unter dem HTTP/2 beim Multiplexen über eine einzige TCP-Verbindung leidet. Streams können bidirektional oder unidirektional sein, und beide Seiten können sie öffnen.
• Verbindungen werden über eine Connection-ID identifiziert, nicht über das 4-Tupel. Das ist es, was QUIC im Protokolldesign einen Wechsel der IP-Adresse oder des Ports überstehen lässt.

TsgcQUICClient stellt diesen Transport direkt bereit, als rohe Bytes auf Streams. Er spricht nicht HTTP/3 oder ein anderes Anwendungsprotokoll: Verwenden Sie TsgcHTTP3Client, wenn Sie HTTP-Semantik über QUIC wünschen. Greifen Sie zu TsgcQUICClient, wenn Sie Ihr eigenes Protokoll über QUIC transportieren oder einen QUIC-Endpunkt testen.

Wissenswertes zum Umfang, bevor Sie beginnen. Die Komponente ist ein schlanker Client über dem QUIC-Transport, und zwei ihrer Einschränkungen überraschen häufig:

• Es gibt keinen Lesepfad, bis Sie EnableMultiStream aufrufen. Ein einfacher Client kann sich verbinden und senden, aber nichts von dem, was er empfängt, wird gemeldet. OnQUICStreamData ist das einzige Ereignis für empfangene Daten und bleibt untätig, bis der Multi-Stream-Modus eingeschaltet wird. Auf dem Client gibt es kein OnQUICData, anders als bei TsgcQUICServer.
• ALPN ist fest auf h3 gesetzt und kann nicht konfiguriert werden. 0-RTT-Wiederaufnahme und Verbindungsmigration sind in der zugrunde liegenden Transportklasse implementiert, werden aber nicht als Eigenschaften an dieser Komponente bereitgestellt.

Die beiden QUIC-Engines

Die Bibliothek kann QUIC über eine von zwei Engines betreiben. Die Engine folgt SSLQUICOptions.IOHandler:

1. Bei iohOpenSSL (Standard) wird, wenn der Build OSSL_QUIC_client_method exportiert, die integrierte Engine (qmBuiltin) verwendet. Hier besitzt OpenSSL 3.5 oder höher die gesamte QUIC-Verbindung und die Bibliothek steuert sie über die OpenSSL-Stream-API.
2. Andernfalls wird, wenn der Build die OpenSSL-3.5-QUIC-TLS-API exportiert (SSL_set_quic_tls_cbs), die sgc-Engine (qmCustom) als Fallback verwendet. Dies ist der reine Pascal-QUIC-Stack in den sgcQUIC_*-Units: Er erstellt und parst die Pakete selbst und verwendet OpenSSL nur, um den TLS 1.3-Handshake zu steuern. Ist keine der beiden APIs verfügbar, etwa bei einem quictls-Build, löst die Initialisierung der Verbindung eine Ausnahme aus.
3. Bei iohNativeTLS wird immer die sgc-Engine verwendet, und der TLS 1.3-Handshake läuft auf der nativen TLS-Engine, mit Session-Tickets, Wiederaufnahme und 0-RTT. Der Paketschutz ist ebenfalls nativ, sodass OpenSSL überhaupt nicht geladen wird.

Mit den mit den Demos gebündelten OpenSSL-3.5-Binärdateien wird qmBuiltin ausgewählt. IsOpenSSL_QUIC_Available und IsOpenSSL_QUIC_TLS_Available, deklariert in sgcIdSSLOpenSSLHeaders, melden, welche der beiden OpenSSL-APIs die geladene Bibliothek exportiert. Die Engines im Vergleich:

Funktion	qmBuiltin (OpenSSL 3.5+)	qmCustom (sgc-Engine)
Verbinden, trennen, auf dem Standard-Stream senden	Ja	Ja
EnableMultiStream	Ja	Ja
OpenStream / WriteStreamData	Ja	Ja
OnQUICStreamData (der Lesepfad)	Ja, nach EnableMultiStream	Ja, nach EnableMultiStream
Feinabstimmung von QUICOptions.Settings	Größtenteils von OpenSSL ausgehandelt, Werte werden nicht herangezogen	Ja, treibt den Pascal-Stack an

Siehe QUIC für den vollständigen Engine-Vergleich.

Schnellstart

1. Erstellen Sie einen TsgcQUICClient und setzen Sie Host und Port des QUIC-Servers. QUIC läuft über UDP, Port ist daher ein UDP-Port, üblicherweise 443.

2. Konfigurieren Sie TLS über SSLQUICOptions. Die Überprüfung ist standardmäßig deaktiviert, aktivieren Sie daher VerifyCertificate und lassen Sie RootCertFile auf Ihre CA zeigen, außer bei einem reinen Wegwerftest. Bei aktivierter Überprüfung muss das Zertifikat jetzt zusätzlich zum Host passen, mit dem Sie sich verbinden, sodass ein selbstsigniertes Zertifikat oder eines, das für einen anderen Namen ausgestellt wurde, abgelehnt wird, wo es früher akzeptiert wurde.

3. Behandeln Sie OnQUICConnect, OnQUICDisconnect und OnQUICException. Die Behandlung von OnQUICException ist nicht optional: Verbindungsfehler lösen keine Ausnahme aus, sie werden dort gemeldet, und Connect gibt lediglich False zurück.

4. Öffnen Sie die Verbindung mit Connect (blockierend, gibt ein Ergebnis zurück) oder Start / Active := True (nicht-blockierend).

5. Wenn Sie etwas empfangen müssen, rufen Sie nach dem Verbinden EnableMultiStream auf und behandeln Sie OnQUICStreamData. Zum Senden verwenden Sie WriteData für den Standard-Stream oder OpenStream plus WriteStreamData für einen bestimmten.

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

oClient.SSLQUICOptions.VerifyCertificate := True;
oClient.SSLQUICOptions.RootCertFile := 'ca.pem';
oClient.SSLQUICOptions.ConnectTimeout := 10000;

oClient.OnQUICConnect := OnQUICConnectEvent;
oClient.OnQUICStreamData := OnQUICStreamDataEvent;
oClient.OnQUICException := OnQUICExceptionEvent;

if oClient.Connect then
  oClient.WriteData('Hello QUIC');

uses
  sgcHTTP, sgcQUIC_Client, sgcQUIC_Classes;

procedure TForm1.Start;
begin
  FClient := TsgcQUICClient.Create(nil);
  FClient.Host := 'www.example.com';
  FClient.Port := 443;

  // TLS 1.3. Verification is off by default, turn it on.
  FClient.SSLQUICOptions.VerifyCertificate := True;
  FClient.SSLQUICOptions.RootCertFile := 'ca.pem';
  // the handshake timeout, 10000 ms is already the default
  FClient.SSLQUICOptions.ConnectTimeout := 10000;

  FClient.OnQUICConnect := OnQUICConnectEvent;
  FClient.OnQUICStreamData := OnQUICStreamDataEvent;
  FClient.OnQUICDisconnect := OnQUICDisconnectEvent;
  FClient.OnQUICException := OnQUICExceptionEvent;

  // Connect returns False without raising, the reason arrives on OnQUICException
  if not FClient.Connect(10000) then
    Log('connect failed');
end;

procedure TForm1.OnQUICConnectEvent(Sender: TObject; const Connection: TsgcQUICConnection);
var
  oStream: TsgcQUICClientStream;
begin
  Log('connected');

  // required before OnQUICStreamData will ever fire
  FClient.EnableMultiStream;

  oStream := FClient.OpenStream; // bidirectional
  if Assigned(oStream) then
    FClient.WriteStreamData(oStream, TEncoding.UTF8.GetBytes('Hello QUIC'))
  else
    Log('could not open a stream, is the builtin OpenSSL QUIC engine active?');
end;

procedure TForm1.OnQUICStreamDataEvent(Sender: TObject; aStreamId: Int64;
  aUnidirectional: Boolean; const aData: TBytes);
begin
  // raised on the read thread, do not touch the UI directly here
  Log(Format('stream %d: %d bytes', [aStreamId, Length(aData)]));
end;

procedure TForm1.OnQUICDisconnectEvent(Sender: TObject; const Connection: TsgcQUICConnection;
  Code: Int64; const Reason: string);
begin
  if Code = 0 then
    Log('closed cleanly')
  else
    Log(Format('closed, code %d: %s', [Code, Reason]));
end;

procedure TForm1.OnQUICExceptionEvent(Sender: TObject; const Connection: TsgcQUICConnection;
  const E: Exception);
begin
  Log('error: ' + E.Message);
end;