Skip to content

ktls: Build the OCF software backend into the kernel (fixes #667) - #672

Merged
laffer1 merged 4 commits into
masterfrom
ktls-ocf-builtin
Nov 19, 2026
Merged

laffer1 merged 4 commits into
masterfrom
ktls-ocf-builtin

Conversation

@laffer1

@laffer1 laffer1 commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Fixes #667.

Ports FreeBSD 21e3c1fbe246 ("Assume OCF is the only KTLS software backend"). KTLS no longer supports loadable software backends. The OCF backend is built into every kernel with options KERN_TLS, and ktls_ocf.ko is removed. Both parts of #667 are fixed:

  1. KTLS software mode works without loading a module. tests/sys/kern/ktls_test no longer needs kldload ktls_ocf.
  2. ktls_try_sw() used to replace the backend's error with EOPNOTSUPP whenever no backend accepted the session. It now calls ktls_ocf_try() directly and returns its error, so enabling receive for AES-CBC fails with EPROTONOSUPPORT, as the tests expect.

Commits

FreeBSD Subject
21e3c1fbe246 Assume OCF is the only KTLS software backend.
6b313a3a6045 Include the trailer in the original dst_iov. (a same-day follow-up to 21e3c1fbe246)
7ffc9b15ba9c ktls: Update documentation for software backends. (ktls.4)
UPDATING: note ktls_ocf built into the kernel

How 21e3c1fbe246 was ported

Our KTLS code matched FreeBSD stable/13, which never merged this commit. stable/13 then picked up a dozen later head changes that had been rewritten for the old backend API. I three-way merged uipc_ktls.c, ktls_ocf.c and ktls.h, using FreeBSD's tree just before 21e3c1fbe246 as the base. Each conflict was resolved against head's own post-21e3c1fbe246 version of the same code.

  • Kept from stable/13:
    • the split encrypt and decrypt OCF counters (16bea05ac327)
    • synchronous OCF dispatch
    • TLS 1.3 receive (05a1d0f5d7ac)
    • TLS 1.0 sequential records (9f03d2c00167, 4827bf76bce8)
    • the AEAD minimum record length check (4e4741464889)
    • the MAC session free (4b337ada34bc)
    • ktls_drop()
    • the TLS 1.0 empty-fragment accounting (d16cb228c1a6)
    • vm_page_alloc_noobj() for sendfile pages
  • Not imported: head's 16k buffer zone (ktls_buffer_alloc), which 21e3c1fbe246's version of ktls_encrypt() uses but stable/13 never had.
  • Our security fixes: 257e33b and 2e27a51 are in the receive path, which this change leaves alone.
  • __FreeBSD_version: FreeBSD bumped it for out-of-tree backends. I didn't, because we have none.
  • ObsoleteFiles: FreeBSD added no entry for ktls_ocf.ko, since installkernel replaces /boot/kernel. I didn't either.

Testing

  • Builds: amd64 GENERIC with INVARIANTS and WITNESS, and arm64 GENERIC (the configs with KERN_TLS), build. ktls_ocf.o is linked into the kernel and no ktls_ocf.ko is built. The only uipc_ktls.c warnings are three on arm64 that master also has.
  • bhyve guest, amd64 debug kernel:
    • ktls_test with kern.ipc.tls.enable=1 and no kldload: 281/281 pass. Master gets 22/281 without loading ktls_ocf.ko and 271/281 with it.
    • The ocf stats show TLS 1.0–1.3 encrypt and decrypt traffic for GCM, ChaCha20 and CBC.
    • No lock-order reversals and no panics. The only one in the logs, ufs -> devfs at shutdown, shows up on master too.
  • Sendfile path: ktls_test never sends from a file, so the separate-output encrypt path (file pages encrypted into new pages, which 6b313a3a6045 changed) went untested. A guest-only program sendfile()d a 400 KiB file over a KTLS loopback connection. It used 8 offset and length mixes (unaligned starts, 1 byte, 3 bytes, exact and spanning 16 KiB records, multi-record) and covered 10 suites: AES-GCM 128 and 256 for TLS 1.2 and 1.3, ChaCha20-Poly1305 for TLS 1.2 and 1.3, and AES-CBC for TLS 1.0, 1.1 and 1.2 with SHA1, SHA256 and SHA384. The receiver decrypted every record in userspace with OpenSSL, checking tags, MACs and padding, and compared the result with the file. All 80 cases pass.

Separate existing bug found while testing

Using KTLS receive on the peer socket instead of OpenSSL, AEAD records of about 4 KiB or more fail with EBADMSG. This also happens with write(2) on the sender, and on unpatched master with ktls_ocf.ko loaded. Records are rejected because our CVE-2026-45257 fix (257e33b) treats mbufs converted for the loopback interface as shared. FreeBSD had the same regression (PR 296498) and fixed it in 0af1065b3a57. Filed as #673, fixed separately in #674.

🤖 Generated with Claude Code

bsdjhb and others added 4 commits November 19, 2026 09:29
This removes support for loadable software backends.  The KTLS OCF
support is now always included in kernels with KERN_TLS and the
ktls_ocf.ko module has been removed.  The software encryption routines
now take an mbuf directly and use the TLS mbuf as the crypto buffer
when possible.

Our KTLS code matched FreeBSD stable/13, which never merged this
change, so it was ported by hand on top of the later stable/13 work
already in the tree.  Kept as in stable/13: the split encrypt and
decrypt counters, synchronous OCF dispatch, TLS 1.3 receive, the TLS
1.0 sequential record handling, the minimum AEAD record length check
and the vm_page_alloc_noobj() page allocation for sendfile records.
The 16k buffer zone that FreeBSD head used in ktls_encrypt() is not
imported.  The __FreeBSD_version bump is not applied.

With the backend list gone, errors from ktls_ocf_try() now reach the
caller.  Enabling receive for AES-CBC fails with EPROTONOSUPPORT
instead of EOPNOTSUPP, which is what tests/sys/kern/ktls_test expects.

Fixes:		#667
Obtained from:	FreeBSD 21e3c1fbe246
AI-Assisted-by:	Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Lucas Holt <luke@foolishgames.com>
This avoids creating a duplicate copy on the stack just to
append the trailer.

Obtained from:	FreeBSD 6b313a3a6045
AI-Assisted-by:	Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Lucas Holt <luke@foolishgames.com>
KTLS no longer supports multiple software backends.  Instead, it
always uses OCF for software crypto.  In particular, the ktls_ocf.ko
module no longer exists.  The OCF bits for KTLS are compiled into the
kernel instead.

Obtained from:	FreeBSD 7ffc9b15ba9c
AI-Assisted-by:	Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Lucas Holt <luke@foolishgames.com>
AI-Assisted-by:	Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Lucas Holt <luke@foolishgames.com>
@sourcery-ai

sourcery-ai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Data structures

Update the KTLS session interface for direct OCF use, replacing the pluggable-backend fields and callback signature with the mbuf-based software-encryption interface.

  • sys/sys/ktls.h L169-211 (6 small edits)

Implementation

Replace backend selection and lifecycle management with direct OCF calls, and adapt transmit encryption to pass TLS mbufs and construct separate output pages when needed.

  • sys/kern/uipc_ktls.c L882-886, L2194-2224, L2239-2244 (+14 small edits)

Convert OCF TLS encryption routines to operate on TLS mbufs, use in-place crypto where possible, and include the trailer in the separate-output iovec.

  • sys/opencrypto/ktls_ocf.c L189-206, L373-390, L510-531 (+22 small edits)

Configuration

Build the OCF KTLS backend into kernels with KERN_TLS and remove the standalone ktls_ocf module from the module build.

  • sys/conf/files L5147
  • sys/modules/Makefile L222 (removed lines), L458 (removed lines)
  • sys/modules/ktls_ocf/Makefile (deleted)

Documentation

Update the KTLS manual and release notes to describe software encryption through crypto(9) and the removal of the loadable OCF backend.

  • UPDATING L3-8
  • share/man/man4/ktls.4 L32, L78-81, L205

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@laffer1
laffer1 merged commit e51a4a6 into master Nov 19, 2026
8 of 12 checks passed
@laffer1
laffer1 deleted the ktls-ocf-builtin branch November 19, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

tests: ktls_test needs ktls_ocf loaded; CBC receive tests expect EPROTONOSUPPORT

2 participants