[PATCH v2 2/2] doc: warn about following symlinks recursively in chown/chgrp

[Michael Orlitzky]

* doc/coreutils.texi: In both chown and chgrp (which shares
  its code with chown), operating on symlinks recursively
  has a window of vulnerability where the destination user
  or group can change the target of the operation. This commit
  warns about combining the --dereference, --recursive, and -L
  flags.
---
 doc/coreutils.texi | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 1c0e8a36c..809366ada 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1427,6 +1427,13 @@ a command line argument is a symbolic link to a 
directory, traverse it.
 @cindex symbolic link to directory, traverse each that is encountered
 In a recursive traversal, traverse every symbolic link to a directory
 that is encountered.
+This option creates a security risk. In the presence of symlinks, the
+traversal is not guaranteed to be performed depth-first. As a result,
+there is a race condition: an attacker may be able to introduce a
+symlink at a point in the traversal that has yet to be reached. When
+it is reached, the operation will be performed on the target of that,
+symlink, possibly allowing the attacker to escalate his privileges.
+
 @end macro
 @choptL
 
@@ -10990,6 +10997,14 @@ chown -h -R --from=OLDUSER NEWUSER /
 @findex lchown
 Do not act on symbolic links themselves but rather on what they point to.
 This is the default when not operating recursively.
+Combining this option with @option{--recursive} (@option{-R}) creates
+a security risk. In the presence of symlinks, the recursive directory
+traversal is not guaranteed to be performed depth-first. As a result,
+there is a race condition: the @var{new-owner} may be able to
+introduce a symlink at a point in the traversal that has yet to be
+reached. When it is reached, @code{chown} will be performed on the
+target of that symlink---a situation that is often exploitable to
+gain root privileges.
 
 @item -h
 @itemx --no-dereference
@@ -11120,6 +11135,14 @@ changed.
 @findex lchown
 Do not act on symbolic links themselves but rather on what they point to.
 This is the default when not operating recursively.
+Combining this option with @option{--recursive} (@option{-R}) creates
+a security risk. In the presence of symlinks, the recursive directory
+traversal is not guaranteed to be performed depth-first. As a result,
+there is a race condition: a member of @var{group} may be able to
+introduce a symlink at a point in the traversal that has yet to be
+reached. When it is reached, @code{chgrp} will be performed on the
+target of that symlink---a situation that is often exploitable to
+escalate privileges.
 
 @item -h
 @itemx --no-dereference
-- 
2.13.6