{"id":23152816,"url":"https://github.com/ptrd/agent15","last_synced_at":"2025-08-17T20:33:19.867Z","repository":{"id":145798331,"uuid":"392422047","full_name":"ptrd/agent15","owner":"ptrd","description":"A (partial) TLS 1.3 implementation in Java.","archived":false,"fork":false,"pushed_at":"2024-12-01T10:41:15.000Z","size":887,"stargazers_count":13,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-01T11:29:10.214Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ptrd.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-LESSER.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-03T18:50:05.000Z","updated_at":"2024-12-01T10:41:18.000Z","dependencies_parsed_at":"2023-11-03T13:37:50.133Z","dependency_job_id":"af7d7a66-fff5-4344-b734-257f8410d2bf","html_url":"https://github.com/ptrd/agent15","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrd%2Fagent15","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrd%2Fagent15/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrd%2Fagent15/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrd%2Fagent15/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ptrd","download_url":"https://codeload.github.com/ptrd/agent15/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230168147,"owners_count":18183878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T19:18:54.035Z","updated_at":"2025-08-17T20:33:19.839Z","avatar_url":"https://github.com/ptrd.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Agent15](https://bitbucket.org/pjtr/agent15/raw/master/docs/media/Logo_Agent15_rectangle.png)\n\n# A (partial) TLS 1.3 implementation in Java\n\nAgent15 is an open source implementation of the [handshake protocol](https://datatracker.ietf.org/doc/html/rfc8446#section-4) of TLS 1.3. \nIt was developed for, and is used by [Kwik](https://bitbucket.org/pjtr/kwik/src/master/), a 100% pure Java implementation of the QUIC protocol. \nQUIC uses TLS 1.3 for encryption, but only the handshake layer, not the record layer (see [RFC 9001, sec 3](https://www.rfc-editor.org/rfc/rfc9001.html#name-protocol-overview)).\n\nAgent15 is created and maintained by Peter Doornbosch. The latest greatest can always be found on [BitBucket](https://bitbucket.org/pjtr/agent15).\n\n## Status\n\nAgent15 implements all of the handshake protocol that is needed to setup and maintain a QUIC connection, including\n[session resumption](https://datatracker.ietf.org/doc/html/rfc8446#section-2.2) \nand\n[0-RTT](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).\n\nNot all TLS 1.3 handshake messages are implemented (yet); some because they are not used at all in QUIC and others \nbecause the Kwik project does not use them. The messages that are not implemented are:\n\n- HelloRetryRequest\n- EndOfEarlyData: not used by QUIC, see https://www.rfc-editor.org/rfc/rfc9001.html#name-removing-the-endofearlydata\n- KeyUpdateRequest: not used by QUIC, see https://www.rfc-editor.org/rfc/rfc9001.html#name-key-update\n\nAlso, not all extensions are supported, see the [source](https://bitbucket.org/pjtr/agent15/src/master/src/main/java/tech/kwik/agent15/extension/) \nfor an overview of which extensions are supported. \nHowever, the message parser will create an `UnknownExtension` object for unsupported extensions, so parsing will not fail \n(as it does for unsupported handshake message types).\n\n#### QUIC extension support\n\nQUIC defines a custom TLS extension for carrying [Transport parameters](https://www.rfc-editor.org/rfc/rfc9001.html#name-quic-transport-parameters-e),\nthis is supported by Agent15 by means of a custom extension parser function that can be injected by the client application.\n\n\n### Supported cipher suites etc.\n\nAgent15 supports the following cipher suites:\n\n- TLS_AES_128_GCM_SHA256 (mandated by TLS 1.3 specification)\n- TLS_AES_256_GCM_SHA384\n- TLS_CHACHA20_POLY1305_SHA256\n\n\nThe following digital signatures are supported:\n\n- rsa_pkcs1_sha256 (for certificates only, in accordance with TLS 1.3 specification)\n- rsa_pss_rsae_sha256\n- rsa_pss_rsae_sha384\n- rsa_pss_rsae_sha512\n- ecdsa_secp256r1_sha256\n\nThe following elliptic curves are supported:\n\n- secp256r1\n- X25519\n\n### Features\n\nThe engines support session resumption with a PSK (obtained via a NewSessionTicket message). The server uses an in-memory\ncache to store session tickets, so a restart invalidates all tickets.\nClient authentication (by means of a client certificate) is supported in the client engine, but not yet for the server engine.\n\n### Usage\n\nMaven coordinates:\n\n    \u003cdependency\u003e\n        \u003cgroupId\u003etech.kwik\u003c/groupId\u003e\n        \u003cartifactId\u003eagent15\u003c/artifactId\u003e\n        \u003cversion\u003e3.1\u003c/version\u003e\n    \u003c/dependency\u003e\n\n\nClient: instantiate a `TlsClientEngine` with a `ClientMessageSender` and a `TlsStatusEventHandler` and call `startHandshake()` on it.\nThe `ClientMessageSender` is the callback to let the client actually send the handshake messages. \nThe `TlsStatusEventHandler` enables to client to react TLS events that are needed for the QUIC handshake,\ne.g. when the early secrets or the handshake secrets are known (QUIC computes its own secrets based on the TLS secrets).\nAny TLS message received should be passed to the engine's `received` method, which is done automatically by the `TlsMessageParser` \nwhen calling its `parseAndProcessHandshakeMessage()` method.\n\nServer: instantiate a `TlsServerEngine`. In addition to a `ServerMessageSender` and a `TlsStatusEventHandler` that serve\nanalogous purpose as in the client case, the server certificate and its private key need to be provided as well. \nAs with the client, any TLS message received should be passed to the engine, which will take care of sending all necessary \nmessages back to the client.\n\n#### Building\n\nUse the gradle wrapper to build the library: `./gradlew build` (or on Windows: `gradlew.bat build`).\n\n### Security\n\nCertificates are checked using the default Java truststore. Other CA's can be used by setting a custom trustmanager.\n\nAll security aspects required by TLS are (supposed to be) implemented, I you find any discrepancies with the TLS 1.3 \nspecification, please file a bug report or contact the author.  \nNo security checks or reviews have been made for this library; use at your own risk. \n\n## Contact\n\nIf you have questions about this project, please mail the author (peter dot doornbosch) at luminis dot eu.\n\n## Acknowledgements\n\nMany thanks to Michael Driscoll ([@xargsnotbombs](https://twitter.com/xargsnotbombs)) for writing \nthe brilliant [\"The New Illustrated TLS Connection, Every byte explained and reproduced\"](https://tls13.ulfheim.net/);\nI never would have succeeded in writing a functional TLS library without this help. \nThanks to Piet van Dongen for creating the marvellous logo!\n\n## License\n\nThis program is open source and licensed under LGPL (see the LICENSE.txt and LICENSE-LESSER.txt files in the distribution). \nThis means that you can use this program for anything you like, and that you can embed it as a library in other applications, even commercial ones. \nIf you do so, the author would appreciate if you include a reference to the original.\n \nAs of the LGPL license, all modifications and additions to the source code must be published as (L)GPL as well.\n\nIf you want to use the source with a different open source license, contact the author.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrd%2Fagent15","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fptrd%2Fagent15","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrd%2Fagent15/lists"}