Module tech.kwik.agent15

module tech.kwik.agent15

Agent15 is a Java implementation of the handshake protocol of TLS 1.3 (RFC 8446, section 4). It was developed for, and is used by, QUIC implementations: QUIC uses TLS 1.3 for encryption, but only the handshake layer, not the record layer (see RFC 9001, section 3).

What is implemented

Agent15 implements all of the handshake protocol needed to set up and maintain a QUIC connection, including session resumption and 0-RTT. Because it targets QUIC, it implements only the handshake layer, not the TLS record layer. A few handshake messages are intentionally not implemented, as they are not used with QUIC: HelloRetryRequest, EndOfEarlyData and KeyUpdate. Unsupported extensions do not cause parsing to fail; the parser represents them with an UnknownExtension object.

Supported cryptography

Cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256.
Signature algorithms: rsa_pkcs1_sha256 (certificates only), rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512, ecdsa_secp256r1_sha256.
Named groups (key exchange): secp256r1, X25519.

Getting started

The public API lives in the tech.kwik.agent15.engine package.

• Client: instantiate a TlsClientEngine with a ClientMessageSender and a TlsStatusEventHandler, then call startHandshake(). The ClientMessageSender is the callback used to actually send handshake messages; the TlsStatusEventHandler lets the application react to TLS events needed for the QUIC handshake (for example, when early or handshake secrets become available). Any TLS message received should be passed to the engine's received method.
• Server: instantiate a TlsServerEngine with a ServerMessageSender, a TlsStatusEventHandler, and the server certificate and its private key. As with the client, any TLS message received should be passed to the engine, which takes care of sending the necessary messages back to the client.

QUIC's transport-parameters extension is supported by injecting a custom extension parser through the engine API. Session resumption uses a PSK obtained from a NewSessionTicket message; the server keeps session tickets in an in-memory cache, so a restart invalidates all outstanding tickets. Client authentication with a client certificate is supported by the client engine.

Security

Certificates are validated against the default Java truststore; a custom trust manager can be configured to use other certificate authorities.

Packages

Exports

Package	Description
tech.kwik.agent15	Core types shared across the library, such as protocol constants, protocol exceptions and session tickets.
tech.kwik.agent15.alert	TLS alert types, thrown as exceptions to signal protocol errors during the handshake.
tech.kwik.agent15.engine	The public API of the library: the client and server TLS engines and their factories, plus the callback interfaces an application implements to send messages and react to handshake events.
tech.kwik.agent15.env	Platform abstraction for mapping cryptographic algorithm names, needed because Android uses different names than standard Java.
tech.kwik.agent15.extension	The TLS extension types and the parser that dispatches to them; unsupported extensions are represented by UnknownExtension rather than causing a parse failure.
tech.kwik.agent15.handshake	The TLS 1.3 handshake message types (RFC 8446 §4), such as ClientHello, ServerHello, Certificate and Finished.