Skip to content

Commit d1a2844

Browse files
authored
syscall: qualify search-only directory descriptors (#1155)
* syscall: qualify search-only directory descriptors * ci: build test helpers on macOS
1 parent ea64520 commit d1a2844

8 files changed

Lines changed: 247 additions & 32 deletions

File tree

‎.github/workflows/macos-build.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,15 @@ jobs:
3939
LDFLAGS="-L${BREW_PREFIX}/lib -L${OPENSSL_PREFIX}/lib" \
4040
./configure --with-rrsync
4141
- name: make
42-
run: make
42+
run: make check-progs
4343
- name: install
4444
run: sudo make install
4545
- name: info
4646
run: rsync --version
47+
- name: check search-only directories
48+
run: |
49+
./runtests.py --rsync-bin="$PWD/rsync" \
50+
search-only-destination search-only-held-dirfd
4751
- name: check
4852
# chown-fake / devices-fake / xattrs / xattrs-hlink now RUN on macOS
4953
# (rsyncfns.py drives xattrs via the `xattr` command), verified on a

‎NEWS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
1+
# NEWS for UNRELEASED
2+
3+
## Changes in this version:
4+
5+
### BUG FIXES:
6+
- Preserved known-name operations beneath searchable but unreadable directories
7+
on macOS. Native configuration now proves lookup, creation,
8+
permission-revocation and no-follow behaviour before selecting a traversal
9+
descriptor. Unverified targets fail closed instead of using raceable paths.
10+
111
# NEWS for rsync 3.5.2 (4 Nov 2026)
212

313
## Changes in this version:

‎SECURITY.md‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,11 @@ closed rather than applied through a raced symlink, but only as a rare backstop:
5555
the common file/dir/FIFO case is secured on every platform via `fchmod` on a held
5656
fd, so no real functionality is lost.
5757

58+
The parent-path resolver is also fail-closed when the kernel cannot provide a
59+
pinned search-only directory descriptor. A pathname fallback would apply to
60+
every leaf operation, including creation, rename and hard-link operations, and
61+
could therefore redirect changes outside the transfer root.
62+
5863
This trade-off applies only to these local-attacker residual classes. Remotely
5964
reachable defects — memory safety, authentication bypass, protocol parsing, input
6065
bounds — are fixed unconditionally on all platforms, never left as a residual.
@@ -198,30 +203,32 @@ leaf symlink into a file read.
198203

199204
### Path resolution
200205

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

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

226233
Legitimate *in-tree* directory symlinks are followed, so `--keep-dirlinks` /
227234
`--copy-links` and a symlinked module path keep working. A relative alternate-dest

‎configure.ac‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -992,6 +992,175 @@ if test x"$rsync_cv_HAVE_DIRFD" = x"yes"; then
992992
AC_DEFINE([HAVE_DIRFD], 1, [Define to 1 if you have a working dirfd() (function or macro).])
993993
fi
994994

995+
dnl The confined resolver needs a directory descriptor which can be opened with
996+
dnl search permission alone and which still rechecks search permission when it
997+
dnl is used. A defined O_SEARCH is not sufficient: NetBSD 11 discards it, and
998+
dnl POSIX permits an O_SEARCH descriptor to bypass later permission checks.
999+
AC_CACHE_CHECK([for race-safe search-only directory descriptors],
1000+
[rsync_cv_search_only_dirfd_flag], [
1001+
rm -f conftest.search-only
1002+
AC_RUN_IFELSE([AC_LANG_SOURCE([[
1003+
#define _GNU_SOURCE 1
1004+
#include <sys/types.h>
1005+
#include <sys/stat.h>
1006+
#include <errno.h>
1007+
#include <fcntl.h>
1008+
#include <stdio.h>
1009+
#include <stdlib.h>
1010+
#include <unistd.h>
1011+
1012+
#ifndef O_CLOEXEC
1013+
#define O_CLOEXEC 0
1014+
#endif
1015+
1016+
static int check_flag(int flag)
1017+
{
1018+
struct stat expected, observed;
1019+
char base[] = "/tmp/rsync-search-only.XXXXXX";
1020+
int root = -1, control = -1, cwd = -1, fd = -1, child = -1;
1021+
int dropped = 0, result = 1;
1022+
gid_t saved_gid = getegid();
1023+
1024+
if (!mkdtemp(base))
1025+
goto out;
1026+
root = open(base, O_RDONLY | O_DIRECTORY | O_CLOEXEC);
1027+
cwd = open(".", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
1028+
if (root < 0 || cwd < 0 || mkdirat(root, "dir", 0700) < 0
1029+
|| symlinkat("dir", root, "link") < 0)
1030+
goto out;
1031+
control = openat(root, "dir", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
1032+
if (control < 0 || fstat(control, &expected) < 0)
1033+
goto out;
1034+
child = openat(control, "known", O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, 0600);
1035+
if (child < 0 || write(child, "x", 1) != 1)
1036+
goto out;
1037+
if (geteuid() == 0) {
1038+
if (fchown(root, 65534, 65534) < 0
1039+
|| fchown(control, 65534, 65534) < 0
1040+
|| fchown(child, 65534, 65534) < 0)
1041+
goto out;
1042+
}
1043+
if (close(child) < 0)
1044+
goto out;
1045+
child = -1;
1046+
if (geteuid() == 0) {
1047+
if (setegid(65534) < 0)
1048+
goto out;
1049+
if (seteuid(65534) < 0) {
1050+
setegid(saved_gid);
1051+
goto out;
1052+
}
1053+
dropped = 1;
1054+
}
1055+
if (fchmod(control, 0100) < 0)
1056+
goto out;
1057+
fd = openat(root, "dir", flag | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
1058+
if (fd < 0 || fstat(fd, &observed) < 0
1059+
|| expected.st_dev != observed.st_dev || expected.st_ino != observed.st_ino)
1060+
goto out;
1061+
child = openat(fd, "known", O_RDONLY | O_CLOEXEC);
1062+
if (child < 0 || close(child) < 0)
1063+
goto out;
1064+
child = -1;
1065+
if (fchmod(control, 0300) < 0)
1066+
goto out;
1067+
child = openat(fd, "new", O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, 0600);
1068+
if (child < 0 || close(child) < 0 || unlinkat(fd, "new", 0) < 0)
1069+
goto out;
1070+
child = -1;
1071+
if (fchmod(control, 0000) < 0)
1072+
goto out;
1073+
child = openat(fd, "known", O_RDONLY | O_CLOEXEC);
1074+
if (child >= 0 || (errno != EACCES && errno != EPERM))
1075+
goto out;
1076+
if (fchdir(fd) == 0) {
1077+
fchdir(cwd);
1078+
goto out;
1079+
}
1080+
if (errno != EACCES && errno != EPERM)
1081+
goto out;
1082+
if (fchmod(control, 0700) < 0)
1083+
goto out;
1084+
child = openat(root, "link", flag | O_DIRECTORY | O_CLOEXEC);
1085+
if (child < 0 || close(child) < 0)
1086+
goto out;
1087+
child = -1;
1088+
child = openat(root, "link", flag | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
1089+
if (child >= 0)
1090+
goto out;
1091+
result = 0;
1092+
out:
1093+
if (dropped && (seteuid(0) < 0 || setegid(saved_gid) < 0))
1094+
result = 1;
1095+
if (child >= 0 && close(child) < 0)
1096+
result = 1;
1097+
if (fd >= 0 && close(fd) < 0)
1098+
result = 1;
1099+
if (control >= 0) {
1100+
if (fchmod(control, 0700) < 0)
1101+
result = 1;
1102+
if (unlinkat(control, "new", 0) < 0 && errno != ENOENT)
1103+
result = 1;
1104+
if (unlinkat(control, "known", 0) < 0 && errno != ENOENT)
1105+
result = 1;
1106+
if (close(control) < 0)
1107+
result = 1;
1108+
}
1109+
if (root >= 0) {
1110+
if (unlinkat(root, "link", 0) < 0 && errno != ENOENT)
1111+
result = 1;
1112+
if (unlinkat(root, "dir", AT_REMOVEDIR) < 0 && errno != ENOENT)
1113+
result = 1;
1114+
if (close(root) < 0)
1115+
result = 1;
1116+
}
1117+
if (cwd >= 0 && close(cwd) < 0)
1118+
result = 1;
1119+
if (rmdir(base) < 0 && errno != ENOENT)
1120+
result = 1;
1121+
return result;
1122+
}
1123+
1124+
int main(void)
1125+
{
1126+
const char *name = NULL;
1127+
#ifdef O_PATH
1128+
if (check_flag(O_PATH) == 0)
1129+
name = "O_PATH";
1130+
#endif
1131+
#ifdef O_SEARCH
1132+
if (!name && check_flag(O_SEARCH) == 0)
1133+
name = "O_SEARCH";
1134+
#endif
1135+
if (name) {
1136+
FILE *out = fopen("conftest.search-only", "w");
1137+
if (!out || fprintf(out, "%s\n", name) < 0 || fclose(out) < 0)
1138+
return 1;
1139+
return 0;
1140+
}
1141+
return 1;
1142+
}
1143+
]])],
1144+
[rsync_cv_search_only_dirfd_flag=`cat conftest.search-only`],
1145+
[rsync_cv_search_only_dirfd_flag=no],
1146+
[case "$host_os" in
1147+
linux*|android*)
1148+
AC_LINK_IFELSE([AC_LANG_PROGRAM([[
1149+
#define _GNU_SOURCE 1
1150+
#include <fcntl.h>
1151+
]], [[return openat(AT_FDCWD, ".", O_PATH | O_DIRECTORY | O_NOFOLLOW) < -1;]])],
1152+
[rsync_cv_search_only_dirfd_flag=O_PATH],
1153+
[rsync_cv_search_only_dirfd_flag=no])
1154+
;;
1155+
*) rsync_cv_search_only_dirfd_flag=no ;;
1156+
esac])
1157+
rm -f conftest.search-only
1158+
])
1159+
if test x"$rsync_cv_search_only_dirfd_flag" != x"no"; then
1160+
AC_DEFINE_UNQUOTED([SEARCH_ONLY_DIRFD_FLAG], [$rsync_cv_search_only_dirfd_flag],
1161+
[Open flag for race-safe search-only directory descriptors.])
1162+
fi
1163+
9951164
dnl cygwin iconv.h defines iconv_open as libiconv_open
9961165
if test x"$ac_cv_func_iconv_open" != x"yes"; then
9971166
AC_CHECK_FUNC(libiconv_open, [ac_cv_func_iconv_open=yes; AC_DEFINE(HAVE_ICONV_OPEN, 1)])

‎syscall.c‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,12 @@ extern char curr_dir[MAXPATHLEN]; /* defined below; fwd-declared for the seed */
7777
extern int operator_path_resolve; /* defined below; fwd-declared for the exclude check */
7878
extern int filesfrom_owner_walk_override; /* defined below; used by files-from implied dirs */
7979

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

749748
/* Open a directory for traversal or as *at()/fchdir() authority. Unlike an
750749
* O_RDONLY directory endpoint, this accepts a searchable but unreadable
751-
* directory on Linux. */
750+
* directory when the kernel provides a safe search-only descriptor. */
752751
int open_no_attacker_symlinks_dirfd(const char *path)
753752
{
754753
return ona_open(path, directory_traverse_flags(), 0, NULL, 0);

‎testsuite/search-only-destination_test.py‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,27 @@
11
#!/usr/bin/env python3
22
"""The receiver must traverse a searchable but unreadable destination parent.
33
4-
Android exposes /sdcard through such a path, so the race-safe destination walk
5-
must use directory descriptors that require search permission only.
4+
Android exposes /sdcard through such a path. Kernels which provide a race-safe
5+
search-only directory descriptor must therefore support this destination walk.
66
"""
77

8+
import json
89
import os
910
import shutil
1011
import subprocess
1112
import sys
1213
import tempfile
1314
from pathlib import Path
1415

15-
from rsyncfns import SCRATCHDIR, rmtree, rsync_argv, test_fail, test_skipped
16+
from rsyncfns import SCRATCHDIR, rmtree, rsync_argv, run_rsync, test_fail, test_skipped
1617

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

2021
launcher = []
2122
if os.geteuid() == 0:
23+
if not sys.platform.startswith('linux'):
24+
test_skipped('requires a non-root test process on this platform')
2225
setpriv = shutil.which('setpriv')
2326
if setpriv is None:
2427
test_skipped('setpriv is unavailable for the root-run testsuite')
@@ -61,6 +64,10 @@
6164
stderr=subprocess.PIPE,
6265
text=True,
6366
)
67+
if not search_only_dirs:
68+
if proc.returncode == 0 or (dest / 'probe').exists():
69+
test_fail('unsupported search-only traversal did not fail closed')
70+
test_skipped('kernel has no race-safe search-only directory descriptor')
6471
finally:
6572
parent.chmod(0o755)
6673
copied = (dest / 'probe').read_text() if (dest / 'probe').is_file() else None

‎testsuite/search-only-held-dirfd_test.py‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
"""Known-name operations must not require permission to list parent dirs.
33
44
The confined resolver holds directory descriptors to prevent symlink races.
5-
On Linux, those traversal and *at() anchor descriptors can use O_PATH: opening
6-
a known file beneath a searchable directory, or creating one beneath a
7-
writable/searchable directory, does not require directory read permission.
5+
Supported kernels provide a descriptor which can open a known file beneath a
6+
searchable directory or create one beneath a writable/searchable directory
7+
without requiring permission to list that directory.
88
"""
99

10+
import json
1011
import os
1112
import shutil
1213
import subprocess
@@ -15,14 +16,16 @@
1516
from pathlib import Path
1617

1718
from rsyncfns import (
18-
SCRATCHDIR, forced_protocol, rmtree, rsync_argv, test_fail, test_skipped,
19+
SCRATCHDIR, forced_protocol, rmtree, rsync_argv, run_rsync, test_fail, test_skipped,
1920
)
2021

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

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

106+
if not search_only_dirs:
107+
unsupported = subprocess.run(
108+
launcher + rsync_argv('-t', str(incoming), f'{write_only_dest}/'),
109+
stdout=subprocess.PIPE,
110+
stderr=subprocess.PIPE,
111+
text=True,
112+
)
113+
if unsupported.returncode == 0 or (write_only_dest / 'incoming').exists():
114+
test_fail('unsupported search-only traversal did not fail closed')
115+
test_skipped('kernel has no race-safe search-only directory descriptor')
116+
103117
# Keep received implied dirs usable on systems without a safe fchmodat2.
104118
# The source remains mode 0111, so sender traversal coverage is unchanged.
105119
exact = subprocess.run(

0 commit comments

Comments
 (0)