Lib.rs

libpathrs

This library implements a set of C-friendly APIs (written in Rust) to make path resolution within a potentially-untrusted directory safe on GNU/Linux. There are countless examples of security vulnerabilities caused by bad handling of paths (symlinks make the issue significantly worse).

Example

Root and Handle API

Here is a toy example of using this library to open a path (/etc/passwd) inside a root filesystem (/path/to/root) safely. More detailed examples can be found in examples/ and tests/.

#include <pathrs.h>

int get_my_fd(void)
{
	const char *root_path = "/path/to/root";
	const char *unsafe_path = "/etc/passwd";

	int liberr = 0;
	int root = -EBADF,
		handle = -EBADF,
		fd = -EBADF;

	root = pathrs_root_open(root_path);
	if (root < 0) {
		liberr = root;
		goto err;
	}

	handle = pathrs_resolve(root, unsafe_path);
	if (handle < 0) {
		liberr = handle;
		goto err;
	}

	fd = pathrs_reopen(handle, O_RDONLY);
	if (fd < 0) {
		liberr = fd;
		goto err;
	}

err:
	if (liberr < 0) {
		pathrs_error_t *error = pathrs_errorinfo(liberr);
		fprintf(stderr, "Uh-oh: %s (errno=%d)\n", error->description, error->saved_errno);
		pathrs_errorinfo_free(error);
	}
	close(root);
	close(handle);
	return fd;
}

Safe procfs API

libpathrs also provides a set of primitives to safely interact with procfs. This is very important for some programs (such as container runtimes), because /proc has several key system administration purposes that make it different to other filesystems. It particular, /proc is used:

1. As a mechanism for doing certain filesystem operations through /proc/self/fd/... (and other similar magic-links) that cannot be done by other means.
2. As a source of true information about processes and the general system (such as by looking /proc/$pid/status).
3. As an administrative tool for managing processes (such as setting LSM labels like /proc/self/attr/apparmor/exec).

These operations have stronger requirements than regular filesystems. For (1) we need to open the magic-link for real (magic-links are symlinks that are not resolved lexically, they are in-kernel objects that warp you to other files without doing a regular path lookup) which much harder to do safely (even with openat2). For (2) and (3) we have the requirement that we need to open a specific file, not just any file within /proc (if there are overmounts or symlinks) which is not the case pathrs_resolve(). As a result, it is necessary to take far more care when doing operations of /proc and libpathrs provides very useful helper to do this. Failure to do so can lead to security issues such as those in CVE-2019-16884 and CVE-2019-19921.

In addition, with the new mount API (fsopen(2) and open_tree(2) in particular, added in Linux 5.2), it is possible to get a totally private procfs handle that can be used without worrying about racing mount operations. libpathrs will try to use this if it can (this usually requires root).

Here are a few examples of practical things you might want to do with libpathrs's procfs API:

/*
 * Safely get an fd to /proc/self/exe. This is something runc does to re-exec
 * itself during the container setup process.
 */
int get_self_exe(void)
{
    /* This follows the trailing magic-link! */
    int fd = pathrs_proc_open(PATHRS_PROC_SELF, "exe", O_PATH);
    if (fd < 0) {
        pathrs_error_t *error = pathrs_errorinfo(fd);
        /* ... print the error ... */
        pathrs_errorinfo_free(error);
        return -1;
    }
    return fd;
}

/*
 * Safely set the AppArmor exec label for the current process. This is
 * something runc does while configuring the container process.
 */
int write_apparmor_label(const char *label)
{
    int fd, err;

    /*
     * Note the usage of O_NOFOLLOW here. You should use O_NOFOLLOW except in
     * the very rare case where you need to open a magic-link or you really
     * want to follow a trailing symlink.
     */
    fd = pathrs_proc_open(PATHRS_PROC_SELF, "attr/apparmor/exec",
                          O_WRONLY|O_NOFOLLOW);
    if (fd < 0) {
        pathrs_error_t *error = pathrs_errorinfo(fd);
        /* ... print the error ... */
        pathrs_errorinfo_free(error);
        return -1;
    }

    err = write(fd, label, strlen(label));
    close(fd);
    return err;
}

/*
 * Sometimes you need to get the "real" path of a file descriptor. This path
 * MUST NOT be used for actual filesystem operations, because it's possible for
 * an attacker to move the file or change one of the path components to a
 * symlink, which could lead to you operating on files you didn't expect
 * (including host files if you're a container runtime).
 *
 * In most cases, this kind of function would be used for diagnostic purposes
 * (such as in error messages, to provide context about what file the error is
 * in relation to).
 */
char *get_unsafe_path(int fd)
{
    char *fdpath;

    if (asprintf(&fdpath, "fd/%d", fd) < 0)
        return NULL;

    int linkbuf_size = 128;
    char *linkbuf = malloc(size);
    if (!linkbuf)
        goto err;
    for (;;) {
        int len = pathrs_proc_readlink(PATHRS_PROC_THREAD_SELF,
                                       fdpath, linkbuf, linkbuf_size);
        if (len < 0) {
            pathrs_error_t *error = pathrs_errorinfo(fd);
            /* ... print the error ... */
            pathrs_errorinfo_free(error);
            goto err;
        }

        if (len <= linkbuf_size)
            break;

        linkbuf_size = len;
        linkbuf = realloc(linkbuf, linkbuf_size);
        if (!linkbuf)
            goto err;
    }

    free(fdpath);
    return linkbuf;

err:
    free(fdpath);
    free(linkbuf);
    return NULL;
}

Kernel Support

libpathrs is designed to only work with Linux, as it uses several Linux-only APIs.

libpathrs was designed alongside openat2(2) (available since Linux 5.6) and dynamically tries to use the latest kernel features to provide the maximum possible protection against racing attackers. However, it also provides support for older kernel versions (in theory up to Linux 2.6.39 but we do not currently test this) by emulating newer kernel features in userspace.

However, we strongly recommend you use at least Linux 5.8 to get a reasonable amount of protection against various attacks, and ideally at least Linux 6.8 to make use of all of the protections we have implemented. See the following table for what kernel features we optionally support and what they are used for.

For more information about the work behind openat2(2), you can read the following LWN articles (note that the merged version of openat2(2) is different to the version described by LWN):

• New AT_ flags for restricting pathname lookup
• Restricting path name lookup with openat2()

License

libpathrs is licensed under the GNU LGPLv3 (or any later version).

libpathrs: safe path resolution on Linux
Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
Copyright (C) 2019-2024 SUSE LLC

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along
with this program. If not, see <https://www.gnu.org/licenses/>.

The language-specific bindings (the code in contrib/bindings/ and go-pathrs/) are licensed under the Apache-2.0 license, to allow for wider usage of libpathrs from languages where language libraries are not dynamically linked.

NOTE: If you compile libpathrs.so into your binary statically, you still need to abide by the LGPLv3 license. In practice this means at least providing the object files necessary to allow someone to recompile your program using a modified libpathrs. See the LGPLv3 license for more details.

libpathrs: safe path resolution on Linux
Copyright (C) 2019-2024 Aleksa Sarai <cyphar@cyphar.com>
Copyright (C) 2019-2024 SUSE LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.