AtlatestRepositorysigil-quic
sigil-quic / treeREADME.md
1
# sigil-quic3
Experimental QUIC v1 for [Sigil](https://codeberg.org/sigil/sigil), including4
packet protection, a TLS 1.3 handshake engine, bounded connection and stream5
state, and a UDP endpoint adapter.7
## Status9
Early development. Client/server handshakes, authenticated Retry, sequential10
bidirectional streams, RFC 9221 DATAGRAM, authenticated path migration, and11
numeric IPv4/IPv6 endpoints are implemented and covered by tests. TLS uses12
AES-128-GCM/SHA-256, X25519, and P-256 signatures. HQ interoperability tools13
are included. Full QUIC key update, 0-RTT, PSK authentication, and a built-in14
X.509 trust store are not implemented. Applications must provide a certificate15
verifier or an independently trusted public-key pin. The library needs16
independent security review before production use.18
## Dependency20
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`:22
```scheme23
(from-git url: "codeberg:sigil/sigil-quic" branch: "master")24
```26
Requires sigil-crypto ^0.18.1. The package declares Sigil 0.22 dependencies.27
The endpoint adapter needs IPv4/IPv6-aware UDP support: `udp-socket` families28
and `socket-normalize-address`. This support is not in a released Sigil yet29
and is planned for an upcoming release.31
## Usage33
Derive client Initial packet keys for the example destination connection ID34
from RFC 9001, then release the owned key material:36
```scheme37
(import (sigil quic packet))39
(let ((keys (initial-keys #u8(131 148 200 240 62 81 87 8) 'client)))40
; Vector entries: traffic secret, AES key, IV, header-protection key.41
(display (bytevector-length (vector-ref keys 1))) ; => 1642
(discard-packet-keys! keys))43
```45
For connections, use `(sigil quic connection)` and drive its receive, output,46
and timer calls, or use `(sigil quic endpoint)` for the UDP adapter. See the47
[API and implementation notes](docs/implementation.md) for identity verification,48
stream handling, DATAGRAM limits, migration, cleanup, and endpoint options.49
The [HQ adapter](tools/hq/README.md) is a complete transfer example.51
## Tests53
On a Linux host with a C toolchain and the required socket APIs:55
```sh56
sigil deps install57
sigil test --report58
```60
Tests cover RFC vectors, malformed input, bounded state, failure cleanup, and61
loopback UDP. For a single native executable using the same test bodies:63
```sh64
node scripts/native-tls-tests.mjs65
cd build/native-tests66
sigil deps install67
sigil build --config native68
build/native/bin/quic-native-tests69
```71
The packet probe also provides byte-corruption controls:73
```sh74
sigil build --config native75
QUIC_PROBE_SKIP_BENCH=1 scripts/run-gates.sh build/native/bin/quic-probe76
```78
## License80
BSD-3-Clause. See [LICENSE](LICENSE).