man/man2/openat2.2: HISTORY: Include epilogue about FreeBSD

While RESOLVE_BENEATH was based on FreeBSD's O_BENEATH, there was a
well-known safety issue in O_BENEATH that we explicitly avoided
replicating -- FreeBSD would only verify whether the lookup escaped the
dirfd *at the end of the path lookup*.

This meant that even with O_BENEATH, an attacker could gain information
about the structure of the filesystem outside of the dirfd through
timing attacks or other side-channels.

Once Linux had RESOLVE_BENEATH, FreeBSD implemented O_RESOLVE_BENEATH to
mimic the same behaviour[1] and eventually removed O_BENEATH entirely
from their system[2].  It seems prudent to provide this epilogue in the
HISTORY section of the openat2(2) man page (the FreeBSD man page does
for open(2) not reference this historical connection with Linux at all,
as far as I can tell).

Link: [1] <https://reviews.freebsd.org/D25886>
Link: [2] <https://reviews.freebsd.org/D28907>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250721-openat2-history-v1-1-994936dd224a@cyphar.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/openat2.2 b/man/man2/openat2.2
index e7d4009200492c9cfc93b02b41b8fca2f52b0c28..9d0b587779d24c5516dc9dd04f198b80add1a005 100644 (file)
--- a/man/man2/openat2.2
+++ b/man/man2/openat2.2
@@ -478,7 +478,20 @@ Linux 5.6.
 The semantics of
 .B RESOLVE_BENEATH
 were modeled after FreeBSD's
+.BR O_BENEATH ,
+but avoided a well-known correctness bug in FreeBSD's implementation that
+rendered it effectively insecure.
+Later, FreeBSD 13 introduced
+.B O_RESOLVE_BENEATH
+to replace the insecure
 .BR O_BENEATH .
+.\" https://reviews.freebsd.org/D25886
+.\" https://reviews.freebsd.org/D28907
+FreeBSD's
+.B O_RESOLVE_BENEATH
+semantics are based on Linux's
+.B RESOLVE_BENEATH
+and the two are now functionally equivalent.
 .SH NOTES
 .SS Extensibility
 In order to allow for future extensibility,