[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 15/21: [docs]: Revise discussion of unsafe mode.
From: |
G. Branden Robinson |
Subject: |
[groff] 15/21: [docs]: Revise discussion of unsafe mode. |
Date: |
Sun, 6 Jun 2021 13:04:21 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 18acdc214a9473be8bee3d0bb57e7de4030003d4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jun 7 00:30:33 2021 +1000
[docs]: Revise discussion of unsafe mode.
* doc/groff.texi (Groff Options):
* src/roff/troff/troff.1.man (Options): Parallelize presentation of -U
option. Provide motivation in our Texinfo manual, and explain what
the risk is instead of saying, vaguely, "potentially dangerous".
* doc/groff_diff.7.man (Restricted requests): Add new section.
Prompted by an observation by Dave Kemper.
---
doc/groff.texi | 8 ++++++--
man/groff_diff.7.man | 27 +++++++++++++++++++++++++--
src/roff/troff/troff.1.man | 19 ++++++++++---------
3 files changed, 41 insertions(+), 13 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 2d51f91..d45dc61 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1294,8 +1294,12 @@ and Font Files}.) This can be overridden with the
@option{-X} option.
@item -U
@cindex mode, unsafe
@cindex unsafe mode
-Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
-@code{sy}, and @code{pi} requests.
+Operate in @dfn{unsafe mode}, which enables the @code{open},
+@code{opena}, @code{pi}, @code{pso}, and @code{sy} requests. These
+requests are disabled by default because they allow an untrusted input
+document to write to arbitrary file names and run arbitrary commands.
+This option also adds the current directory to the macro search path;
+see the @option{-m} option above.
@item -w@var{name}
Enable warning @var{name}. Available warnings are described in
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 35f0a46..f539b24 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -935,6 +935,26 @@ inter-word space when a line is adjusted.
.
.
.\" ====================================================================
+.SS "Restricted requests"
+.\" ====================================================================
+.
+To mitigate risks from untrusted input documents,
+the
+.BR open ,
+.BR opena ,
+.BR pi ,
+.BR pso ,
+and
+.B sy
+requests are disabled by default.
+.
+.IR \%@g@troff (@MAN1EXT@)'s
+.B \-U
+option enables the formatter's \[lq]unsafe mode\[rq],
+restoring their function.
+.
+.
+.\" ====================================================================
.SS "New requests"
.\" ====================================================================
.
@@ -3875,13 +3895,16 @@ Useful in conjunction with the
.B \[rs]n[.ne]
register.
.
+.
.TP
.B \[rs]n[.U]
-Set to\~1 if in safer mode and to\~0 if in unsafe mode (as given with
-the
+Set to\~1 if in safer mode and to\~0 if in unsafe mode
+(as determined by
+.IR \%@g@troff 's
.B \-U
command-line option).
.
+.
.TP
.B \[rs]n[.vpt]
1\~if vertical position traps are enabled, 0\~otherwise.
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index c44227f..cd0ead4 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -362,23 +362,24 @@ for a more detailed description.
.TP
.B \-U
Operate in
-.IR "unsafe mode" ;
-enabling the
+.IR "unsafe mode" ,
+which enables the
.BR .open ,
.BR .opena ,
+.BR .pi ,
.BR .pso ,
-.BR .sy ,
and
-.B .pi
+.B .sy
requests.
.
-For security reasons,
-these potentially dangerous requests are disabled otherwise.
+These requests are disabled by default because they allow an untrusted
+input document to write to arbitrary file names and run arbitrary
+commands.
.
-It also adds the current directory to the macro search path;
-see
+This option also adds the current directory to the macro search path;
+see the
.B \-m
-above.
+option above.
.
.
.TP
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 15/21: [docs]: Revise discussion of unsafe mode.,
G. Branden Robinson <=