NET Stack V5.5.5 — PureBasic Network Framework

Version: 5.5.5 — OpenSSL-3.x Ticket-Callback Race-Fix (EVP_CIPHER_fetch + EVP_MAC) Datum: April 2026 Plattform: Linux x86_64 Sprache: PureBasic 6.x Lizenz: Kommerziell + LGPL v2.1 only

---

Übersicht

Vollständiger Netzwerk-Stack für PureBasic mit nativem QUIC-Support. Von Low-Level I/O bis QUIC Transport — alles aus einem Guss.

Kennzahlen

Metrik	Wert
Module	17
Quellcode	~22.000 Zeilen
Testsuite	38 Suites, 649 Tests
QUIC-Stack	~7.400 Zeilen (nativ, kein Wrapper)
Unterstützte Protokolle	TCP, UDP, Unix, QUIC, TLS 1.2/1.3, Multicast/Broadcast
Security-Findings	49 analysiert, 49 gefixt, 0 offen

Module

net_lib/
├── atomic-ops.pbi          (205 Zeilen)  Lock-free atomare Operationen
├── lock-free-queue.pbi     (369 Zeilen)  MPMC Queue
├── NET_Core.pbi           (2.774 Zeilen) Kern: Connections, Streams, I/O, Ref-Counting
├── tls-openssl.pbi        (3.100 Zeilen) OpenSSL TLS 1.2/1.3 + QUIC_METHOD + EVP_MAC
├── tls-dummy.pbi          (1.027 Zeilen) Test-Stub (kein echtes TLS)
├── NET_Server.pbi         (1.643 Zeilen) Event-Loop Server mit epoll
├── NET_Client.pbi           (974 Zeilen) Async Client + Pooling
├── quic-native.pbi        (6.820 Zeilen) Nativer QUIC Stack (RFC 9000)
├── quic-perf.pbi            (695 Zeilen) GSO/GRO, ECN, Pacing Primitiven
├── quic-integration.pbi     (170 Zeilen) QUIC ↔ NET_Core Bootstrap
├── NET_Metrics.pbi          (590 Zeilen) Prometheus Metriken
├── NET_Shaping.pbi          (574 Zeilen) Token/Leaky Bucket Shaping
├── NET_Multicast.pbi        (783 Zeilen) Multicast/Broadcast Transport-Primitiven
├── NET_Discovery.pbi      (1.357 Zeilen) mDNS/DNS-SD Service Discovery
├── UnixSocket.pbi          (V5.5, ~120) Kompatibilitäts-Mapper für WEB_Framework
├── NET_Framing.pbi         (V5.5, ~180) Generic length-prefixed Frame-Assembler
├── NET_Correlation.pbi     (V5.5, ~170) Request/Response-Map mit Timeout-GC

---

V5.5.5 — OpenSSL-3.x Ticket-Callback Race-Fix + Header-Cleanup

Produktion zeigte sporadische Crashes im _TicketKeyCallback mit zwei Symptomen aus dem gleichen Root-Cause:

• SEGV in libcrypto bei EVP_CipherInit_ex → EVP_CIPHER_fetch → OPENSSL_LH_retrieve (NULL-Deref im Cache-Bucket)
• "free invalid size" ABRT, wenn ein halb-initialisierter EVP_CIPHER* später beim Free explodiert

Ursache: Die Legacy-Getter EVP_aes_128_cbc() / EVP_sha256() liefern in OpenSSL 3.x einen Pointer mit origin = EVP_ORIG_GLOBAL. EVP_CipherInit_ex triggert damit intern bei jedem Callback einen Provider-Fetch über einen globalen Hash — nicht thread-safe gegen parallele TLS-Worker.

Fix (zwei Ebenen, beide OpenSSL-3.x-nativ mit transparentem 1.1.x-Fallback):

1. Cipher/Digest einmalig fetchen. EVP_CIPHER_fetch("AES-128-CBC") + EVP_MD_fetch("SHA256") beim Init. Gefetchte Pointer tragen origin = EVP_ORIG_DYNAMIC → kein Re-Fetch im Hot-Path. Cleanup via EVP_CIPHER_free / EVP_MD_free (refcount-korrekt). 1.1.x-Fallback: Legacy-Getter gecached (dort existiert kein Race, weil keine Provider-Infrastruktur). Betroffen: _TicketKeyCallback (4 Call-Sites) + GetCertInfo SHA-256-Fingerprint.

2. EVP_MAC statt HMAC_CTX. SSL_CTX_set_tlsext_ticket_key_evp_cb (OpenSSL 3.0+) registriert einen neuen _TicketKeyCallbackEVP, der einen EVP_MAC_CTX statt HMAC_CTX erhält. OpenSSL hält den EVP_MAC intern vor; Callback ruft nur EVP_MAC_init mit einem pre-built OSSL_PARAM-Array (digest = "SHA256"). Eliminiert den analogen HMAC_Init_ex-Lazy-Fetch-Race. Legacy-Callback bleibt als 1.1.x-Fallback registriert.

Header-Cleanup (alle 17 .pbi): einheitlicher Copyright + SPDX + LGPL-Block (Projekt-String korrigiert: 8 Files trugen fälschlich "PureBasic HTTP Stack V3.2"), Per-File-Changelog-Blöcke entfernt (Git-Log ist die Wahrheit), Modul-Header auf knappe Beschreibung + Verweis auf README reduziert.

Tests: v5.2 (TLS, 422/422), v5.3 (QUIC/Discovery, 125/125), Unix-Sockets (98/102; 1 pre-existing Stale-bind-Fail, 3 skipped). Race ist Thread-Timing — nicht unit-testbar; Code-Pfade Init/Registrierung/Cleanup sind durch die Suite abgedeckt.

---

V5.5.4 — net_lib als Git-Submodule

Der net_lib/-Ordner ist ab V5.5.4 kein vendored Code mehr, sondern ein Git-Submodule der auf ssh://git@gitea.lihaso.com:3001/PB_Includes/net_lib.git verweist.

Warum? Drei Repos nutzen net_lib/ am gleichen Pfad (NET_Framework-Tests, HTTP_Framework, purepower-framework). Ohne Submodule-Setup mussten Änderungen manuell in alle drei Repos kopiert werden — Fixes sind dadurch z.B. im WEB_Framework gelandet aber nie zurück ins NET_Framework. Das hat die V5.5.1–V5.5.3-Backport-Serie verursacht.

Struktur:

• PB_Includes/net_lib — Distribution-Repo (nur .pbi-Files auf Root-Level, Source of Truth)
• PB_Includes/NET_Framework — Dev-Repo mit Tests/Docs/Makefile (mountet net_lib/ als Submodule)
• PB_Includes/HTTP_Framework — Protokoll-Layer (mountet net_lib/ als Submodule)
• LIHASO/purepower-framework — WebApp (mountet net_lib/ als Submodule)

Checkout nach Clone:

git clone --recurse-submodules ssh://git@gitea.lihaso.com:3001/PB_Includes/NET_Framework.git
# oder bei bereits geklontem Repo:
git submodule update --init

Release-Workflow:

1. Code-Änderung im net_lib/-Submodule (→ cd net_lib && git add . && git commit)
2. Commit + Push im net_lib-Repo
3. Im NET_Framework: Submodule-Pointer aktualisieren (git add net_lib && git commit)
4. Tests laufen lassen
5. Beide Repos taggen (git tag v5.5.5 in beiden, gleichnamig)
6. Beide pushen

---

V5.5.1 — Backports aus WEB_Framework

Vor dem Vendor-Checkout ins WEB_Framework festgestellt: dort existieren Features/Fixes die nie ins NET_Framework zurückportet wurden. Die wichtigsten sind jetzt drin:

Kritischer Bugfix

TLS-Partial-Transfer bei HTTPS > 65KB (NET_Core): Der EPOLLOUT-Flush-Handler nutzte _WriteNonBlocking (raw write) für alle Connections — bei TLS schrieb er damit Klartext auf den TLS-FD → NS_ERROR_NET_PARTIAL_TRANSFER für Dateien > ~65KB über HTTPS. Fix: _ConnectionWrite wenn tls_active. Zusätzlich: Direct-Write-Loop wartet bei TLS-WANT_WRITE per WaitForEvent im selben Thread (verhindert Race auf dem SSL-Objekt).

QUIC Multi-Domain Hosting (SNI)

• SetSNICallback(*callback) in QUIC_Native — App liefert Callback der pro Hostname _QUICSNIEntry mit cert_file + key_file zurückgibt
• Per-Hostname SSL_CTX Cache (_quic_sni_ctxs Map)
• OpenSSL SSL_CTX_callback_ctrl + SSL_get_servername + SSL_set_SSL_CTX Bindings
• Ein QUIC-Port hostet N HTTPS/3-Domains mit eigenen Certs

Let's Encrypt fullchain Support

• SSL_CTX_use_certificate_chain_file Binding in quic-native
• Server-Cert-Loader bevorzugt Chain-File, Fallback auf einzelnes Cert
• Let's Encrypt fullchain.pem funktioniert jetzt direkt

TLS-SNI Connection-Tracking

• TLS_OpenSSL::GetRawSSLCtx(*wrapper_ctx) — SSL_CTX* aus Wrapper extrahieren
• TLS_OpenSSL::GetConnectionSNI(fd) — SNI-Hostname pro Connection nachschlagen (für HTTP/2 "421 Misdirected Request")
• TLS_OpenSSL::ClearConnectionSNI(fd) — Cleanup bei Connection-Close
• SSL_get_fd Binding

---

V5.5 — Unix Domain Sockets + NET_Framing + NET_Correlation

Unix Domain Sockets (komplett implementiert)

Lokale IPC über AF_UNIX — vorher nur als Platzhalter (#TRANSPORT_UNIX = 3) in V4.0 angekündigt, jetzt vollständig mit epoll-Integration:

• SOCK_STREAM Pathname Sockets — /tmp/app.sock, automatisches Stale-Socket-Cleanup
• Abstract Namespace — @myapp-Syntax (Linux), keine Filesystem-Einträge
• SOCK_DGRAM Unix — nachrichtenbasiert, für lokale Logging/Events
• SO_PEERCRED — Peer-Authentifizierung via UID/GID/PID (NET_Core::GetPeerCredentials)
• systemd Socket Activation — AddListenerFromFD + GetSystemdListenerFDs (LISTEN_FDS-Protokoll)
• TLS über Unix — funktioniert über bestehenden TLS-Pfad (für Container-IPC mit mTLS)
• Connection Pool — AcquireUnixConnection(path, tls) analog TCP-Pool
• Permissions — ListenerConfig\unix_mode für chmod nach bind
• UnixSocket Kompatibilitäts-Mapper — drop-in für WEB_Framework/Infrastructure/UnixSocket.pbi

NET_Framing (neu) — Generic Length-Prefixed Frame Assembler

Partial-reads aus OnData-Callbacks akkumulieren, Callback pro vollständigem Frame. Konfigurierbar für PPMSG (4 BE), HTTP/2 (3 BE), WebSocket (2/8 BE), gRPC:

Protected cfg.NET_Framing::AssemblerConfig
cfg\header_bytes = 4 : cfg\big_endian = #True
cfg\max_frame_size = 16 * 1024 * 1024
cfg\include_header = #False   ; nur Body an Callback

Protected *asm = NET_Framing::Create(@cfg, @MyFrameHandler())
NET_Framing::Feed(*asm, *partial_data, len)    ; feuert Callback pro Frame

NET_Correlation (neu) — Request/Response-Map mit Timeout-GC

App-provided Seq-ID → Callback + Timeout. Poll-basierte Timeout-Erkennung:

Protected *map = NET_Correlation::CreateMap()
NET_Correlation::Register(*map, my_seq, @OnResponse(), ctx, 5000)
; ... Request senden ...
; Bei Response-Empfang:
NET_Correlation::Match(*map, seq, *response_data, len)
; Im Event-Loop:
NET_Correlation::TickTimeouts(*map)

PluginSupervisor-Migration ready

Die drei neuen Module (UnixSocket, NET_Framing, NET_Correlation) + NET_Client::ConnectUnix geben das komplette Fundament für async Plugin-IPC:

• Use-Case A (blockierende Plugins): UnixSocket::* Include-Pfad tauschen, API identisch
• Use-Case B (async Supervisor): ConnectUnix + NET_Framing für PPMSG + NET_Correlation für Request/Response

---

V5.4 — Security-Hardening + OpenSSL Zukunftssicherung

Security-Fixes (Mistral Security Check)

Alle 49 Findings aus dem Mistral Security Audit wurden verifiziert und behoben:

• QUIC Certificate Validation — SSL_VERIFY_PEER wird für QUIC-Clients erzwungen
• Session Ticket Security — RAND_bytes statt unsicherem Random(255)-Fallback
• OCSP Signature Validation — OCSP_basic_verify für vollständige Signaturprüfung
• SSL Shutdown Handling — Return-Values geprüft, kein doppelter Shutdown
• Buffer Limits — 16 MB Cap (#MAX_QUIC_BUFFER) gegen unbounded growth
• Ref-Counting — _FindAndAcquire/_ReleaseConn mit atomaren Operationen gegen Use-After-Free

Pending-Frame-Queue (neu)

• RESET_STREAM und STOP_SENDING werden jetzt tatsächlich als QUIC-Frames gesendet
• PATH_RESPONSE / NEW_CONNECTION_ID gehen nicht mehr bei Buffer-Overflow verloren
• Pacing blockiert keine Control-Frames mehr — ACKs und Control-Frames umgehen Pacing
• Queue mit Overflow-Schutz (max 64 Frames pro Connection)

Token Storage + 0-RTT Session Resumption (neu)

• Retry-Token wird bei Retry-Empfang gespeichert und im nächsten Initial Packet mitgesendet
• NEW_TOKEN wird gespeichert für 0-RTT Reconnects
• Session Ticket Serialisierung via i2d_SSL_SESSION/d2i_SSL_SESSION
• Get0RTTTicket() / Set0RTTTicket() für vollständige 0-RTT Resumption

ALPN Fix

• OPENSSL_NPN_NEGOTIATED ist 1, nicht 0 — HTTP/2 und HTTP/3 ALPN-Negotiation funktioniert jetzt korrekt

OpenSSL 3.0+ / 4.0 Zukunftssicherung

Feature	OpenSSL 3.1 (Leap 15.6)	OpenSSL 3.5+	OpenSSL 4.0
TLS 1.2/1.3	Ja	Ja	Ja
Ticket-Key (EVP_MAC)	Ja (neu)	Ja	Ja (Pflicht)
Ticket-Key (HMAC legacy)	Ja (Fallback)	Ja	Nein (entfernt)
CA-Verify (file/dir API)	Ja (neu)	Ja	Ja (Pflicht)
CA-Verify (legacy)	Ja (Fallback)	Ja	Deprecated
QUIC/H3	Nur mit quictls	Nativ	Nativ

Runtime-Erkennung: TLS_OpenSSL::IsQUICAPIAvailable() + GetQUICDiagnostics() für automatische Feature-Detection.

---

V5.3 — QUIC Performance + Multicast/Discovery

QUIC Performance (quic-perf.pbi)

• UDP GSO (Generic Segmentation Offload) — 1 Syscall statt N, Kernel 4.18+
• UDP GRO (Generic Receive Offload) — Aggregierte Pakete beim Empfang
• ECN (Explicit Congestion Notification, RFC 3168) — CE-Feedback in Reno/Cubic CC
• Pacing (Token-Bucket, RFC 9002 §7.7) — Rate = 1.25 x cwnd/RTT

Multicast & Broadcast (NET_Multicast.pbi)

• IPv4/IPv6 Multicast — JoinGroup() / LeaveGroup()
• Source-Specific Multicast (SSM) — JoinSourceGroup()
• Broadcast — SO_BROADCAST, Limited + Directed Broadcast
• Standalone Sockets mit automatischem Group-Tracking

Service Discovery (NET_Discovery.pbi)

• mDNS (RFC 6762) — Multicast DNS auf 224.0.0.251:5353
• DNS-SD (RFC 6763) — AnnounceService(), BrowseServices(), ResolveService()
• DNS Wire Format — Vollständiger Encoder/Decoder mit Pointer-Compression
• TTL-basierter Cache mit Re-Announcement und Goodbye-Paketen

---

V5.2 — OpenSSL 3.5 QUIC Integration

• QUIC_METHOD-Callbacks für OpenSSL 3.5 QUIC-API
• TLS-Message-Boundary-Parsing im Pull-Modell
• ERR_clear_error Cleanup + EVP_MD_get_size Migration
• C-int Rückgabewerte für korrekte Sign-Extension

---

Quick Start

1. TCP Echo-Server (3 Zeilen Logik)

XIncludeFile "net_lib/atomic-ops.pbi"
XIncludeFile "net_lib/lock-free-queue.pbi"
XIncludeFile "net_lib/NET_Core.pbi"
XIncludeFile "net_lib/tls-openssl.pbi"
XIncludeFile "net_lib/NET_Server.pbi"

Procedure OnData(conn.i, *buf, len.i) : NET_Core::Send(conn, *buf, len) : EndProcedure

NET_Server::Init()
NET_Core::SetCallbackData(@OnData())
Define c.NET_Core::ListenerConfig : c\bind_ip="0.0.0.0" : c\port=9000
c\transport_type=1 : c\flags=$05
NET_Server::AddListener(@c)
NET_Server::Run()

2. QUIC/H3 Server

; Prüfen ob QUIC verfügbar ist (OpenSSL 3.5+ oder quictls)
If TLS_OpenSSL::IsQUICAPIAvailable()
  QUIC_Integration::Setup()
  QUIC_Native::SetCallbackStreamData(@OnStreamData())
  NET_Server::AddQUICListener("0.0.0.0", 4433, "cert.pem", "key.pem")
  NET_Server::Run()
Else
  Debug TLS_OpenSSL::GetQUICDiagnostics()
EndIf

3. QUIC Client mit 0-RTT

QUIC_Integration::SetupClient()
conn = NET_Client::ConnectQUICByHostname("example.com", 443)

; Session Ticket speichern für 0-RTT bei Reconnect
Dim ticket.b(4095)
ticket_len = QUIC_Native::Get0RTTTicket(conn, @ticket(0), 4096)

; Späterer Reconnect mit 0-RTT
conn2 = NET_Client::ConnectQUICByHostname("example.com", 443)
QUIC_Native::Set0RTTTicket(conn2, @ticket(0), ticket_len)

---

Kompilieren & Testen

# Build + alle 649 Tests ausführen
make test

# Einzelne Testsuites
make test-v5.2    # Transport + QUIC (422 Tests)
make test-v5.3    # GSO/GRO/ECN/Multicast/Discovery (125 Tests)

# Clean
make clean

---

Abhängigkeiten

• PureBasic 6.x (Linux x86_64, C-Backend)
• OpenSSL 3.x+ (libcrypto.so + libssl.so)
• Linux Kernel 3.9+ (epoll, sendfile); Kernel 4.18+ für GSO/GRO

OpenSSL / QUIC Setup

Distribution	TLS/TCP	QUIC/H3
openSUSE Leap 15.6	zypper install libopenssl-3-devel	quictls installieren (s.u.)
openSUSE Tumbleweed	zypper install libopenssl-3-devel	OpenSSL 3.5+ nativ
Debian/Ubuntu	apt install libssl-dev	quictls oder OpenSSL 3.5+
Fedora/RHEL	dnf install openssl-devel	quictls oder OpenSSL 3.5+
Arch	pacman -S openssl	OpenSSL 3.5+ nativ

quictls (QUIC auf OpenSSL < 3.5): Auto-Detection sucht: libssl-quic.so.3, /opt/quictls/, /usr/local/quictls/, System-Pfade.

---

Verzeichnisstruktur

NET_Framework/
├── net_doc/
│   ├── README.md                    Diese Datei
│   ├── NET_API-Referenz.md          Vollständige API-Dokumentation
│   ├── NET_Demo-Benutzung.md       Codebeispiele & Tutorials
│   ├── LLM_FALLSTRICKE.md          85 PureBasic Pitfalls
│   ├── LLM_CODE_QUALITY.md         9 Code-Quality-Regeln
│   ├── LLM_NET_STACK.md            Architektur-Guide
│   └── Mistral_Security_Check.md   Security Audit Report
├── net_lib/                         Alle Module (.pbi)
├── net_tests/                       Testsuites
│   └── bin/                         Kompilierte Test-Binaries
├── Makefile                         Build-System
└── CLAUDE.md                        Claude Code Projektanweisungen

---

Versionsverlauf

Version	Datum	Highlights
1.0	2025	TCP Server, epoll, Lock-Free Queue
2.0	2025	TLS_OpenSSL, Atomic Ops
3.0	2025	HTTP Server, Client, Multi-Listener
3.1	2025	TLS 1.3, Session Tickets, HSTS
4.0	2025	IPv6, DNS (Unix Domain Sockets als Konstante reserviert — real implementiert in V5.5)
4.2	2025	Connection Pooling, Rate Limiting
5.0	2026	Stream Multiplexing, Certificate Validation, OCSP
5.1	2026	Native QUIC Stack, HTTP/3-Ready
5.2	2026	OpenSSL 3.5 QUIC_METHOD, TLS-Message-Boundary-Parsing
5.3	2026	GSO/GRO, ECN, Pacing, Multicast/Broadcast, mDNS/DNS-SD
5.4	2026	Security-Hardening, Pending-Frame-Queue, 0-RTT Session Tickets, ALPN Fix, OpenSSL 4.0 Readiness
5.5	2026	Unix Domain Sockets (Stream+Dgram+Abstract+SO_PEERCRED+systemd), NET_Framing, NET_Correlation, UnixSocket-Mapper
5.5.1	2026	Backports aus WEB_Framework: TLS-Partial-Transfer-Fix, QUIC SNI Multi-Domain, Let's Encrypt fullchain, SNI-Connection-Tracking
5.5.2	2026	Stream-Send-Loop: Offset-basiert (O(N²)→O(N) MoveMemory) — Perf-Backport aus WEB_Framework
5.5.3	2026	Patch: SNI-Callback-Guard (listener_id > 0) — verhindert Rekursions-Crash bei SSL_set_SSL_CTX auf per-Host-Contexts
5.5.4	2026	net_lib wird Git-Submodule — Distribution-Repo PB_Includes/net_lib als Shared Source für alle Consumer (NET_Framework Tests + HTTP_Framework + purepower-framework)
5.5.5	2026	OpenSSL-3.x Lazy-Fetch-Race-Fix in _TicketKeyCallback — EVP_CIPHER_fetch + EVP_MD_fetch gecached, SSL_CTX_set_tlsext_ticket_key_evp_cb mit EVP_MAC_CTX (eliminiert SEGV + free-invalid-size-ABRT). Header-Cleanup über alle 17 .pbi.

---

Roadmap

V6.0 — Cross-Platform (Windows + macOS)

• Platform-Abstraction-Layer (epoll / IOCP / kqueue)
• Winsock-Kompatibilität (Overlapped I/O)
• Plattform-unabhängige Atomics (GCC Builtins / MSVC Intrinsics)
• OpenSSL-Pfade pro Plattform (Homebrew, vcpkg, System)

Protokoll-Stack (separates Projekt)

HTTP/3 (QPACK, Frame Layer, Server/Client) und WebSocket (TCP + QUIC) sind Protokoll-Layer und werden im HTTP-Protokoll-Stack entwickelt — nicht im NET Transport-Stack.

---

AI-Assistierte Entwicklung

Dieses Projekt wurde mit Unterstützung mehrerer AI-Systeme entwickelt. Jedes System hat mit seinen Stärken zu verschiedenen Aspekten beigetragen:

AI-System	Beiträge
Claude (Anthropic)	QUIC Pending-Frame-Queue, Token Storage, 0-RTT Session Tickets, OpenSSL 3.0+/4.0 Zukunftssicherung (EVP_MAC, verify_file/dir), ALPN Fix, Security-Fix-Verifikation, RAND_bytes Hardening
Mistral	Security Audit (49 Findings), QUIC Certificate Validation, OCSP Signaturvalidierung, Buffer Limits, Ref-Counting Analyse
Gemini (Google)	Architektur-Reviews, Code-Optimierungen, Performance-Analysen
ChatGPT (OpenAI)	Konzeptionelle Entwürfe, API-Design, Dokumentationsvorlagen
DeepSeek	Code-Analyse, Algorithmus-Optimierungen
Grok (xAI)	Technische Recherche, RFC-Referenzen

Die finale Integration, Qualitätskontrolle und alle Architektur-Entscheidungen liegen beim menschlichen Entwickler.

---

Lizenz

Dual-lizenziert:

• LGPL v2.1 only — für Open-Source-Projekte
• Kommerzielle Lizenz — für proprietäre Nutzung ohne LGPL-Pflichten

Copyright (c) 2025-2026. Alle Rechte vorbehalten.