Explicit pointer provenance APIs for CHERI

Brooks Davis <[email protected]> Fri, 19 Jun 2026 14:19:22 +0000
Newsgroups gmane.os.freebsd.architechture
Message-ID <[email protected]>
As part of our effort to bring CHERI memory safety to FreeBSD, I have
posted a stack of reviews in Phabricator which add APIs to explicitly
indicate that pointer provenance should be preserved or stripped when
copying memory.  Under CHERI targets, the non-preserving APIs explicitly
strip validity tags from CHERI capabilities.  This limits the
opportunity for inappropriate flow of capabilities, primarily between
user space and kernel space.

It turns out that the vast majority of copies between user and kernel
are between objects that should not contain pointers.  Thus we default
most APIs (e.g., copyin/copyout) to not preserving capabilities.  We've
added *ptr variants (e.g., copyinptr) which do preserve provenance.
We've also added fueptr and suptr to supplement existing *word APIs.
The exception is memcpy (as well as bcopy and memmove) where the
compiler may insert calls on its own which might or might not need to
copy pointers.  There we have implemented memcpy_data(), etc. which
strip provenance.  We primarily use them in uio and in page copying
routines in the pmap layer.

A note on names: In CheriBSD we originally named copyinptr copyincap and
memcpy_data memcpynocap.  The switch from "cap" to "ptr" is motivated by
a view that CHERI capabilities are just pointers with extra properties.
Likewise "_data" indicates that we're copying data vs pointers.  It's
obviously possible to pick other names, but I think these are reasonably
well motivated.

These are all kernel-only APIs today.  The memcpy_data interface might
eventually make sense in user space, but is probably best done in
conjunction with standards bodies.

I've posted a stack of reviews with the two key ones being:
 - memcpy_data: https://reviews.freebsd.org/D57662
 - copyinptr, ...: https://reviews.freebsd.org/D57663

Feedback welcome

-- Brooks