From bc2fd9796403e03bb757b064d44c22fab92e6842 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Thu, 4 Jan 2018 11:38:21 -0500
Subject: doc: warn about following symlinks recursively in chown/chgrp

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.
Warn about combining the --dereference, --recursive, and -L flags.

* doc/coreutils.texi (warnOptDerefWithRec): Add macro.
(node chown invocation): Add it to --dereference and -L.
(node chgrp invocation): Likewise.

See also: CVE-2017-18018
CVE: CVE-2017-18018
Upstream-Status: Backport from v8.30

Signed-off-by: Michael Orlitzky <michael@orlitzky.com>
Signed-off-by: Jagadeesh Krishnanjanappa <jkrishnanjanappa@mvista.com>
---
 doc/coreutils.texi | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 6bb9f09..9f5f95b 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1428,6 +1428,19 @@ a command line argument is a symbolic link to a directory, traverse it.
 In a recursive traversal, traverse every symbolic link to a directory
 that is encountered.
 @end macro
+
+@c Append the following warning to -L where appropriate (e.g. chown).
+@macro warnOptDerefWithRec
+
+Combining this dereferencing option with the @option{--recursive} option
+may create a security risk:
+During the traversal of the directory tree, an attacker may be able to
+introduce a symlink to an arbitrary target; when the tool reaches that,
+the operation will be performed on the target of that symlink,
+possibly allowing the attacker to escalate privileges.
+
+@end macro
+
 @choptL
 
 @macro choptP
@@ -10995,6 +11008,7 @@ 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.
+@warnOptDerefWithRec
 
 @item -h
 @itemx --no-dereference
@@ -11051,6 +11065,7 @@ Recursively change ownership of directories and their contents.
 @xref{Traversing symlinks}.
 
 @choptL
+@warnOptDerefWithRec
 @xref{Traversing symlinks}.
 
 @choptP
@@ -11125,6 +11140,7 @@ 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.
+@warnOptDerefWithRec
 
 @item -h
 @itemx --no-dereference
@@ -11180,6 +11196,7 @@ Recursively change the group ownership of directories and their contents.
 @xref{Traversing symlinks}.
 
 @choptL
+@warnOptDerefWithRec
 @xref{Traversing symlinks}.
 
 @choptP
-- 
cgit v1.0-41-gc330