docs: add the kernel TLS design notes - #730
Open
lneto wants to merge 1 commit into
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design notes for the kernel TLS (kTLS) epic (#723), in the same shape as the other
doc/design/<theme>/sets: plan, proposed API, verified kernel reference, test strategy.doc/design/ktls/covers a kTLS binding so Lua scripts can key a connected socket for TLS, read andwrite plaintext while the kernel does the record-layer crypto, delegate the handshake to
tlshdthrough the kernel handshake upcall, and splice plaintext between sockets — enough for a TLS proxy or
an in-kernel TLS tunnel in Lua.
The design turns on one fact, stated up front so a contributor does not rediscover it the hard way:
It is built incrementally, and half the foundation already exists on a parked
claude_tlsbranch(
socket:setsockopt, atlscrypto-info packer, a handshake-upcall binding — but not onmaster,and without the data path). The early phases rebase that; the later phases add plaintext I/O with
control records, the handshake plumbing, and the tunnel. kTLS is a TCP ULP and a socket carries one
ULP, so we ride the kernel's
tlsULP; a Lua ULP (the successor to Pedro Tammela'sulp-lua) is aseparate project, kept as a non goal.
The
kernel-notes.mdfacts were verified against Linux 6.8 source and the running kernel's exportedsymbols: the two-step setsockopt keying, the module-callable handshake upcall (
tls_client_hello_*,all plain
EXPORT_SYMBOL), the-EIO-without-a-control-buffer gotcha on the plaintext read path, andthe version drift (TLS 1.3 KeyUpdate lands in 6.14, absent in 6.8).