README: update to describe and strongly recommend new APIs

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>

README.md

@@ -2,31 +2,24 @@
 
 [![Build Status](https://github.com/cyphar/filepath-securejoin/actions/workflows/ci.yml/badge.svg)](https://github.com/cyphar/filepath-securejoin/actions/workflows/ci.yml)
 
-An implementation of `SecureJoin`, a [candidate for inclusion in the Go
-standard library][go#20126]. The purpose of this function is to be a "secure"
-alternative to `filepath.Join`, and in particular it provides certain
-guarantees that are not provided by `filepath.Join`.
-
-> **NOTE**: This code is *only* safe if you are not at risk of other processes
-> modifying path components after you've used `SecureJoin`. If it is possible
-> for a malicious process to modify path components of the resolved path, then
-> you will be vulnerable to some fairly trivial TOCTOU race conditions. [There
-> are some Linux kernel patches I'm working on which might allow for a better
-> solution.][lwn-obeneath]
->
-> In addition, with a slightly modified API it might be possible to use
-> `O_PATH` and verify that the opened path is actually the resolved one -- but
-> I have not done that yet. I might add it in the future as a helper function
-> to help users verify the path (we can't just return `/proc/self/fd/<foo>`
-> because that doesn't always work transparently for all users).
-
-This is the function prototype:
+### Old API ###
 
-```go
-func SecureJoin(root, unsafePath string) (string, error)
-```
+This library was originally just an implementation of `SecureJoin` which was
+[intended to be included in the Go standard library][go#20126] as a safer
+`filepath.Join` that would restrict the path lookup to be inside a root
+directory.
+
+The implementation was based on code that existed in several container
+runtimes. Unfortunately, this API is **fundamentally unsafe** against attackers
+that can modify path components after `SecureJoin` returns and before the
+caller uses the path, allowing for some fairly trivial TOCTOU attacks.
+
+`SecureJoin` (and `SecureJoinVFS`) are still provided by this library to
+support legacy users, but new users are strongly suggested to avoid using
+`SecureJoin` and instead use the [new api](#new-api) or switch to
+[libpathrs][libpathrs].
 
-This library **guarantees** the following:
+With the above limitations in mind, this library guarantees the following:
 
 * If no error is set, the resulting string **must** be a child path of
   `root` and will not contain any symlink path components (they will all be
@@ -47,7 +40,7 @@ This library **guarantees** the following:
 A (trivial) implementation of this function on GNU/Linux systems could be done
 with the following (note that this requires root privileges and is far more
 opaque than the implementation in this library, and also requires that
-`readlink` is inside the `root` path):
+`readlink` is inside the `root` path and is trustworthy):
 
 ```go
 package securejoin
@@ -70,9 +63,105 @@ func SecureJoin(root, unsafePath string) (string, error) {
 }
 ```
 
-[lwn-obeneath]: https://lwn.net/Articles/767547/
+[libpathrs]: https://github.com/openSUSE/libpathrs
 [go#20126]: https://github.com/golang/go/issues/20126
 
+### New API ###
+
+While we recommend users switch to [libpathrs][libpathrs] as soon as it has a
+stable release, some methods implemented by libpathrs have been ported to this
+library to ease the transition. These APIs are only supported on Linux.
+
+These APIs are implemented such that `filepath-securejoin` will
+opportunistically use certain newer kernel APIs that make these operations far
+more secure. In particular:
+
+* All of the lookup operations will use [`openat2`][openat2.2] on new enough
+  kernels (Linux 5.6 or later) to restrict lookups through magic-links and
+  bind-mounts (for certain operations) and to make use of `RESOLVE_IN_ROOT` to
+  efficiently resolve symlinks within a rootfs.
+
+* The APIs provide hardening against a malicious `/proc` mount to either detect
+  or avoid being tricked by a `/proc` that is not legitimate. This is done
+  using [`openat2`][openat2.2] for all users, and privileged users will also be
+  further protected by using [`fsopen`][fsopen.2] and [`open_tree`][open_tree.2]
+  (Linux 4.18 or later).
+
+[openat2.2]: https://www.man7.org/linux/man-pages/man2/openat2.2.html
+[fsopen.2]: https://github.com/brauner/man-pages-md/blob/main/fsopen.md
+[open_tree.2]: https://github.com/brauner/man-pages-md/blob/main/open_tree.md
+
+#### `OpenInRoot` ####
+
+```go
+func OpenInRoot(root, unsafePath string) (*os.File, error)
+func OpenatInRoot(root *os.File, unsafePath string) (*os.File, error)
+func Reopen(handle *os.File, flags int) (*os.File, error)
+```
+
+`OpenInRoot` is a much safer version of
+
+```go
+path, err := securejoin.SecureJoin(root, unsafePath)
+file, err := os.OpenFile(path, unix.O_PATH|unix.O_CLOEXEC)
+```
+
+that protects against various race attacks that could lead to serious security
+issues, depending on the application. Note that the returned `*os.File` is an
+`O_PATH` file descriptor, which is quite restricted. Callers will probably need
+to use `Reopen` to get a more usable handle (this split is done to provide
+useful features like PTY spawning and to avoid users accidentally opening bad
+inodes that could cause a DoS).
+
+Callers need to be careful in how they use the returned `*os.File`. Usually it
+is only safe to operate on the handle directly, and it is very easy to create a
+security issue. [libpathrs][libpathrs] provides far more helpers to make using
+these handles safer -- there is currently no plan to port them to
+`filepath-securejoin`.
+
+`OpenatInRoot` is like `OpenInRoot` except that the root is provided using an
+`*os.File`. This allows you to ensure that multiple `OpenatInRoot` (or
+`MkdirAllHandle`) calls are operating on the same rootfs.
+
+> **NOTE**: Unlike `SecureJoin`, `OpenInRoot` will error out as soon as it hits
+> a dangling symlink or non-existent path. This is in contrast to `SecureJoin`
+> which treated non-existent components as though they were real directories,
+> and would allow for partial resolution of dangling symlinks. These behaviours
+> are at odds with how Linux treats non-existent paths and dangling symlinks,
+> and so these are no longer allowed.
+
+#### `MkdirAll` ####
+
+```go
+func MkdirAll(root, unsafePath string, mode int) error
+func MkdirAllHandle(root *os.File, unsafePath string, mode int) (*os.File, error)
+```
+
+`MkdirAll` is a much safer version of
+
+```go
+path, err := securejoin.SecureJoin(root, unsafePath)
+err = os.MkdirAll(path, mode)
+```
+
+that protects against the same kinds of races that `OpenInRoot` protects
+against.
+
+`MkdirAllHandle` is like `MkdirAll` except that the root is provided using an
+`*os.File` (the reason for this is the same as with `OpenatInRoot`) and an
+`*os.File` of the final created directory is returned (this directory is
+guaranteed to be effectively identical to the directory created by
+`MkdirAllHandle`, which is not possible to ensure by just using `OpenatInRoot`
+after `MkdirAll`).
+
+> **NOTE**: Unlike `SecureJoin`, `MkdirAll` will error out as soon as it hits
+> a dangling symlink or non-existent path. This is in contrast to `SecureJoin`
+> which treated non-existent components as though they were real directories,
+> and would allow for partial resolution of dangling symlinks. These behaviours
+> are at odds with how Linux treats non-existent paths and dangling symlinks,
+> and so these are no longer allowed. This means that `MkdirAll` will not
+> create non-existent directories referenced by a dangling symlink.
+
 ### License ###
 
 The license of this project is the same as Go, which is a BSD 3-clause license