Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/macos-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,15 @@ jobs:
LDFLAGS="-L${BREW_PREFIX}/lib -L${OPENSSL_PREFIX}/lib" \
./configure --with-rrsync
- name: make
run: make
run: make check-progs
- name: install
run: sudo make install
- name: info
run: rsync --version
- name: check search-only directories
run: |
./runtests.py --rsync-bin="$PWD/rsync" \
search-only-destination search-only-held-dirfd
- name: check
# chown-fake / devices-fake / xattrs / xattrs-hlink now RUN on macOS
# (rsyncfns.py drives xattrs via the `xattr` command), verified on a
Expand Down
10 changes: 10 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
# NEWS for UNRELEASED

## Changes in this version:

### BUG FIXES:
- Preserved known-name operations beneath searchable but unreadable directories
on macOS. Native configuration now proves lookup, creation,
permission-revocation and no-follow behaviour before selecting a traversal
descriptor. Unverified targets fail closed instead of using raceable paths.

# NEWS for rsync 3.5.2 (4 Nov 2026)

## Changes in this version:
Expand Down
35 changes: 21 additions & 14 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,11 @@ closed rather than applied through a raced symlink, but only as a rare backstop:
the common file/dir/FIFO case is secured on every platform via `fchmod` on a held
fd, so no real functionality is lost.

The parent-path resolver is also fail-closed when the kernel cannot provide a
pinned search-only directory descriptor. A pathname fallback would apply to
every leaf operation, including creation, rename and hard-link operations, and
could therefore redirect changes outside the transfer root.

This trade-off applies only to these local-attacker residual classes. Remotely
reachable defects — memory safety, authentication bypass, protocol parsing, input
bounds — are fixed unconditionally on all platforms, never left as a residual.
Expand Down Expand Up @@ -198,30 +203,32 @@ leaf symlink into a file read.

### Path resolution

`secure_relative_open()` resolves a path with a single portable mechanism on
every platform: a per-component walk on a stack of held directory fds. On
Linux, anchors and traversal components use
`O_PATH|O_DIRECTORY|O_NOFOLLOW`; other platforms retain the
`O_RDONLY|O_DIRECTORY` fallback. Descending into a real subdirectory pushes
`secure_relative_open()` resolves a path with a per-component walk on a stack
of held directory fds. Native configuration selects a search-only open flag
only after proving known-name lookup, creation, permission revocation and
no-follow behaviour. Linux and FreeBSD use `O_PATH`; current macOS uses
`O_SEARCH`. Cross-built Linux also uses `O_PATH`; unverified cross targets stay
fail-closed. Other platforms use `O_RDONLY|O_DIRECTORY`. Descending into a real
subdirectory pushes
its fd, a `..` pops back to the already-held parent (a pop at the anchor is
refused), and an in-tree directory symlink is followed by reading its target
and walking that off the same stack (absolute targets refused, symlink hops
bounded). A final directory endpoint is reopened with the caller's requested
flags. Thus `secure_opendir()` still receives a readable fd, while known-name
operations beneath a searchable but unreadable directory do not require
permission to list it.
flags. Thus `secure_opendir()` still receives a readable fd, while supported
kernels allow known-name operations beneath a searchable but unreadable
directory without permission to list it.

Because every component is opened relative to a *pinned* fd under `O_NOFOLLOW`,
and `..` is resolved by the held-fd stack rather than by the kernel, the walk is
race-free by construction: no rename or symlink swap of any path name can redirect
resolution outside the anchor subtree, and no kernel "beneath" primitive
(`openat2(RESOLVE_BENEATH)` / `openat(O_RESOLVE_BENEATH)`) is required. The
confinement is therefore uniform across Linux, the BSDs, macOS and
Solaris/illumos, on old and new kernels alike, with nothing to probe or fall back
to at runtime (and so no `openat2`/seccomp interaction to worry about in sandboxed
environments). Cygwin is the exception, because its directory descriptors and
symlink emulation do not give the held-fd walk the same inode pinning — see the
Cygwin residual below.
confinement remains descriptor-based on every platform. A kernel without a
working search-only descriptor, including the tested NetBSD and OpenBSD
releases, cannot traverse a directory which denies read permission. Rsync fails
closed there rather than falling back to a raceable pathname. This limitation is
reported as the `search-only-dirs` capability. Cygwin remains an exception to
the descriptor-pinning model; see the Cygwin residual below.

Legitimate *in-tree* directory symlinks are followed, so `--keep-dirlinks` /
`--copy-links` and a symlinked module path keep working. A relative alternate-dest
Expand Down
169 changes: 169 additions & 0 deletions configure.ac
Original file line number Diff line number Diff line change
Expand Up @@ -992,6 +992,175 @@ if test x"$rsync_cv_HAVE_DIRFD" = x"yes"; then
AC_DEFINE([HAVE_DIRFD], 1, [Define to 1 if you have a working dirfd() (function or macro).])
fi

dnl The confined resolver needs a directory descriptor which can be opened with
dnl search permission alone and which still rechecks search permission when it
dnl is used. A defined O_SEARCH is not sufficient: NetBSD 11 discards it, and
dnl POSIX permits an O_SEARCH descriptor to bypass later permission checks.
AC_CACHE_CHECK([for race-safe search-only directory descriptors],
[rsync_cv_search_only_dirfd_flag], [
rm -f conftest.search-only
AC_RUN_IFELSE([AC_LANG_SOURCE([[
#define _GNU_SOURCE 1
#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#ifndef O_CLOEXEC
#define O_CLOEXEC 0
#endif
static int check_flag(int flag)
{
struct stat expected, observed;
char base[] = "/tmp/rsync-search-only.XXXXXX";
int root = -1, control = -1, cwd = -1, fd = -1, child = -1;
int dropped = 0, result = 1;
gid_t saved_gid = getegid();
if (!mkdtemp(base))
goto out;
root = open(base, O_RDONLY | O_DIRECTORY | O_CLOEXEC);
cwd = open(".", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
if (root < 0 || cwd < 0 || mkdirat(root, "dir", 0700) < 0
|| symlinkat("dir", root, "link") < 0)
goto out;
control = openat(root, "dir", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
if (control < 0 || fstat(control, &expected) < 0)
goto out;
child = openat(control, "known", O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, 0600);
if (child < 0 || write(child, "x", 1) != 1)
goto out;
if (geteuid() == 0) {
if (fchown(root, 65534, 65534) < 0
|| fchown(control, 65534, 65534) < 0
|| fchown(child, 65534, 65534) < 0)
goto out;
}
if (close(child) < 0)
goto out;
child = -1;
if (geteuid() == 0) {
if (setegid(65534) < 0)
goto out;
if (seteuid(65534) < 0) {
setegid(saved_gid);
goto out;
}
dropped = 1;
}
if (fchmod(control, 0100) < 0)
goto out;
fd = openat(root, "dir", flag | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
if (fd < 0 || fstat(fd, &observed) < 0
|| expected.st_dev != observed.st_dev || expected.st_ino != observed.st_ino)
goto out;
child = openat(fd, "known", O_RDONLY | O_CLOEXEC);
if (child < 0 || close(child) < 0)
goto out;
child = -1;
if (fchmod(control, 0300) < 0)
goto out;
child = openat(fd, "new", O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, 0600);
if (child < 0 || close(child) < 0 || unlinkat(fd, "new", 0) < 0)
goto out;
child = -1;
if (fchmod(control, 0000) < 0)
goto out;
child = openat(fd, "known", O_RDONLY | O_CLOEXEC);
if (child >= 0 || (errno != EACCES && errno != EPERM))
goto out;
if (fchdir(fd) == 0) {
fchdir(cwd);
goto out;
}
if (errno != EACCES && errno != EPERM)
goto out;
if (fchmod(control, 0700) < 0)
goto out;
child = openat(root, "link", flag | O_DIRECTORY | O_CLOEXEC);
if (child < 0 || close(child) < 0)
goto out;
child = -1;
child = openat(root, "link", flag | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
if (child >= 0)
goto out;
result = 0;
out:
if (dropped && (seteuid(0) < 0 || setegid(saved_gid) < 0))
result = 1;
if (child >= 0 && close(child) < 0)
result = 1;
if (fd >= 0 && close(fd) < 0)
result = 1;
if (control >= 0) {
if (fchmod(control, 0700) < 0)
result = 1;
if (unlinkat(control, "new", 0) < 0 && errno != ENOENT)
result = 1;
if (unlinkat(control, "known", 0) < 0 && errno != ENOENT)
result = 1;
if (close(control) < 0)
result = 1;
}
if (root >= 0) {
if (unlinkat(root, "link", 0) < 0 && errno != ENOENT)
result = 1;
if (unlinkat(root, "dir", AT_REMOVEDIR) < 0 && errno != ENOENT)
result = 1;
if (close(root) < 0)
result = 1;
}
if (cwd >= 0 && close(cwd) < 0)
result = 1;
if (rmdir(base) < 0 && errno != ENOENT)
result = 1;
return result;
}
int main(void)
{
const char *name = NULL;
#ifdef O_PATH
if (check_flag(O_PATH) == 0)
name = "O_PATH";
#endif
#ifdef O_SEARCH
if (!name && check_flag(O_SEARCH) == 0)
name = "O_SEARCH";
#endif
if (name) {
FILE *out = fopen("conftest.search-only", "w");
if (!out || fprintf(out, "%s\n", name) < 0 || fclose(out) < 0)
return 1;
return 0;
}
return 1;
}
]])],
[rsync_cv_search_only_dirfd_flag=`cat conftest.search-only`],
[rsync_cv_search_only_dirfd_flag=no],
[case "$host_os" in
linux*|android*)
AC_LINK_IFELSE([AC_LANG_PROGRAM([[
#define _GNU_SOURCE 1
#include <fcntl.h>
]], [[return openat(AT_FDCWD, ".", O_PATH | O_DIRECTORY | O_NOFOLLOW) < -1;]])],
[rsync_cv_search_only_dirfd_flag=O_PATH],
[rsync_cv_search_only_dirfd_flag=no])
;;
*) rsync_cv_search_only_dirfd_flag=no ;;
esac])
rm -f conftest.search-only
])
if test x"$rsync_cv_search_only_dirfd_flag" != x"no"; then
AC_DEFINE_UNQUOTED([SEARCH_ONLY_DIRFD_FLAG], [$rsync_cv_search_only_dirfd_flag],
[Open flag for race-safe search-only directory descriptors.])
fi

dnl cygwin iconv.h defines iconv_open as libiconv_open
if test x"$ac_cv_func_iconv_open" != x"yes"; then
AC_CHECK_FUNC(libiconv_open, [ac_cv_func_iconv_open=yes; AC_DEFINE(HAVE_ICONV_OPEN, 1)])
Expand Down
11 changes: 5 additions & 6 deletions syscall.c
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,12 @@ extern char curr_dir[MAXPATHLEN]; /* defined below; fwd-declared for the seed */
extern int operator_path_resolve; /* defined below; fwd-declared for the exclude check */
extern int filesfrom_owner_walk_override; /* defined below; used by files-from implied dirs */

/* A directory fd used only for pathname traversal, fchdir(), or as *at()
* authority does not need read permission on Linux. Keep the portable
* O_RDONLY fallback for systems without O_PATH. */
/* A traversal descriptor does not need directory read permission when
* configure found a flag which preserves later search-permission checks. */
static int directory_traverse_flags(void)
{
#if defined O_PATH && defined O_DIRECTORY
return O_PATH | O_DIRECTORY;
#if defined SEARCH_ONLY_DIRFD_FLAG && defined O_DIRECTORY
return SEARCH_ONLY_DIRFD_FLAG | O_DIRECTORY;
#elif defined O_DIRECTORY
return O_RDONLY | O_DIRECTORY;
#else
Expand Down Expand Up @@ -748,7 +747,7 @@ int open_no_attacker_symlinks(const char *path, int flags, mode_t mode)

/* Open a directory for traversal or as *at()/fchdir() authority. Unlike an
* O_RDONLY directory endpoint, this accepts a searchable but unreadable
* directory on Linux. */
* directory when the kernel provides a safe search-only descriptor. */
int open_no_attacker_symlinks_dirfd(const char *path)
{
return ona_open(path, directory_traverse_flags(), 0, NULL, 0);
Expand Down
17 changes: 12 additions & 5 deletions testsuite/search-only-destination_test.py
Original file line number Diff line number Diff line change
@@ -1,24 +1,27 @@
#!/usr/bin/env python3
"""The receiver must traverse a searchable but unreadable destination parent.
Android exposes /sdcard through such a path, so the race-safe destination walk
must use directory descriptors that require search permission only.
Android exposes /sdcard through such a path. Kernels which provide a race-safe
search-only directory descriptor must therefore support this destination walk.
"""

import json
import os
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path

from rsyncfns import SCRATCHDIR, rmtree, rsync_argv, test_fail, test_skipped
from rsyncfns import SCRATCHDIR, rmtree, rsync_argv, run_rsync, test_fail, test_skipped

if not sys.platform.startswith('linux'):
test_skipped('search-only-destination is Linux-specific')
version = json.loads(run_rsync('-VV', capture_output=True).stdout)
search_only_dirs = version['capabilities']['search_only_dirs']

launcher = []
if os.geteuid() == 0:
if not sys.platform.startswith('linux'):
test_skipped('requires a non-root test process on this platform')
setpriv = shutil.which('setpriv')
if setpriv is None:
test_skipped('setpriv is unavailable for the root-run testsuite')
Expand Down Expand Up @@ -61,6 +64,10 @@
stderr=subprocess.PIPE,
text=True,
)
if not search_only_dirs:
if proc.returncode == 0 or (dest / 'probe').exists():
test_fail('unsupported search-only traversal did not fail closed')
test_skipped('kernel has no race-safe search-only directory descriptor')
finally:
parent.chmod(0o755)
copied = (dest / 'probe').read_text() if (dest / 'probe').is_file() else None
Expand Down
26 changes: 20 additions & 6 deletions testsuite/search-only-held-dirfd_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
"""Known-name operations must not require permission to list parent dirs.
The confined resolver holds directory descriptors to prevent symlink races.
On Linux, those traversal and *at() anchor descriptors can use O_PATH: opening
a known file beneath a searchable directory, or creating one beneath a
writable/searchable directory, does not require directory read permission.
Supported kernels provide a descriptor which can open a known file beneath a
searchable directory or create one beneath a writable/searchable directory
without requiring permission to list that directory.
"""

import json
import os
import shutil
import subprocess
Expand All @@ -15,14 +16,16 @@
from pathlib import Path

from rsyncfns import (
SCRATCHDIR, forced_protocol, rmtree, rsync_argv, test_fail, test_skipped,
SCRATCHDIR, forced_protocol, rmtree, rsync_argv, run_rsync, test_fail, test_skipped,
)

if not sys.platform.startswith('linux'):
test_skipped('search-only held-dirfd coverage is Linux-specific')
version = json.loads(run_rsync('-VV', capture_output=True).stdout)
search_only_dirs = version['capabilities']['search_only_dirs']

launcher = []
if os.geteuid() == 0:
if not sys.platform.startswith('linux'):
test_skipped('requires a non-root test process on this platform')
setpriv = shutil.which('setpriv')
if setpriv is None:
test_skipped('setpriv is unavailable for the root-run testsuite')
Expand Down Expand Up @@ -100,6 +103,17 @@ def permission_probe(path, flag, expected, label):
permission_probe(nested_parent, '-w', 0, 'nested write-search-only mode')
permission_probe(nested_parent, '-x', 0, 'nested write-search-only mode')

if not search_only_dirs:
unsupported = subprocess.run(
launcher + rsync_argv('-t', str(incoming), f'{write_only_dest}/'),
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
if unsupported.returncode == 0 or (write_only_dest / 'incoming').exists():
test_fail('unsupported search-only traversal did not fail closed')
test_skipped('kernel has no race-safe search-only directory descriptor')

# Keep received implied dirs usable on systems without a safe fchmodat2.
# The source remains mode 0111, so sender traversal coverage is unchanged.
exact = subprocess.run(
Expand Down
Loading
Loading