From 8808d5a2b20e45f9947a3362a20383d8f5d29ef6 Mon Sep 17 00:00:00 2001 From: binarycat Date: Tue, 8 Apr 2025 12:27:33 -0500 Subject: [PATCH 1/2] std(docs): clarify how std::fs::set_permisions works with symlinks fixes https://github.com/rust-lang/rust/issues/75942 fixes https://github.com/rust-lang/rust/issues/124201 --- library/std/src/fs.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs index 801baf3d990..1fe180066ce 100644 --- a/library/std/src/fs.rs +++ b/library/std/src/fs.rs @@ -2980,6 +2980,19 @@ pub fn read_dir>(path: P) -> io::Result { /// /// [changes]: io#platform-specific-behavior /// +/// # Symlinks +/// On UNIX systems, it is impossible to manipulate the permission bits of a symlink itself[^1]. +/// Because of this, on those systems, this function will update the permission bits +/// of the file pointed to by the symlink. +/// +/// Note that this behavior can lead to privalage escalation vulnerabilites, +/// where the ability to write a symlink in one directory allows you to +/// cause the permissions of another directory to be modified. +/// +/// For this reason, using this function with symlinks should be avoided. +/// When possible, permissions should be set at creation time instead. +/// +/// [^1]: even if it were possible, the permissions on a symlink are ignored. /// # Errors /// /// This function will return an error in the following situations, but is not From 37c4a37ca2d94047b984aa16a95800b48255d327 Mon Sep 17 00:00:00 2001 From: binarycat Date: Tue, 8 Apr 2025 15:07:08 -0500 Subject: [PATCH 2/2] clarify std::fs::set_permissions symlink behavior nest under platform-specific behavior, factor rationale into its own section, and tweak language. --- library/std/src/fs.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs index 1fe180066ce..3340a5dc23d 100644 --- a/library/std/src/fs.rs +++ b/library/std/src/fs.rs @@ -2980,19 +2980,21 @@ pub fn read_dir>(path: P) -> io::Result { /// /// [changes]: io#platform-specific-behavior /// -/// # Symlinks -/// On UNIX systems, it is impossible to manipulate the permission bits of a symlink itself[^1]. -/// Because of this, on those systems, this function will update the permission bits +/// ## Symlinks +/// On UNIX-like systems, this function will update the permission bits /// of the file pointed to by the symlink. /// /// Note that this behavior can lead to privalage escalation vulnerabilites, -/// where the ability to write a symlink in one directory allows you to -/// cause the permissions of another directory to be modified. +/// where the ability to create a symlink in one directory allows you to +/// cause the permissions of another file or directory to be modified. /// /// For this reason, using this function with symlinks should be avoided. /// When possible, permissions should be set at creation time instead. /// -/// [^1]: even if it were possible, the permissions on a symlink are ignored. +/// # Rationale +/// POSIX does not specify an `lchown` function, +/// and symlinks can be followed regardless of what permission bits are set. +/// /// # Errors /// /// This function will return an error in the following situations, but is not